@kortix/ui 0.14.11 → 0.14.13

package/dist/internal/notifications/notification-rows.d.ts

@@ -26,16 +26,23 @@ export declare function newArrivals(seen: ReadonlySet<string> | null, rows: read
     seen: Set<string>;
 };
 /**
- * How new rows reach a person who is looking at this window: a toast for each
- * (at most `MAX_ARRIVAL_ALERTS`), or, when `os` (the window is in the
- * background, browser notifications are on and granted, and this renderer has
- * no Web Push), an OS notification instead. A row about the session on screen
- * is skipped. So is a finished turn the live stream already announced
- * (`unseen`); a later question, permission request or error in that session
- * is not.
+ * How new rows reach a person, at most `MAX_ARRIVAL_ALERTS` per poll. A finished
+ * turn the live stream already announced (`unseen`) is dropped on both paths; a
+ * later question, permission request or error in that session is not.
+ *
+ * When `os` (the window is in the background, browser notifications are on and
+ * granted, and this renderer has no Web Push), every other row goes to the OS
+ * path: `sendWebNotification` applies the channel policy to it.
+ *
+ * Otherwise each row toasts, except a row of any kind about the session on
+ * screen, and a row about a project other than the one on screen.
+ * `showInAppNotification` applies no policy, so both filters live here. They
+ * run before the cap, so a row that never toasts takes no slot from a row that
+ * does.
  */
 export declare function planArrivals(fresh: readonly InboxNotification[], context: {
     onScreen: (sessionId: string) => boolean;
+    otherProject: (projectId: string | null) => boolean;
     unseen: readonly string[];
     os: boolean;
 }): {

package/dist/internal/notifications/notification-rows.js

@@ -35,22 +35,27 @@ export function newArrivals(seen, rows) {
     return { fresh: rows.filter((row) => !row.read && !seen.has(row.id)), seen: next };
 }
 /**
- * How new rows reach a person who is looking at this window: a toast for each
- * (at most `MAX_ARRIVAL_ALERTS`), or, when `os` (the window is in the
- * background, browser notifications are on and granted, and this renderer has
- * no Web Push), an OS notification instead. A row about the session on screen
- * is skipped. So is a finished turn the live stream already announced
- * (`unseen`); a later question, permission request or error in that session
- * is not.
+ * How new rows reach a person, at most `MAX_ARRIVAL_ALERTS` per poll. A finished
+ * turn the live stream already announced (`unseen`) is dropped on both paths; a
+ * later question, permission request or error in that session is not.
+ *
+ * When `os` (the window is in the background, browser notifications are on and
+ * granted, and this renderer has no Web Push), every other row goes to the OS
+ * path: `sendWebNotification` applies the channel policy to it.
+ *
+ * Otherwise each row toasts, except a row of any kind about the session on
+ * screen, and a row about a project other than the one on screen.
+ * `showInAppNotification` applies no policy, so both filters live here. They
+ * run before the cap, so a row that never toasts takes no slot from a row that
+ * does.
  */
 export function planArrivals(fresh, context) {
     const unseen = new Set(context.unseen);
-    const announce = fresh
-        .filter((row) => !row.session_id ||
-        (!context.onScreen(row.session_id) &&
-            !(row.kind === 'turn_done' && unseen.has(row.session_id))))
-        .slice(0, MAX_ARRIVAL_ALERTS);
-    return context.os ? { toast: [], os: announce } : { toast: announce, os: [] };
+    const announce = fresh.filter((row) => !(row.session_id && row.kind === 'turn_done' && unseen.has(row.session_id)));
+    if (context.os)
+        return { toast: [], os: announce.slice(0, MAX_ARRIVAL_ALERTS) };
+    const toast = announce.filter((row) => !(row.session_id && context.onScreen(row.session_id)) && !context.otherProject(row.project_id));
+    return { toast: toast.slice(0, MAX_ARRIVAL_ALERTS), os: [] };
 }
 /** The in-page notification type: the push `type` of the kind. */
 export function webNotificationType(row) {
@@ -77,7 +82,9 @@ export function rowDestination(row) {
         return 'room';
     if (row.session_id)
         return 'session';
-    return new URL(row.url, 'http://kortix.invalid').pathname.endsWith('/reminders') ? 'reminders' : 'triggers';
+    const path = new URL(row.url, 'http://kortix.invalid').pathname;
+    // `/admin/loops` since 2026-10-28; a row stored before carries `/reminders`.
+    return path.endsWith('/admin/loops') || path.endsWith('/reminders') ? 'reminders' : 'triggers';
 }
 /** The message `public/sw.js` posts to a tab already on a clicked notification's page. */
 export const NOTIFICATION_OPEN_MESSAGE = 'kortix:notification-open';

package/dist/internal/notifications/session-toast-cards.d.ts

@@ -2,12 +2,12 @@
 export declare function SessionFailedCard({ title, label, detail, openLabel, onOpen, onDismiss, }: {
     /** "Session error". */
     title: string;
-    /** The session's name — only when it is not the one on screen. */
+    /** The session's name. `/debug/toasts` draws the card without it. */
     label?: string;
     /** The sentence the transcript's error row shows. */
     detail?: string;
     openLabel: string;
-    /** Absent for the session on screen: there is nowhere to go. */
+    /** Opens the session. `/debug/toasts` draws the card without it. */
     onOpen?: () => void;
     onDismiss: () => void;
 }): import("react").JSX.Element;

package/dist/internal/reminders/reminder-format.d.ts

@@ -22,5 +22,9 @@ export declare function soonestFire(reminders: readonly Pick<SessionReminder, 's
 export declare function elapsedShare(reminder: Pick<SessionReminder, 'next_fire_at' | 'every_seconds' | 'last_fired_at' | 'created_at'>, now: number): number | null;
 /** The first line of the reminder text, for a one-line row title. */
 export declare function reminderTitle(reminder: Pick<SessionReminder, 'name' | 'prompt'>): string;
-/** "Cron 0 9 * * * Europe/Berlin", "Every 1h" or "Once"; `t` is the `reminders` translator. */
-export declare function scheduleLabel(reminder: Pick<SessionReminder, 'cron' | 'timezone' | 'every'>, t: (key: 'cron' | 'every' | 'once', values?: Record<string, string>) => string): string;
+/**
+ * "Cron 0 9 * * * Europe/Berlin", "Every 1h", "Once", or "On an event" for a
+ * session-target trigger a webhook, connector or App event, or merge fires;
+ * `t` is the `reminders` translator.
+ */
+export declare function scheduleLabel(reminder: Pick<SessionReminder, 'cron' | 'timezone' | 'every' | 'source_type'>, t: (key: 'cron' | 'every' | 'once' | 'onEvent', values?: Record<string, string>) => string): string;

package/dist/internal/reminders/reminder-format.js

@@ -82,8 +82,14 @@ export function elapsedShare(reminder, now) {
 export function reminderTitle(reminder) {
     return reminder.name ?? reminder.prompt.split('\n')[0].trim();
 }
-/** "Cron 0 9 * * * Europe/Berlin", "Every 1h" or "Once"; `t` is the `reminders` translator. */
+/**
+ * "Cron 0 9 * * * Europe/Berlin", "Every 1h", "Once", or "On an event" for a
+ * session-target trigger a webhook, connector or App event, or merge fires;
+ * `t` is the `reminders` translator.
+ */
 export function scheduleLabel(reminder, t) {
+    if (reminder.source_type && reminder.source_type !== 'schedule')
+        return t('onEvent');
     if (reminder.cron)
         return t('cron', { expression: [reminder.cron, reminder.timezone ?? ''].join(' ').trim() });
     return reminder.every ? t('every', { period: reminder.every }) : t('once');

package/dist/internal/stores/active-space-store.d.ts

@@ -0,0 +1,35 @@
+/** @internal Kortix apps only. No semver: it may change in any release. */
+/**
+ * The space the user is working inside, per project. `null` = no space (no
+ * scope: every space plus the Project-wide bucket). A space slug scopes
+ * Customize (and the surfaces that opt in) to that one space's agents,
+ * connectors, triggers, reminders and skills. Purely a per-viewer UI context
+ * (which space am I looking at) — it is NOT project config, so it lives in
+ * localStorage only and never touches `kortix.yaml`.
+ */
+type ActiveByProject = Record<string, string | null>;
+interface ActiveSpaceState {
+    byProject: ActiveByProject;
+    setSpace: (projectId: string, space: string | null) => void;
+}
+export declare const useActiveSpaceStore: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<ActiveSpaceState>, "setState" | "persist"> & {
+    setState(partial: ActiveSpaceState | Partial<ActiveSpaceState> | ((state: ActiveSpaceState) => ActiveSpaceState | Partial<ActiveSpaceState>), replace?: false | undefined): unknown;
+    setState(state: ActiveSpaceState | ((state: ActiveSpaceState) => ActiveSpaceState), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<import("zustand/middleware").PersistOptions<ActiveSpaceState, unknown, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: ActiveSpaceState) => void) => () => void;
+        onFinishHydration: (fn: (state: ActiveSpaceState) => void) => () => void;
+        getOptions: () => Partial<import("zustand/middleware").PersistOptions<ActiveSpaceState, unknown, unknown>>;
+    };
+}>;
+/**
+ * The active space for a project (`null` = All), and a setter for it. Spaces
+ * are Work in progress under the `project_channels` flag (`SPACES_FLAG` in
+ * internal/lib/space-scope.ts): off, a stored space reads as `null`, so no
+ * surface scopes to a space. The stored value stays for when the flag is on.
+ */
+export declare function useActiveSpace(projectId: string): [string | null, (space: string | null) => void];
+export {};

package/dist/internal/stores/active-space-store.js

@@ -0,0 +1,29 @@
+'use client';
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+import { useSpacesEnabled } from '../lib/space-scope.js';
+import { createSafeJSONStorage } from '../lib/storage/managed-storage.js';
+import { registerPersistedStore, resetPersistedStore } from './persisted-store-registry.js';
+const STORAGE_KEY = 'kortix.active-space';
+export const useActiveSpaceStore = create()(persist((set) => ({
+    byProject: {},
+    setSpace: (projectId, space) => set((state) => ({ byProject: { ...state.byProject, [projectId]: space } })),
+}), {
+    name: STORAGE_KEY,
+    storage: createSafeJSONStorage(),
+    version: 1,
+    partialize: (state) => ({ byProject: state.byProject }),
+}));
+registerPersistedStore(STORAGE_KEY, () => resetPersistedStore(useActiveSpaceStore));
+/**
+ * The active space for a project (`null` = All), and a setter for it. Spaces
+ * are Work in progress under the `project_channels` flag (`SPACES_FLAG` in
+ * internal/lib/space-scope.ts): off, a stored space reads as `null`, so no
+ * surface scopes to a space. The stored value stays for when the flag is on.
+ */
+export function useActiveSpace(projectId) {
+    const spacesOn = useSpacesEnabled(projectId || null);
+    const space = useActiveSpaceStore((state) => state.byProject[projectId] ?? null);
+    const setSpace = useActiveSpaceStore((state) => state.setSpace);
+    return [spacesOn ? space : null, (next) => setSpace(projectId, next)];
+}

package/dist/internal/stores/kortix-computer-store.d.ts

@@ -100,6 +100,7 @@ interface KortixComputerState {
         target?: QuickViewTarget;
     } | null;
     mobileToolView: QuickView | null;
+    mobileToolTarget: QuickViewTarget | null;
     openFileInComputer: (filePath: string, filePathList?: string[], targetLine?: number) => void;
     openFileBrowser: () => void;
     navigateToToolCall: (toolIndex: number) => void;
@@ -196,7 +197,7 @@ interface KortixComputerState {
         target?: QuickViewTarget;
     } | null;
     /** Mobile only — open `view` in the standalone tool drawer. */
-    openMobileTool: (view: QuickView) => void;
+    openMobileTool: (view: QuickView, target?: QuickViewTarget) => void;
     closeMobileTool: () => void;
     reset: () => void;
 }

package/dist/internal/stores/kortix-computer-store.js

@@ -29,6 +29,7 @@ const initialState = {
     pendingPrimaryOpenSessionId: null,
     pendingQuickView: null,
     mobileToolView: null,
+    mobileToolTarget: null,
     /** A quick-view consumed by the transient BOOT shell (e.g. Terminal clicked
      *  while the sandbox boots). The shell's provider dies at the boot→ready
      *  handoff, taking the view with it — this remembers the intent so
@@ -283,6 +284,7 @@ export const useKortixComputerStore = create()(devtools((set, get) => ({
             pendingToolNavIndex: null,
             // A tool drawer belonging to the session the user just left.
             mobileToolView: null,
+            mobileToolTarget: null,
             // The ⌘I restore memory dies with the session. Within a session the
             // key is a minimise/restore pair; across one it is not, and a detail
             // last seen on a page the user has navigated away from must never be
@@ -312,28 +314,37 @@ export const useKortixComputerStore = create()(devtools((set, get) => ({
         // invariant instead of a patch: this is the single point where
         // "does this session have detail content" changes, so there is no
         // second route into the broken state to remember later.
+        //
+        // It closes the side panel itself, not only `detailOpen`: the layout
+        // shows the right side on `isSidePanelOpen` alone, so a lone
+        // `detailOpen` reset left it open and white. Not `setIsSidePanelOpen`:
+        // the person did not close it, so the panel memory stays and the
+        // provider's arrival restore reopens what it showed.
         const losingDetail = has === null || has === false;
         const isActive = get()._activeSessionId === sessionId;
         const closeDetail = losingDetail && isActive && get().detailOpen;
+        const closePatch = closeDetail
+            ? { ...CLOSED_PANEL_PATCH, detailOpen: false, skipNextExpandAnimation: true }
+            : {};
         if (has === null) {
             if (!(sessionId in map)) {
                 if (closeDetail)
-                    set({ detailOpen: false });
+                    set(closePatch);
                 return;
             }
             const next = { ...map };
             delete next[sessionId];
-            set({ _detailContentBySession: next, ...(closeDetail ? { detailOpen: false } : {}) });
+            set({ _detailContentBySession: next, ...closePatch });
             return;
         }
         if (map[sessionId] === has) {
             if (closeDetail)
-                set({ detailOpen: false });
+                set(closePatch);
             return;
         }
         set({
             _detailContentBySession: { ...map, [sessionId]: has },
-            ...(closeDetail ? { detailOpen: false } : {}),
+            ...closePatch,
         });
     },
     openSidePanel: () => {
@@ -421,11 +432,11 @@ export const useKortixComputerStore = create()(devtools((set, get) => ({
         }
         return { view: pending.view, target: pending.target };
     },
-    openMobileTool: (view) => {
-        set({ mobileToolView: view });
+    openMobileTool: (view, target) => {
+        set({ mobileToolView: view, mobileToolTarget: target ? { ...target } : null });
     },
     closeMobileTool: () => {
-        set({ mobileToolView: null });
+        set({ mobileToolView: null, mobileToolTarget: null });
     },
     reset: () => {
         console.log('[KortixComputerStore] Full reset');

package/dist/internal/stores/pinned-agents-store.d.ts

@@ -0,0 +1,26 @@
+/** @internal Kortix apps only. No semver: it may change in any release. */
+/**
+ * The agents each person pins to the sidebar's Customize, per project. A
+ * view preference of this browser, like the session list's: nothing in the
+ * project's config changes. No pins: Customize shows the first agents.
+ */
+interface PinnedAgentsState {
+    byProject: Record<string, string[]>;
+    togglePinned: (projectId: string, agent: string) => void;
+}
+export declare const usePinnedAgentsStore: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<PinnedAgentsState>, "setState" | "persist"> & {
+    setState(partial: PinnedAgentsState | Partial<PinnedAgentsState> | ((state: PinnedAgentsState) => PinnedAgentsState | Partial<PinnedAgentsState>), replace?: false | undefined): unknown;
+    setState(state: PinnedAgentsState | ((state: PinnedAgentsState) => PinnedAgentsState), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<import("zustand/middleware").PersistOptions<PinnedAgentsState, unknown, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: PinnedAgentsState) => void) => () => void;
+        onFinishHydration: (fn: (state: PinnedAgentsState) => void) => () => void;
+        getOptions: () => Partial<import("zustand/middleware").PersistOptions<PinnedAgentsState, unknown, unknown>>;
+    };
+}>;
+/** The agents pinned in this project, in pin order. */
+export declare function usePinnedAgents(projectId: string): string[];
+export {};

package/dist/internal/stores/pinned-agents-store.js

@@ -0,0 +1,20 @@
+'use client';
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+import { createSafeJSONStorage } from '../lib/storage/managed-storage.js';
+import { registerPersistedStore, resetPersistedStore } from './persisted-store-registry.js';
+const STORAGE_KEY = 'kortix.pinned-agents';
+const EMPTY = [];
+export const usePinnedAgentsStore = create()(persist((set, get) => ({
+    byProject: {},
+    togglePinned: (projectId, agent) => {
+        const current = get().byProject[projectId] ?? EMPTY;
+        const next = current.includes(agent) ? current.filter((name) => name !== agent) : [...current, agent];
+        set({ byProject: { ...get().byProject, [projectId]: next } });
+    },
+}), { name: STORAGE_KEY, storage: createSafeJSONStorage(), partialize: (state) => ({ byProject: state.byProject }) }));
+/** The agents pinned in this project, in pin order. */
+export function usePinnedAgents(projectId) {
+    return usePinnedAgentsStore((state) => state.byProject[projectId] ?? EMPTY);
+}
+registerPersistedStore(STORAGE_KEY, () => resetPersistedStore(usePinnedAgentsStore));

package/dist/internal/stores/session-panel-memory-store.js

@@ -48,6 +48,9 @@ export function rememberedPanelOf({ terminalOpen, detailKey, }) {
         return { kind: 'view', view: 'browser', target: { url: detailKey.slice(4) } };
     if (detailKey?.startsWith('file:'))
         return { kind: 'file', path: detailKey.slice(5) };
+    // An artifact opens through the browser request, as a clicked artifact link does.
+    if (detailKey?.startsWith('artifact:'))
+        return { kind: 'view', view: 'browser', target: { url: detailKey.slice(9) } };
     return null;
 }
 /** The panel to reopen on arrival, or null: only on a running session, with the panel closed, on desktop. */

package/dist/internal/stores/turn-attention-store.d.ts

@@ -1,17 +1,18 @@
 /** @internal Kortix apps only. No semver: it may change in any release. */
 /**
- * Finished turns the user has not seen yet, per session.
+ * Turns the user has not seen yet, per session: finished turns, and failed
+ * turns of another project.
  *
  * The source of truth for the favicon badge (TurnAttentionBadge): a turn that
- * finished while the user was on another tab or another in-app session lands
+ * ended while the user was on another tab or another in-app session lands
  * here, and every entry is dropped the moment that session comes into view.
  * In-memory on purpose — the toast and the OS notification it complements are
  * ephemeral too, and the session list has no "unseen" concept to hydrate from.
  */
 interface TurnAttentionState {
-    /** Session ids whose finished turn the user has not seen yet. */
+    /** Session ids whose finished or failed turn the user has not seen yet. */
     unseen: readonly string[];
-    /** Record a finished turn for a session the user is not looking at. */
+    /** Record a finished or failed turn for a session the user is not looking at. */
     markTurnComplete: (sessionId: string) => void;
     /** Drop every id the user has now seen (viewed the session or its tab). */
     markSeen: (sessionIds: readonly string[]) => void;

package/dist/lib/routes.d.ts

@@ -28,6 +28,8 @@ export interface UiRoutes {
     goals: (projectId: string) => string | null;
     /** The project's artifacts (flag `artifacts`); one is `<artifacts>/<artifact_id>`. */
     artifacts: (projectId: string) => string | null;
+    /** One space: a channel, its room and its tabs (`?tab=` opens one). */
+    space: (projectId: string, slug: string) => string | null;
     members: (projectId: string) => string | null;
     /** The project settings page, on its sandbox section. */
     sandboxSettings: (projectId: string) => string | null;
@@ -37,6 +39,12 @@ export interface UiRoutes {
      * capability root, for example `models` or `triggers?id=<slug>`.
      */
     customize: (projectId: string, path?: string) => string | null;
+    /**
+     * Project admin: the project-wide libraries (connectors, skills, triggers,
+     * loops, models, secrets, apps, repo) and settings, one section each.
+     * `path` is the section and anything below it (`connectors/<app>`).
+     */
+    admin: (projectId: string, path?: string) => string | null;
     /** A channel of the project, by slug (`project_channels` flag). */
     channel: (projectId: string, slug: string) => string;
     /** The caller's direct messages with one agent, by agent name (`project_channels` flag). */
@@ -45,7 +53,12 @@ export interface UiRoutes {
     memory: (projectId: string) => string | null;
 }
 export declare const defaultUiRoutes: UiRoutes;
-/** Replaces the routes the host passes. Omitted routes keep their default. */
+/**
+ * Replaces the routes the host passes. Omitted routes keep their default,
+ * except `admin`: a host that maps `customize` (to its own pages, or to null)
+ * and says nothing of `admin` gets the same mapping for it, since the
+ * libraries left Customize for Project admin (2026-10-27).
+ */
 export declare function setUiRoutes(overrides: Partial<UiRoutes>): void;
 export declare function uiRoutes(): UiRoutes;
 /** A channel slug or DM agent name from its URL segment; null when a hand-typed escape is malformed. */
@@ -56,6 +69,8 @@ export declare function decodeSpaceSegment(segment: string): string | null;
  * the default path instead of breaking their own tabs.
  */
 export declare function customizePath(projectId: string, path?: string): string;
+/** A Project admin URL, with the same fallback as `customizePath`. */
+export declare function adminPath(projectId: string, path?: string): string;
 /**
  * The session id `pathname` shows, read through the host's `session` route
  * (so a host URL scheme works), or null when it is not a session page of

package/dist/lib/routes.js

@@ -8,18 +8,26 @@ const DEFAULT_ROUTES = {
     rooms: (p) => `/projects/${p}/rooms`,
     goals: (p) => `/projects/${p}/goals`,
     artifacts: (p) => `/projects/${p}/artifacts`,
+    space: (p, slug) => `/projects/${p}/spaces/${encodeURIComponent(slug)}`,
     members: (p) => `/projects/${p}/members`,
-    sandboxSettings: (p) => `/projects/${p}/config?section=sandbox`,
+    sandboxSettings: (p) => `/projects/${p}/admin/sandbox`,
     customize: (p, path) => `/projects/${p}/customize${path ? `/${path}` : ''}`,
+    admin: (p, path) => `/projects/${p}/admin${path ? `/${path}` : ''}`,
     channel: (p, slug) => `/projects/${p}/c/${slug}`,
     dm: (p, agentName) => `/projects/${p}/dm/${encodeURIComponent(agentName)}`,
     memory: (p) => `/projects/${p}/memory`,
 };
 export const defaultUiRoutes = DEFAULT_ROUTES;
 let routes = DEFAULT_ROUTES;
-/** Replaces the routes the host passes. Omitted routes keep their default. */
+/**
+ * Replaces the routes the host passes. Omitted routes keep their default,
+ * except `admin`: a host that maps `customize` (to its own pages, or to null)
+ * and says nothing of `admin` gets the same mapping for it, since the
+ * libraries left Customize for Project admin (2026-10-27).
+ */
 export function setUiRoutes(overrides) {
-    routes = { ...DEFAULT_ROUTES, ...overrides };
+    const admin = overrides.admin ?? overrides.customize;
+    routes = { ...DEFAULT_ROUTES, ...overrides, ...(admin ? { admin } : {}) };
 }
 export function uiRoutes() {
     return routes;
@@ -41,6 +49,10 @@ export function decodeSpaceSegment(segment) {
 export function customizePath(projectId, path) {
     return routes.customize(projectId, path) ?? DEFAULT_ROUTES.customize(projectId, path);
 }
+/** A Project admin URL, with the same fallback as `customizePath`. */
+export function adminPath(projectId, path) {
+    return routes.admin(projectId, path) ?? DEFAULT_ROUTES.admin(projectId, path);
+}
 /**
  * The session id `pathname` shows, read through the host's `session` route
  * (so a host URL scheme works), or null when it is not a session page of

package/dist/markdown/doc-editor/doc-embed.d.ts

@@ -0,0 +1,31 @@
+import type { LinkPreview } from '@kortix/sdk';
+import { Node } from '@tiptap/core';
+/**
+ * A pasted link shown as a card: its title, its description and the address on
+ * the left, the page's Open Graph image (when it has one) on the right. With
+ * no image, the site's favicon sits before the address. The
+ * card is stored in the Markdown file as one line of HTML
+ * (`<div class="kx-embed">…</div>`), so the published page shows it without
+ * fetching anything but that image; the doc stylesheet draws it.
+ */
+export type EmbedMeta = {
+    href: string;
+    title: string;
+    summary: string;
+    image: string;
+};
+/** A link that can be a card: any http(s) address. */
+export declare function canEmbed(href: string): boolean;
+/** One plain line from page text (Markdown or HTML removed), capped. */
+export declare function plainSummary(text: string | null | undefined): string;
+/** What the URL alone tells: the card when the page says nothing (a private page, Linear, a failed read). */
+export declare function embedFromUrl(href: string): EmbedMeta | null;
+/**
+ * The card for a link: the page's own title, description and image, read by
+ * the API (`read`: `getLinkPreview` for the doc's project). GitHub's title
+ * reads "… by author · Pull Request #12 · owner/repo". Linear is not read (its
+ * pages need a login); a page that cannot be read is the card the URL gives.
+ */
+export declare function fetchEmbed(href: string, read: (url: string) => Promise<LinkPreview>): Promise<EmbedMeta | null>;
+/** The card in a doc: an atom block, `div.kx-embed` in the HTML and in the Markdown file. */
+export declare const LinkEmbed: Node<any, any>;