@kortix/ui 0.0.0-stage → 0.14.4

package/dist/markdown/setup-links/util.d.ts

@@ -0,0 +1,80 @@
+import { type LinkInfoStorage, type SecretSetupLinkSubmitResult } from '@kortix/sdk';
+/**
+ * The browser storage the SDK's connector link-info cache persists through, or
+ * null outside a browser or when storage is blocked (private mode). The SDK
+ * owns the cache policy; the host owns the DOM access.
+ */
+export declare function browserLinkInfoStorage(): LinkInfoStorage | null;
+/**
+ * Maps a failed setup-link request to the state the human should see. The API
+ * distinguishes an expired link (410 — expected, recoverable by re-minting)
+ * from an unknown/mangled one (404 — usually a truncated copy); collapsing
+ * both into one generic "invalid" message left humans stuck with no way
+ * forward.
+ */
+export declare function classifySetupLinkError(cause: unknown): 'expired' | 'invalid' | 'network';
+/** "6 days" / "3 hours" / "25 minutes" until the link dies; null once past. */
+export declare function describeLinkExpiry(expiresAtIso: string, nowMs: number): string | null;
+export type TextLinkPart = {
+    type: 'text';
+    value: string;
+} | {
+    type: 'link';
+    href: string;
+    label: string;
+};
+/**
+ * Splits agent-written field hints ("Create one at https://…") into text and
+ * link parts, so the form renders the URL as a real link instead of dead text.
+ */
+export declare function splitTextLinks(text: string): TextLinkPart[];
+export type SetupLinkKind = 'secret' | 'connector';
+/**
+ * Recognize an agent-minted setup link. The agent emits an ABSOLUTE url
+ * (`${FRONTEND_URL}/secret-intake/<token>` or `/connect/<token>`) so it stays a
+ * plain tappable link in Slack; inside the web app that origin equals our own,
+ * so we intercept it and render an in-app modal instead of navigating away.
+ */
+export declare function parseSetupLinkHref(href?: string): {
+    kind: SetupLinkKind;
+    token: string;
+} | null;
+/**
+ * The kind of setup link a URL that is still streaming will become, or null.
+ *
+ * `parseSetupLinkHref` needs the whole token. This answers as soon as the path
+ * names a setup route, and applies the same origin rule to the part so far: a
+ * cross-origin URL counts only while its token can still start with `ksl_`.
+ */
+export declare function partialSetupLinkKind(partial: string): SetupLinkKind | null;
+export declare function pendingSetupLinkHref(kind: SetupLinkKind): string;
+export declare function parsePendingSetupLinkHref(href?: string): SetupLinkKind | null;
+/**
+ * Streaming text that ends inside a setup link, with that link held as pending.
+ *
+ * A setup token is several hundred characters, so the link takes a second or
+ * two to stream. Until the closing paren arrives, the open link is rewritten
+ * to `[label](<pending href>)`: the renderer shows the card it will become,
+ * with nothing to click, instead of raw `[label](` text or a card built from a
+ * partial token. Every other text passes through unchanged.
+ */
+export declare function holdPendingSetupLink(markdown: string): string;
+/**
+ * Agents usually emit the setup link as a bare URL, so the markdown link text
+ * IS the URL — a few hundred opaque token characters. That never belongs on
+ * the chip. Only keep the author's text when it reads like a human label.
+ */
+export declare function setupLinkChipLabel(raw: string, token: string, fallback: string): string;
+/**
+ * The one outcome the human must still act on: the value is saved, but the
+ * agent that asked for it is not allowed to receive it. Said on the form
+ * because it is the only moment the human is present — the agent otherwise
+ * reports the secret as unset and the human re-enters a value already saved.
+ * Returns structure only; the form renders it through the locale catalog
+ * (`hardcodedUi.secretIntakeWithheld`).
+ */
+export declare function describeWithheldSecrets(result: Pick<SecretSetupLinkSubmitResult, 'agent' | 'withheld'>): {
+    agent: string;
+    byGrant: string[];
+    byAllowlist: string[];
+} | null;

package/dist/markdown/setup-links/util.js

@@ -0,0 +1,220 @@
+import { HostBoundaryError } from '@kortix/sdk';
+import { openMarkdownLinkAtEnd } from '../../_vendor/kortix-shared.js';
+/**
+ * The browser storage the SDK's connector link-info cache persists through, or
+ * null outside a browser or when storage is blocked (private mode). The SDK
+ * owns the cache policy; the host owns the DOM access.
+ */
+export function browserLinkInfoStorage() {
+    try {
+        return typeof window === 'undefined' ? null : window.localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Maps a failed setup-link request to the state the human should see. The API
+ * distinguishes an expired link (410 — expected, recoverable by re-minting)
+ * from an unknown/mangled one (404 — usually a truncated copy); collapsing
+ * both into one generic "invalid" message left humans stuck with no way
+ * forward.
+ */
+export function classifySetupLinkError(cause) {
+    const status = cause instanceof HostBoundaryError
+        ? cause.status
+        : typeof cause?.status === 'number'
+            ? cause.status
+            : null;
+    if (status === 410)
+        return 'expired';
+    if (status === 404 || status === 400)
+        return 'invalid';
+    return 'network';
+}
+/** "6 days" / "3 hours" / "25 minutes" until the link dies; null once past. */
+export function describeLinkExpiry(expiresAtIso, nowMs) {
+    const expiresMs = Date.parse(expiresAtIso);
+    if (Number.isNaN(expiresMs) || expiresMs <= nowMs)
+        return null;
+    const minutes = Math.round((expiresMs - nowMs) / 60_000);
+    if (minutes >= 2 * 24 * 60)
+        return `${Math.round(minutes / (24 * 60))} days`;
+    if (minutes >= 2 * 60)
+        return `${Math.round(minutes / 60)} hours`;
+    if (minutes >= 2)
+        return `${minutes} minutes`;
+    return 'less than 2 minutes';
+}
+/**
+ * `[label](https://…)` or a bare `https://…`. http(s) only: this runs on
+ * agent-written text, which must never become a `javascript:` href.
+ */
+const TEXT_LINK_PATTERN = /\[([^\]\n]+)\]\((https?:\/\/[^\s)]+)\)|https?:\/\/[^\s<>]+/g;
+const MAX_LINKED_TEXT = 2_000;
+/** Prose punctuation that ends a sentence after a bare URL but is not part of it. */
+const URL_TRAILING_PUNCTUATION = /[.,;:!?'")\]]+$/;
+/**
+ * Splits agent-written field hints ("Create one at https://…") into text and
+ * link parts, so the form renders the URL as a real link instead of dead text.
+ */
+export function splitTextLinks(text) {
+    // ponytail: TEXT_LINK_PATTERN and URL_TRAILING_PUNCTUATION backtrack
+    // quadratically on a long run of `[` or `!` (CodeQL js/polynomial-redos). A
+    // hint is one or two sentences; past MAX_LINKED_TEXT it renders as plain
+    // text. Replace the regexes with a scanner if hints ever need to be longer.
+    if (text.length > MAX_LINKED_TEXT)
+        return [{ type: 'text', value: text }];
+    const parts = [];
+    let cursor = 0;
+    for (const match of text.matchAll(TEXT_LINK_PATTERN)) {
+        const start = match.index ?? 0;
+        const [whole, markdownLabel, markdownHref] = match;
+        const href = markdownHref ?? whole.replace(URL_TRAILING_PUNCTUATION, '');
+        const label = markdownLabel ?? href.replace(/^https?:\/\/(www\.)?/, '').replace(/\/$/, '');
+        if (start > cursor)
+            parts.push({ type: 'text', value: text.slice(cursor, start) });
+        parts.push({ type: 'link', href, label: label || href });
+        cursor = start + (markdownHref ? whole.length : href.length);
+    }
+    if (cursor < text.length)
+        parts.push({ type: 'text', value: text.slice(cursor) });
+    return parts;
+}
+/**
+ * Recognize an agent-minted setup link. The agent emits an ABSOLUTE url
+ * (`${FRONTEND_URL}/secret-intake/<token>` or `/connect/<token>`) so it stays a
+ * plain tappable link in Slack; inside the web app that origin equals our own,
+ * so we intercept it and render an in-app modal instead of navigating away.
+ */
+export function parseSetupLinkHref(href) {
+    if (!href)
+        return null;
+    let pathname = href;
+    let sameOrigin = true;
+    if (/^https?:\/\//i.test(href)) {
+        try {
+            const u = new URL(href);
+            sameOrigin = typeof window === 'undefined' || u.origin === window.location.origin;
+            pathname = u.pathname;
+        }
+        catch {
+            return null;
+        }
+    }
+    const m = pathname.match(/^\/(secret-intake|connect)\/([^/?#]+)/);
+    if (!m)
+        return null;
+    const token = decodeURIComponent(m[2]);
+    // Links are minted against FRONTEND_URL, which can differ from the origin the
+    // app is being viewed on (staging, preview deploys, self-host behind another
+    // domain). A cross-origin URL is still ours when it carries the `ksl_` wire
+    // prefix — the token is HMAC-verified server-side, so intercepting can never
+    // hand a foreign form our data. Anything else stays a plain link.
+    if (!sameOrigin && !token.startsWith('ksl_'))
+        return null;
+    return { kind: m[1] === 'secret-intake' ? 'secret' : 'connector', token };
+}
+/**
+ * The kind of setup link a URL that is still streaming will become, or null.
+ *
+ * `parseSetupLinkHref` needs the whole token. This answers as soon as the path
+ * names a setup route, and applies the same origin rule to the part so far: a
+ * cross-origin URL counts only while its token can still start with `ksl_`.
+ */
+export function partialSetupLinkKind(partial) {
+    const text = partial.trim();
+    let pathname = text;
+    let sameOrigin = true;
+    if (/^https?:\/\//i.test(text)) {
+        try {
+            const u = new URL(text);
+            sameOrigin = typeof window === 'undefined' || u.origin === window.location.origin;
+            pathname = u.pathname;
+        }
+        catch {
+            return null;
+        }
+    }
+    const m = pathname.match(/^\/(secret-intake|connect)\/([^/?#]*)/);
+    if (!m)
+        return null;
+    const token = m[2];
+    if (!sameOrigin && !('ksl_'.startsWith(token) || token.startsWith('ksl_')))
+        return null;
+    return m[1] === 'secret-intake' ? 'secret' : 'connector';
+}
+/**
+ * The href a setup link carries while its URL is still streaming. A fragment,
+ * so sanitize and rehype-harden pass it unchanged and it can never navigate.
+ */
+const PENDING_SETUP_LINK_HREF = '#kortix-setup-link-pending:';
+export function pendingSetupLinkHref(kind) {
+    return `${PENDING_SETUP_LINK_HREF}${kind}`;
+}
+export function parsePendingSetupLinkHref(href) {
+    if (!href?.startsWith(PENDING_SETUP_LINK_HREF))
+        return null;
+    const kind = href.slice(PENDING_SETUP_LINK_HREF.length);
+    return kind === 'secret' || kind === 'connector' ? kind : null;
+}
+/**
+ * Streaming text that ends inside a setup link, with that link held as pending.
+ *
+ * A setup token is several hundred characters, so the link takes a second or
+ * two to stream. Until the closing paren arrives, the open link is rewritten
+ * to `[label](<pending href>)`: the renderer shows the card it will become,
+ * with nothing to click, instead of raw `[label](` text or a card built from a
+ * partial token. Every other text passes through unchanged.
+ */
+export function holdPendingSetupLink(markdown) {
+    const open = openMarkdownLinkAtEnd(markdown);
+    // A label with brackets inside cannot be re-emitted safely. It keeps the
+    // generic streaming-link path.
+    if (!open || open.label.includes('[') || open.label.includes(']'))
+        return markdown;
+    // `[label](https://…/connect/ksl_…` is arriving, or the label itself is the
+    // setup URL: `[https://…/connect/ksl_…`.
+    const kind = partialSetupLinkKind(open.destination ?? open.label);
+    if (!kind)
+        return markdown;
+    // A label that is the URL renders as the card's fallback title, as the
+    // finished link would.
+    const label = open.destination === null ? '' : open.label;
+    return `${markdown.slice(0, open.start)}[${label}](${pendingSetupLinkHref(kind)})`;
+}
+/**
+ * Agents usually emit the setup link as a bare URL, so the markdown link text
+ * IS the URL — a few hundred opaque token characters. That never belongs on
+ * the chip. Only keep the author's text when it reads like a human label.
+ */
+export function setupLinkChipLabel(raw, token, fallback) {
+    const text = raw.trim();
+    if (!text)
+        return fallback;
+    const looksLikeUrl = /^https?:\/\//i.test(text) ||
+        // No token while the URL is still streaming, and '' is in every string.
+        (token !== '' && text.includes(token)) ||
+        text.includes('/secret-intake/') ||
+        text.includes('/connect/') ||
+        (text.length > 48 && !text.includes(' '));
+    return looksLikeUrl ? fallback : text;
+}
+/**
+ * The one outcome the human must still act on: the value is saved, but the
+ * agent that asked for it is not allowed to receive it. Said on the form
+ * because it is the only moment the human is present — the agent otherwise
+ * reports the secret as unset and the human re-enters a value already saved.
+ * Returns structure only; the form renders it through the locale catalog
+ * (`hardcodedUi.secretIntakeWithheld`).
+ */
+export function describeWithheldSecrets(result) {
+    const withheld = result.withheld ?? [];
+    if (!result.agent || withheld.length === 0)
+        return null;
+    return {
+        agent: result.agent,
+        byGrant: withheld.filter((w) => w.reason === 'agent_grant').map((w) => w.name),
+        byAllowlist: withheld.filter((w) => w.reason === 'session_allowlist').map((w) => w.name),
+    };
+}

package/dist/markdown/stream-words.d.ts

@@ -0,0 +1,68 @@
+import { type ReactNode } from 'react';
+/** The class a streamed word carries; `styles/components.css` fades it in once, on mount. */
+export declare const STREAM_WORD_CLASS = "kx-stream-word";
+/** The slice of hast this plugin reads; `@types/hast` is not a dependency of the app. */
+interface HastText {
+    type: 'text';
+    value: string;
+}
+interface HastElement {
+    type: 'element';
+    tagName: string;
+    properties?: {
+        className?: unknown;
+    };
+    children: HastNode[];
+}
+type HastNode = HastText | HastElement | {
+    type: string;
+    children?: HastNode[];
+};
+interface HastParent {
+    children: HastNode[];
+}
+/**
+ * Rehype plugin for a message that is still streaming: every prose word
+ * becomes its own `<span class="kx-stream-word">`.
+ *
+ * React keeps the DOM node of a word that was already on screen, so only the
+ * words a render adds mount, and only they run the fade. That turns the step
+ * between two paced renders into a soft fill instead of a pop. Only opacity
+ * animates: no layout, no glyph repaint. Once the stream ends the plugin is
+ * dropped and the message renders as plain text, the same as from history.
+ */
+export declare function rehypeStreamWords(): (tree: HastParent) => void;
+/**
+ * The window the words of one render are spread across.
+ *
+ * The pacer renders about every 32 ms (`STREAM_COMMIT_MS`), and one render
+ * at a fast model's speed adds ~3 words. Fading those in on the same frame
+ * reads as a lump every 32 ms. Spreading their start times across the gap
+ * until the next render makes each word arrive on its own, so the fill is
+ * continuous at the display's frame rate while React renders at half of it.
+ */
+export declare const STREAM_STAGGER_WINDOW_MS = 40;
+/**
+ * One message's fade gate. A message that mounts mid-stream (a session switch,
+ * a reload, a remount) already holds its text: the reader has it, it is not
+ * arriving. The words and block chrome of the first render that has words
+ * therefore show without the fade, and the gate opens for the words after
+ * them. `UnifiedMarkdown` creates one per message, open for a message that
+ * mounts settled.
+ *
+ * The gate takes a word as it mounts. It returns true when the word shows at
+ * once; it has then already turned off that word's fade.
+ */
+export type StreamFadeGate = (word: HTMLElement) => boolean;
+export declare function createStreamFadeGate(open: boolean): StreamFadeGate;
+export declare const StreamFadeGateContext: import("react").Context<StreamFadeGate | null>;
+/**
+ * One streamed word. Its layout effect runs once, on mount, with every other
+ * word the same render mounted; the microtask then gives each its delay
+ * before the browser paints. A word already on screen keeps its node, so it
+ * never fades again.
+ */
+export declare function StreamWord({ children }: {
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export {};

package/dist/markdown/stream-words.js

@@ -0,0 +1,113 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useLayoutEffect, useRef } from 'react';
+import { isKatexClassName } from './katex-markdown.js';
+/** The class a streamed word carries; `styles/components.css` fades it in once, on mount. */
+export const STREAM_WORD_CLASS = 'kx-stream-word';
+/** Subtrees whose text is not prose: code renders its own string, math and SVG are layout. */
+const OPAQUE_TAGS = new Set(['code', 'pre', 'svg', 'math', 'script', 'style']);
+function wordSpan(value) {
+    return {
+        type: 'element',
+        tagName: 'span',
+        properties: { className: [STREAM_WORD_CLASS] },
+        children: [{ type: 'text', value }],
+    };
+}
+function wrapWords(node) {
+    const out = [];
+    for (const child of node.children) {
+        if (child.type === 'text') {
+            for (const part of child.value.split(/(\s+)/)) {
+                if (!part)
+                    continue;
+                out.push(/\s/.test(part[0]) ? { type: 'text', value: part } : wordSpan(part));
+            }
+            continue;
+        }
+        if (child.type === 'element') {
+            const el = child;
+            const className = el.properties?.className;
+            if (!OPAQUE_TAGS.has(el.tagName) && !isKatexClassName(className))
+                wrapWords(el);
+        }
+        out.push(child);
+    }
+    node.children = out;
+}
+/**
+ * Rehype plugin for a message that is still streaming: every prose word
+ * becomes its own `<span class="kx-stream-word">`.
+ *
+ * React keeps the DOM node of a word that was already on screen, so only the
+ * words a render adds mount, and only they run the fade. That turns the step
+ * between two paced renders into a soft fill instead of a pop. Only opacity
+ * animates: no layout, no glyph repaint. Once the stream ends the plugin is
+ * dropped and the message renders as plain text, the same as from history.
+ */
+export function rehypeStreamWords() {
+    return (tree) => wrapWords(tree);
+}
+/**
+ * The window the words of one render are spread across.
+ *
+ * The pacer renders about every 32 ms (`STREAM_COMMIT_MS`), and one render
+ * at a fast model's speed adds ~3 words. Fading those in on the same frame
+ * reads as a lump every 32 ms. Spreading their start times across the gap
+ * until the next render makes each word arrive on its own, so the fill is
+ * continuous at the display's frame rate while React renders at half of it.
+ */
+export const STREAM_STAGGER_WINDOW_MS = 40;
+/** Words mounted in the current render, in document order. */
+let mounting = [];
+function staggerMounting() {
+    const step = STREAM_STAGGER_WINDOW_MS / mounting.length;
+    for (let i = 1; i < mounting.length; i++) {
+        mounting[i].style.animationDelay = `${(i * step).toFixed(1)}ms`;
+    }
+    mounting = [];
+}
+/** Block chrome that fades on mount while streaming (`globals.css`, `.streaming-active`). */
+const FADING_CHROME = 'li, figure, hr, blockquote, .kx-md-table';
+export function createStreamFadeGate(open) {
+    let closing = false;
+    return (word) => {
+        if (open)
+            return false;
+        word.style.animation = 'none';
+        if (!closing) {
+            closing = true;
+            // After every word of this commit, before the paint.
+            queueMicrotask(() => {
+                open = true;
+                word
+                    .closest('.kortix-markdown')
+                    ?.querySelectorAll(FADING_CHROME)
+                    .forEach((node) => (node.style.animation = 'none'));
+            });
+        }
+        return true;
+    };
+}
+export const StreamFadeGateContext = createContext(null);
+/**
+ * One streamed word. Its layout effect runs once, on mount, with every other
+ * word the same render mounted; the microtask then gives each its delay
+ * before the browser paints. A word already on screen keeps its node, so it
+ * never fades again.
+ */
+export function StreamWord({ children }) {
+    const ref = useRef(null);
+    const gate = useContext(StreamFadeGateContext);
+    useLayoutEffect(() => {
+        const el = ref.current;
+        if (!el || gate?.(el))
+            return;
+        if (mounting.length === 0)
+            queueMicrotask(staggerMounting);
+        mounting.push(el);
+        // The gate is fixed for this message's lifetime; a word reads it once, on mount.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return (_jsx("span", { ref: ref, className: STREAM_WORD_CLASS, children: children }));
+}

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

@@ -0,0 +1,68 @@
+/**
+ * The text Streamdown parses: KaTeX delimiters normalised, system tags removed,
+ * bare URLs linked. Currency escaping skips code, so a fence (a generative UI
+ * block's `"$10"`, a shell `$1`) reaches its renderer as written.
+ *
+ * While the message streams, a setup link whose URL is still arriving is held
+ * as a pending card first (`holdPendingSetupLink`), so the reader never sees
+ * its raw `[label](` or a card built from a partial token. Settled text is
+ * never held.
+ */
+export declare function prepareMarkdownSource(content: string, isStreaming: boolean): string;
+/**
+ * Does this markdown define a reference-style link target (`[1]: https://…`)?
+ *
+ * Streamdown parses a streaming message block by block, and a definition in
+ * one block cannot resolve a `[text][1]` in another: the reference renders as
+ * raw brackets. A message with a definition is therefore parsed whole, which is
+ * what Streamdown already does for footnotes. A definition inside a fence or
+ * display math is code the message shows, not a target, so it does not keep
+ * the text whole (`hasReferenceDefinitionOutsideFences`).
+ */
+export declare function hasLinkReferenceDefinition(markdown: string): boolean;
+/**
+ * Is this href Streamdown's stand-in for a URL that has not arrived yet?
+ *
+ * While a message streams, Streamdown's `remend` closes a half-written link as
+ * `[label](streamdown:incomplete-link)` so the label renders before the URL is
+ * complete. That href is not a destination. It must never become an anchor.
+ */
+export declare function isStreamingLinkPlaceholder(href: string | undefined): boolean;
+/** Same-origin link? Internal links route through next/link; the rest open externally. */
+export declare function isInternalUrl(href: string | undefined): boolean;
+/**
+ * The host a markdown image would be fetched from, when that host is not this
+ * app. `null` for a same-origin or relative source, for `data:` and `blob:`,
+ * and for a source the sandbox proxy rewrote (`proxiedSrc !== src`): that is
+ * the session's own file served through the API, not a third party.
+ *
+ * The URL is resolved against the page exactly as the browser will fetch it,
+ * so protocol-relative (`//host`), backslash (`\\host`), padded and
+ * mixed-case forms are classified by where they actually point. Anything that
+ * resolves off this origin is remote; a source that does not parse is too.
+ */
+export declare function remoteImageHost(src: string, proxiedSrc?: string): string | null;
+/**
+ * Can this href be handed to `next/link` without crashing the prefetch path?
+ *
+ * Next.js' app-router `createPrefetchURL` (in `app-router.tsx`) does
+ * `new URL(addBasePath(href), window.location.href)` and, on failure, throws
+ * `Cannot prefetch '<href>' because it cannot be converted to a URL.` — which
+ * fires whenever a `<Link>` carrying a malformed absolute href scrolls into
+ * view (segment-cache `pingVisibleLinks`). A valid external URL is fine
+ * (`isExternalURL` short-circuits prefetch); only URLs that fail `new URL()`
+ * blow up, e.g. `http://:` (an empty host/port template like
+ * `http://${HOST}:${PORT}` that leaked unsubstituted from content).
+ *
+ * Internal (`/`, `#`, `?`) and bare-relative hrefs are always safe. We only
+ * reject protocol-prefixed hrefs that don't parse, so the renderer can fall
+ * back to a plain `<a>` and never feed garbage to `next/link`.
+ */
+export declare function isLinkSafeHref(href: string | undefined): boolean;
+/** Route only trusted app paths through Next.js Link and its prefetcher. */
+export declare function shouldUseNextLink(href: string | undefined): boolean;
+export { LANGUAGE_ALIASES, normalizeLanguage, languageLabel } from '../_vendor/shared/code-language.js';
+/** Does this inline-code text look like a clickable URL? */
+export declare function looksLikeUrl(text: string): boolean;
+/** Does this inline-code text look like a file path we can open in a preview? */
+export declare function looksLikeFilePath(text: string): boolean;