@kortix/ui 0.14.8 → 0.14.10

package/dist/files/renderers/image-frame.d.ts

@@ -0,0 +1,48 @@
+import { type ReactNode } from 'react';
+export interface ImageFrameProps {
+    /** CSS `aspect-ratio` before the image loads (`"3 / 2"`); the image's natural size replaces it on load. */
+    aspectRatio: string;
+    src: string | null;
+    alt: string;
+    /** The image does not exist yet, or its bytes are on the way. */
+    pending: boolean;
+    /** Centered over the frame: the busy line, or a note. */
+    label?: ReactNode;
+    /** Makes the image a button (open it in the file viewer). */
+    onOpen?: () => void;
+    className?: string;
+    /**
+     * Fill the parent's box (a tile of a layout) and crop the image to it
+     * (`object-cover`), in place of holding `aspectRatio` and fitting the image.
+     */
+    fill?: boolean;
+    /**
+     * The tallest the frame may be (`'60vh'`): it narrows to keep its ratio,
+     * so it never crops more and never letterboxes. Unset: the full width.
+     */
+    maxHeight?: string;
+    /** The image button's accessible name; `alt` when unset. */
+    openLabel?: string;
+    /** The image's natural ratio when another surface already measured it (`"<w> / <h>"`), so a remount starts at it. */
+    naturalRatio?: string | null;
+    /** Reports the image's natural size once it decoded. */
+    onNaturalSize?: (width: number, height: number) => void;
+    /** Drawn over the frame's own box (an overlay on the image's corner), which narrows with `maxHeight`. */
+    children?: ReactNode;
+}
+/**
+ * The box an image takes before, while and after it exists: a flat `bg-muted`
+ * surface that holds the requested aspect ratio before any pixel arrives, so
+ * the layout does not jump when the image lands, then fades the image in.
+ * The frame itself never moves: the busy signal is the label (one waiting
+ * channel, kortix-brand `layout.md` States).
+ */
+export declare function ImageFrame({ aspectRatio, src, alt, pending, label, onOpen, className, fill, maxHeight, openLabel, naturalRatio, onNaturalSize, children, }: ImageFrameProps): import("react").JSX.Element;
+/**
+ * An image whose file could not be read: "Image unavailable" and Try again,
+ * centered in the frame. Never the read's own error text (R38): that is
+ * internal (a status line, a path, a stack), not something a reader can act on.
+ */
+export declare function ImageUnavailable({ onRetry }: {
+    onRetry: () => void;
+}): import("react").JSX.Element;

package/dist/files/renderers/image-frame.js

@@ -0,0 +1,59 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useTranslations } from '../../i18n/index.js';
+import { Button } from '../../primitives/button.js';
+import { cn } from '../../lib/utils.js';
+import { useEffect, useRef, useState } from 'react';
+/** `'3 / 2'` → `1.5`; anything unreadable → `1`. */
+function ratioValue(ratio) {
+    const [w, h] = ratio.split('/').map((part) => Number(part.trim()));
+    return w && h ? w / h : 1;
+}
+/**
+ * The box an image takes before, while and after it exists: a flat `bg-muted`
+ * surface that holds the requested aspect ratio before any pixel arrives, so
+ * the layout does not jump when the image lands, then fades the image in.
+ * The frame itself never moves: the busy signal is the label (one waiting
+ * channel, kortix-brand `layout.md` States).
+ */
+export function ImageFrame({ aspectRatio, src, alt, pending, label, onOpen, className, fill = false, maxHeight, openLabel, naturalRatio = null, onNaturalSize, children, }) {
+    const img = useRef(null);
+    const [loaded, setLoaded] = useState(false);
+    const [natural, setNatural] = useState(naturalRatio);
+    // A new source starts hidden at the requested ratio again; a cached one may
+    // be complete before React sees `load`.
+    useEffect(() => {
+        const el = img.current;
+        const complete = !!el?.complete && el.naturalWidth > 0;
+        setLoaded(complete);
+        setNatural(complete && el ? `${el.naturalWidth} / ${el.naturalHeight}` : naturalRatio);
+        // The ratio is the cached one until this source decodes; a new source is measured on load.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [src]);
+    const onLoad = () => {
+        const el = img.current;
+        if (el?.naturalWidth && el.naturalHeight) {
+            setNatural(`${el.naturalWidth} / ${el.naturalHeight}`);
+            onNaturalSize?.(el.naturalWidth, el.naturalHeight);
+        }
+        setLoaded(true);
+    };
+    const image = src ? (
+    // eslint-disable-next-line @next/next/no-img-element -- a blob: URL of a sandbox file; the Next loader cannot fetch it
+    _jsx("img", { ref: img, src: src, alt: alt, onLoad: onLoad, className: cn('size-full transition-[opacity,filter] duration-moderate ease-out motion-reduce:blur-none', fill ? 'object-cover' : 'object-contain', loaded ? 'opacity-100 blur-none' : 'opacity-0 blur-xs') })) : null;
+    return (_jsxs("div", { "aria-busy": pending, className: cn('bg-muted relative w-full overflow-hidden rounded-md', fill && 'h-full', className), style: fill
+            ? undefined
+            : {
+                aspectRatio: natural ?? aspectRatio,
+                ...(maxHeight && { width: `min(100%, calc(${maxHeight} * ${ratioValue(natural ?? aspectRatio)}))` }),
+            }, children: [image && onOpen ? (_jsx("button", { type: "button", onClick: onOpen, "aria-label": openLabel ?? alt, className: "focus-visible:ring-kortix-base block size-full cursor-zoom-in rounded-md focus-visible:ring-2 focus-visible:outline-none focus-visible:ring-inset", children: image })) : (image), label ? (_jsx("div", { className: "absolute inset-0 flex items-center justify-center p-4 text-center", children: label })) : null, children] }));
+}
+/**
+ * An image whose file could not be read: "Image unavailable" and Try again,
+ * centered in the frame. Never the read's own error text (R38): that is
+ * internal (a status line, a path, a stack), not something a reader can act on.
+ */
+export function ImageUnavailable({ onRetry }) {
+    const t = useTranslations('imageGen');
+    return (_jsxs("span", { className: "text-muted-foreground flex flex-col items-center gap-2 text-xs", children: [t('unavailable'), _jsx(Button, { type: "button", variant: "secondary", size: "sm", className: "active:scale-[0.96]", onClick: onRetry, children: t('tryAgain') })] }));
+}

package/dist/files/renderers/image-renderer.d.ts

@@ -24,6 +24,16 @@ interface ImageRendererProps {
     /** Add the backdrop swatches to the shelf (see `ImageBackdrop`). Off by
      *  default — an opaque JPEG has exactly one meaningful background. */
     backdrop?: boolean;
+    /**
+     * The image's details toggle (ⓘ), last on the shelf: shown only when the
+     * host has details for this image (a generated image's prompt and model).
+     * It is a `DisclosureTrigger`: the host renders this renderer inside the
+     * `Disclosure` whose content holds the details.
+     */
+    info?: {
+        pressed: boolean;
+        label: string;
+    };
 }
-export declare function ImageRenderer({ url, className, fileName, controls, backdrop: showBackdrop, }: ImageRendererProps): React.JSX.Element;
+export declare function ImageRenderer({ url, className, fileName, controls, backdrop: showBackdrop, info, }: ImageRendererProps): React.JSX.Element;
 export {};

package/dist/files/renderers/image-renderer.js

@@ -6,10 +6,20 @@ import { Button } from '../../primitives/button.js';
 import { ButtonGroup, ButtonGroupSeparator } from '../../primitives/button-group.js';
 import Hint from '../../primitives/hint.js';
 import Loading from '../../primitives/loading.js';
+import { IconInfo } from '../../primitives/kortix-icons.js';
+import { DisclosureTrigger } from '../../primitives/disclosure.js';
 import { usePreviewFit } from '../viewer/preview-fit.js';
 import { cn } from '../../lib/utils.js';
 import { ImageBrokenIcon as ImageOff, ArrowClockwiseIcon as RotateCw, MagnifyingGlassPlusIcon as ZoomIn, MagnifyingGlassMinusIcon as ZoomOut, } from '@phosphor-icons/react';
 import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * The details toggle: a `DisclosureTrigger` (toggle, Enter/Space,
+ * `aria-expanded`) around the shelf's button. Props and ref pass through, so
+ * the tooltip trigger around it still works.
+ */
+function InfoTrigger({ pressed, label, ...props }) {
+    return (_jsx(DisclosureTrigger, { children: _jsx(Button, { ...props, variant: "secondary", size: "icon-base", "aria-label": label, "aria-pressed": pressed, "data-image-info": "", children: _jsx(IconInfo, { className: "size-4", weight: pressed ? 'fill' : 'regular' }) }) }));
+}
 const MAX_RETRIES = 3;
 const RETRY_DELAYS = [500, 1500, 3000]; // ms — escalating backoff
 const MIN_ZOOM = 0.25;
@@ -43,7 +53,7 @@ const BACKDROPS = [
     { value: 'white', label: 'White' },
     { value: 'black', label: 'Black' },
 ];
-export function ImageRenderer({ url, className, fileName, controls = 'hover', backdrop: showBackdrop = false, }) {
+export function ImageRenderer({ url, className, fileName, controls = 'hover', backdrop: showBackdrop = false, info, }) {
     const tHardcodedUi = useTranslations('hardcodedUi');
     const backdrops = useLocalizedUiCatalog(BACKDROPS);
     // `null` outside a <PreviewFitProvider> (Advanced-mode viewer, /projects
@@ -230,8 +240,8 @@ export function ImageRenderer({ url, className, fileName, controls = 'hover', ba
                     : [
                         'top-1 opacity-0 transition-opacity duration-200 ease-out',
                         'group-hover:opacity-100 focus-within:opacity-100',
-                        showInfo && 'opacity-100',
-                    ]), children: _jsxs(ButtonGroup, { children: [_jsx(Hint, { label: zoomOutLabel, side: "bottom", children: _jsx(Button, { variant: "secondary", size: "icon-base", onClick: handleZoomOut, disabled: zoom <= MIN_ZOOM, "aria-label": zoomOutLabel, children: _jsx(ZoomOut, { className: "size-4" }) }) }), _jsx(Hint, { label: tHardcodedUi.raw('i18nComplete.textce89ae822e8b'), side: "bottom", children: _jsxs(Button, { variant: "secondary", size: "sm", className: "min-w-14 tabular-nums", onClick: handleResetZoom, "aria-label": tHardcodedUi.raw('i18nComplete.textce89ae822e8b'), children: [Math.round(zoom * 100), "%"] }) }), _jsx(Hint, { label: zoomInLabel, side: "bottom", children: _jsx(Button, { variant: "secondary", size: "icon-base", onClick: handleZoomIn, disabled: zoom >= MAX_ZOOM, "aria-label": zoomInLabel, children: _jsx(ZoomIn, { className: "size-4" }) }) }), _jsx(Hint, { label: tHardcodedUi.raw('i18nComplete.textc3613b1704f5'), side: "bottom", children: _jsx(Button, { variant: "secondary", size: "icon-base", onClick: handleRotate, "aria-label": tHardcodedUi.raw('i18nComplete.text9dc6b57eecba'), children: _jsx(RotateCw, { className: "size-4" }) }) }), showBackdrop && (_jsxs(_Fragment, { children: [_jsx(ButtonGroupSeparator, {}), backdrops.map(({ value, label }) => (_jsx(Hint, { label: `${label} background`, side: "bottom", children: _jsx(Button, { variant: "secondary", size: "icon-base", onClick: () => setBackdrop(value), "aria-label": `${label} background`, "aria-pressed": backdrop === value, children: _jsx("span", { className: cn(
+                        (showInfo || info?.pressed) && 'opacity-100',
+                    ]), children: _jsxs(ButtonGroup, { children: [_jsx(Hint, { label: zoomOutLabel, side: "bottom", children: _jsx(Button, { variant: "secondary", size: "icon-base", onClick: handleZoomOut, disabled: zoom <= MIN_ZOOM, "aria-label": zoomOutLabel, children: _jsx(ZoomOut, { className: "size-4" }) }) }), _jsx(Hint, { label: tHardcodedUi.raw('i18nComplete.textce89ae822e8b'), side: "bottom", children: _jsxs(Button, { variant: "secondary", size: "sm", className: "min-w-14 tabular-nums", onClick: handleResetZoom, "aria-label": tHardcodedUi.raw('i18nComplete.textce89ae822e8b'), children: [Math.round(zoom * 100), "%"] }) }), _jsx(Hint, { label: zoomInLabel, side: "bottom", children: _jsx(Button, { variant: "secondary", size: "icon-base", onClick: handleZoomIn, disabled: zoom >= MAX_ZOOM, "aria-label": zoomInLabel, children: _jsx(ZoomIn, { className: "size-4" }) }) }), _jsx(Hint, { label: tHardcodedUi.raw('i18nComplete.textc3613b1704f5'), side: "bottom", children: _jsx(Button, { variant: "secondary", size: "icon-base", onClick: handleRotate, "aria-label": tHardcodedUi.raw('i18nComplete.text9dc6b57eecba'), children: _jsx(RotateCw, { className: "size-4" }) }) }), info ? (_jsx(Hint, { label: info.label, side: "bottom", children: _jsx(InfoTrigger, { pressed: info.pressed, label: info.label }) })) : null, showBackdrop && (_jsxs(_Fragment, { children: [_jsx(ButtonGroupSeparator, {}), backdrops.map(({ value, label }) => (_jsx(Hint, { label: `${label} background`, side: "bottom", children: _jsx(Button, { variant: "secondary", size: "icon-base", onClick: () => setBackdrop(value), "aria-label": `${label} background`, "aria-pressed": backdrop === value, children: _jsx("span", { className: cn(
                                             // A hairline on every swatch, not just the white one:
                                             // without it the white chip vanishes on a light
                                             // toolbar and the black one on a dark toolbar.

package/dist/files/renderers/pdf/pdf-clipboard.d.ts

@@ -0,0 +1,2 @@
+/** The upstream React utility leaves denied clipboard writes unhandled. */
+export declare function PdfClipboard(): null;

package/dist/files/renderers/pdf/pdf-clipboard.js

@@ -0,0 +1,21 @@
+import { useSelectionCapability } from '@embedpdf/plugin-selection/react';
+import { useEffect } from 'react';
+import { errorToast } from '../../../primitives/toast.js';
+import { useTranslations } from '../../../i18n/index.js';
+import { copyToClipboard } from '../../../internal/lib/utils/clipboard.js';
+/** The upstream React utility leaves denied clipboard writes unhandled. */
+export function PdfClipboard() {
+    const { provides: selection } = useSelectionCapability();
+    const t = useTranslations('commandPalette');
+    useEffect(() => {
+        if (!selection)
+            return;
+        return selection.onCopyToClipboard(({ text }) => {
+            void copyToClipboard(text).then((copied) => {
+                if (!copied)
+                    errorToast(t('copyFailed'));
+            });
+        });
+    }, [selection, t]);
+    return null;
+}

package/dist/files/renderers/pdf/pdf-viewer.js

@@ -9,7 +9,8 @@ import { RenderLayer, RenderPluginPackage } from '@embedpdf/plugin-render/react'
 import { Rotate, RotatePluginPackage } from '@embedpdf/plugin-rotate/react';
 import { ScrollPluginPackage, ScrollStrategy, useScroll, useScrollPlugin, } from '@embedpdf/plugin-scroll/react';
 import { SearchLayer, SearchPluginPackage, useSearch } from '@embedpdf/plugin-search/react';
-import { CopyToClipboard, SelectionPluginPackage, useSelectionCapability, useSelectionPlugin, } from '@embedpdf/plugin-selection/react';
+import { SelectionPluginPackage } from '@embedpdf/plugin-selection';
+import { useSelectionCapability, useSelectionPlugin, } from '@embedpdf/plugin-selection/react';
 import { ThumbImg, ThumbnailPluginPackage, useThumbnailCapability, useThumbnailPlugin, } from '@embedpdf/plugin-thumbnail/react';
 import { TilingLayer, TilingPluginPackage } from '@embedpdf/plugin-tiling/react';
 import { useIsViewportGated, useViewportCapability, useViewportElement, useViewportRef, ViewportElementContext, ViewportPluginPackage, } from '@embedpdf/plugin-viewport/react';
@@ -36,6 +37,7 @@ import { cn } from '../../../lib/utils.js';
 import { downloadBlob } from '../../../internal/lib/utils/download.js';
 import { loadSharedPdfEngine } from './pdf-engine-loader.js';
 import { SidebarGlyph as PanelLeft } from '../../../icons/sidebar-toggle.js';
+import { PdfClipboard } from './pdf-clipboard.js';
 const DEFAULT_ZOOM = 1;
 const ZOOM_OPTIONS = [0.1, 0.25, 0.5, 0.75, 1, 1.25, 1.5, 2];
 const PAGE_GAP = 24;
@@ -1218,7 +1220,7 @@ function PDFViewerInner({ viewerRef, pdfFile, documentId, document: pdfDocument,
                                                 }, children: _jsx(CircleMinus, { className: "size-4" }) }) }), _jsxs(Select, { value: String(currentZoomLevel), onValueChange: (value) => zoom?.requestZoom(Number(value)), disabled: controlsDisabled, modal: false, children: [_jsx(SelectTrigger, { size: "sm", className: "w-[84px] min-w-[84px] tabular-nums", children: _jsxs(SelectValue, { placeholder: tI18nComplete.raw('text509c517ede79'), children: [Math.round(currentZoomLevel * 100), "%"] }) }), _jsx(SelectContent, { alignItemWithTrigger: false, children: ZOOM_OPTIONS.map((option) => (_jsxs(SelectItem, { value: String(option), children: [Math.round(option * 100), "%"] }, option))) })] }), _jsx(ToolbarTooltip, { label: tI18nComplete.raw('text0e47f09a748f'), children: _jsx(Button, { type: "button", variant: "ghost", size: "icon-sm", className: "transition-transform active:scale-[0.96]", "aria-label": tI18nComplete.raw('text0e47f09a748f'), disabled: controlsDisabled || currentZoomLevel >= ZOOM_OPTIONS[ZOOM_OPTIONS.length - 1], onClick: () => {
                                                     const nextZoom = ZOOM_OPTIONS.find((option) => option > currentZoomLevel);
                                                     zoom?.requestZoom(nextZoom ?? ZOOM_OPTIONS[ZOOM_OPTIONS.length - 1]);
-                                                }, children: _jsx(CirclePlus, { className: "size-4" }) }) })] }), _jsx(Separator, { orientation: "vertical", className: "mx-1 h-4 self-center" }), _jsx(PDFViewerSearchControl, { documentId: documentId, controlsDisabled: controlsDisabled, initialSearch: findText }, documentId), toolbarActions ? (_jsxs(_Fragment, { children: [_jsx(Separator, { orientation: "vertical", className: "mx-1 h-4 self-center" }), toolbarActions] })) : null, showDownload || showUpload ? (_jsxs(_Fragment, { children: [_jsx(Separator, { orientation: "vertical", className: "mx-1 h-4 self-center" }), _jsx(PDFViewerFileActionsMenu, { onUploadFile: handleUpload, showUpload: showUpload }), showDownload ? (_jsx(ViewerDownloadButton, { disabled: controlsDisabled, pending: isPreparingDownload, onDownload: () => void handleDownload() })) : null] })) : null] }) })] })) : null, _jsxs("div", { ref: viewerShellRef, className: "bg-muted/30 relative flex min-h-0 flex-1 overflow-hidden", children: [isLoading ? (_jsx(PDFViewerLoadingSkeleton, { sidebarInline: sidebarInline, sidebarOpen: sidebarOpen })) : null, _jsxs("div", { className: "flex h-full max-h-full min-h-0 w-full flex-1 overflow-hidden", children: [_jsx(DocumentViewerThumbnailSidebar, { closedInlineClassName: THUMBNAIL_SIDEBAR_CLOSED_CLASS, inline: sidebarInline, open: thumbnailSidebarVisible, widthClassName: THUMBNAIL_SIDEBAR_WIDTH_CLASS, children: thumbnailSidebarVisible ? (_jsx(PDFViewerThumbnails, { basePageRotations: basePageRotations, documentId: documentId, activePage: activePage, pageCount: numPages, pageRotationDeltas: pageRotationDeltas, pdfDocument: pdfDocument, selectedPageIndexes: selectedPageIndexes, onSelectPage: selectThumbnailPage })) : null }), _jsxs(PDFViewerScrollAreaViewport, { documentId: documentId, className: "relative h-full max-h-full min-h-0 min-w-0 flex-1", children: [_jsx(PDFViewerViewportBridge, { viewportElementRef: viewportElementRef }), _jsx(PDFViewerSelectionCopyShortcut, { documentId: documentId }), _jsx(PDFViewerSelectionReleaseGuard, { documentId: documentId }), _jsx(GlobalPointerProvider, { documentId: documentId, children: _jsx(PDFViewerScroller, { basePageRotations: basePageRotations, documentId: documentId, pageRotationDeltas: pageRotationDeltas, renderPage: renderPage }) }), _jsx(CopyToClipboard, {})] })] })] })] }));
+                                                }, children: _jsx(CirclePlus, { className: "size-4" }) }) })] }), _jsx(Separator, { orientation: "vertical", className: "mx-1 h-4 self-center" }), _jsx(PDFViewerSearchControl, { documentId: documentId, controlsDisabled: controlsDisabled, initialSearch: findText }, documentId), toolbarActions ? (_jsxs(_Fragment, { children: [_jsx(Separator, { orientation: "vertical", className: "mx-1 h-4 self-center" }), toolbarActions] })) : null, showDownload || showUpload ? (_jsxs(_Fragment, { children: [_jsx(Separator, { orientation: "vertical", className: "mx-1 h-4 self-center" }), _jsx(PDFViewerFileActionsMenu, { onUploadFile: handleUpload, showUpload: showUpload }), showDownload ? (_jsx(ViewerDownloadButton, { disabled: controlsDisabled, pending: isPreparingDownload, onDownload: () => void handleDownload() })) : null] })) : null] }) })] })) : null, _jsxs("div", { ref: viewerShellRef, className: "bg-muted/30 relative flex min-h-0 flex-1 overflow-hidden", children: [isLoading ? (_jsx(PDFViewerLoadingSkeleton, { sidebarInline: sidebarInline, sidebarOpen: sidebarOpen })) : null, _jsxs("div", { className: "flex h-full max-h-full min-h-0 w-full flex-1 overflow-hidden", children: [_jsx(DocumentViewerThumbnailSidebar, { closedInlineClassName: THUMBNAIL_SIDEBAR_CLOSED_CLASS, inline: sidebarInline, open: thumbnailSidebarVisible, widthClassName: THUMBNAIL_SIDEBAR_WIDTH_CLASS, children: thumbnailSidebarVisible ? (_jsx(PDFViewerThumbnails, { basePageRotations: basePageRotations, documentId: documentId, activePage: activePage, pageCount: numPages, pageRotationDeltas: pageRotationDeltas, pdfDocument: pdfDocument, selectedPageIndexes: selectedPageIndexes, onSelectPage: selectThumbnailPage })) : null }), _jsxs(PDFViewerScrollAreaViewport, { documentId: documentId, className: "relative h-full max-h-full min-h-0 min-w-0 flex-1", children: [_jsx(PDFViewerViewportBridge, { viewportElementRef: viewportElementRef }), _jsx(PDFViewerSelectionCopyShortcut, { documentId: documentId }), _jsx(PDFViewerSelectionReleaseGuard, { documentId: documentId }), _jsx(GlobalPointerProvider, { documentId: documentId, children: _jsx(PDFViewerScroller, { basePageRotations: basePageRotations, documentId: documentId, pageRotationDeltas: pageRotationDeltas, renderPage: renderPage }) }), _jsx(PdfClipboard, {})] })] })] })] }));
 }
 function PDFViewerDocumentLoader({ pdfFile, onDocumentLoadSuccess, ...innerProps }) {
     const { provides: documentManager } = useDocumentManagerCapability();

package/dist/files/renderers/show-content-renderer.d.ts

@@ -44,6 +44,12 @@ export interface ShowContentProps {
      * blob would run agent-authored script inside the app.
      */
     attachment?: string;
+    /**
+     * The sha256 of the file's bytes, from the `show` output (R38): an image
+     * already loaded under another path (the generated original of a Drive
+     * copy) draws at once from the shared image store.
+     */
+    sha256?: string;
     /** Optional: render a proxied localhost iframe. Caller provides this component. */
     LocalhostPreview?: React.ComponentType<{
         url: string;
@@ -74,7 +80,7 @@ export interface ShowContentProps {
      */
     toolbarActions?: React.ReactNode;
 }
-export declare function ShowContentRenderer({ type, title, description, path, url, content, language, aspectRatio, attachment, LocalhostPreview, fill, onStatusChange, toolbarActions, }: ShowContentProps): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
+export declare function ShowContentRenderer({ type, title, description, path, url, content, language, aspectRatio, attachment, sha256, LocalhostPreview, fill, onStatusChange, toolbarActions, }: ShowContentProps): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
 export interface ShowCarouselItem {
     type: string;
     title?: string;
@@ -86,6 +92,8 @@ export interface ShowCarouselItem {
     aspect_ratio?: string;
     /** Stored copy of `path` from saved history — see `ShowContentProps.attachment`. */
     attachment?: string;
+    /** The bytes' sha256 from the `show` output — see `ShowContentProps.sha256`. */
+    sha256?: string;
     /** `pending`: a grouped `show` call whose payload has not arrived yet. The
      *  slot holds its place so the card does not jump when it lands. */
     status?: 'pending' | 'ready' | 'error';

package/dist/files/renderers/show-content-renderer.js

@@ -36,6 +36,7 @@ import Loading from '../../primitives/loading.js';
 import { TextShimmer } from '../../primitives/text-shimmer.js';
 import { framePolicy } from '../viewer/preview-policy.js';
 import { useBinaryBlob } from '../runtime/hooks/use-binary-blob.js';
+import { useSharedImage } from '../runtime/hooks/use-shared-image.js';
 import { sessionDriveMountPath } from '../../internal/files/session-drive-files.js';
 import { useFileContent } from '../runtime/hooks/use-file-content.js';
 import { useHeicBlob } from '../../internal/hooks/use-heic-url.js';
@@ -49,10 +50,14 @@ import { buildStaticFileLocalUrl, isSessionAttachmentRef } from '@kortix/sdk';
 import { WarningIcon as AlertTriangle, CaretLeftIcon as ChevronLeft, CaretRightIcon as ChevronRight, ArrowSquareOutIcon as ExternalLink, FileIcon, FileTextIcon as FileText, FileXIcon as FileWarning, GlobeIcon as Globe, MusicNotesIcon as Music, } from '@phosphor-icons/react';
 import { lazy, Suspense, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { ImageRenderer } from './image-renderer.js';
+import { ImageFrame, ImageUnavailable } from './image-frame.js';
 import { MermaidDiagram } from './mermaid/mermaid-diagram.js';
 import { ViewerFrame } from './shared/viewer-frame.js';
 import { resolveShowType, shouldRenderFromSandboxFile } from './show-type-utils.js';
 import { VideoRenderer } from './video-renderer.js';
+import { ShowConnectHero, showConnectTarget } from '../../markdown/setup-links/show-connect-hero.js';
+import { ShowArtifactCard } from '../../artifacts/artifact-session.js';
+import { parseArtifactUrl } from '../../artifacts/frame-policy.js';
 // ── Lazy-load heavy renderers ──────────────────────────────────────────────
 const PdfRenderer = lazy(() => import('./pdf/pdf-renderer.js').then((m) => ({ default: m.PdfRenderer })));
 const CsvRenderer = lazy(() => import('./csv/csv-renderer.js').then((m) => ({ default: m.CsvRenderer })));
@@ -84,6 +89,35 @@ export function showDomain(url) {
         return url;
     }
 }
+const SHOW_LINK_COPY = { open: 'Open' };
+/**
+ * The `url` show: one card, centered in the panel.
+ *
+ * A connect URL (a Kortix link or a provider's sign-in page) is not a page to
+ * visit: it renders the connect step, `ShowConnectHero`. Every other URL is a link card:
+ * favicon, title, domain, the agent's sentence, and an explicit Open action.
+ */
+function ShowLink({ url, title, description }) {
+    const connect = showConnectTarget(url, title);
+    if (connect) {
+        return _jsx(ShowConnectHero, { url: url, target: connect, title: title, description: description });
+    }
+    // A Kortix artifact's link shows the artifact (a session page opens it in its panel,
+    // like an App link); a link the viewer cannot open stays a link.
+    if (parseArtifactUrl(url)) {
+        return _jsx(ShowArtifactCard, { url: url, fallback: _jsx(ShowLinkCard, { url: url, title: title, description: description }) });
+    }
+    return _jsx(ShowLinkCard, { url: url, title: title, description: description });
+}
+function ShowLinkCard({ url, title, description }) {
+    const copy = useLocalizedUiCatalog(SHOW_LINK_COPY);
+    const favicon = showFavicon(url);
+    const domain = showDomain(url);
+    const [faviconFailed, setFaviconFailed] = useState(false);
+    return (_jsxs("a", { href: url, target: "_blank", rel: "noopener noreferrer", "data-testid": "show-link-card", className: "group border-border bg-card hover:bg-hover flex w-full max-w-xl items-start gap-3 rounded-lg border p-4 transition-colors", children: [_jsx("span", { className: "bg-muted flex size-9 shrink-0 items-center justify-center overflow-hidden rounded-md", children: favicon && !faviconFailed ? (
+                /* eslint-disable-next-line @next/next/no-img-element */
+                _jsx("img", { src: favicon, alt: "", className: "size-5 rounded-sm", onError: () => setFaviconFailed(true) })) : (_jsx(Globe, { className: "text-muted-foreground size-4" })) }), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "text-foreground block truncate text-sm font-medium", children: title || domain }), _jsx("span", { className: "text-muted-foreground block truncate text-xs", children: domain }), description ? (_jsx("span", { className: "text-muted-foreground mt-2 line-clamp-3 block text-sm text-pretty", children: description })) : null] }), _jsxs("span", { className: "text-muted-foreground group-hover:text-foreground flex shrink-0 items-center gap-1 text-xs font-medium transition-colors", children: [copy.open, _jsx(ExternalLink, { className: "size-3.5" })] })] }));
+}
 export function showAspectRatioToCSS(ar) {
     if (!ar || ar === 'auto')
         return undefined;
@@ -138,8 +172,9 @@ function FileCard({ title, fileName, path }) {
     return (_jsxs("div", { className: "flex items-center gap-4 px-5 py-5", children: [_jsx("div", { className: "bg-muted/20 flex size-12 items-center justify-center rounded-xl", children: _jsx(FileText, { className: "text-muted-foreground/40 size-6" }) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "text-foreground truncate text-sm font-medium", children: title || fileName }), _jsx("div", { className: "text-muted-foreground/50 mt-0.5 truncate font-mono text-xs", children: path })] })] }));
 }
 // ── Component ──────────────────────────────────────────────────────────────
-export function ShowContentRenderer({ type, title = '', description = '', path = '', url = '', content = '', language = '', aspectRatio = '', attachment, LocalhostPreview, fill = false, onStatusChange, toolbarActions, }) {
+export function ShowContentRenderer({ type, title = '', description = '', path = '', url = '', content = '', language = '', aspectRatio = '', attachment, sha256, LocalhostPreview, fill = false, onStatusChange, toolbarActions, }) {
     const tI18nComplete = useTranslations('hardcodedUi.i18nComplete');
+    const tImageGen = useTranslations('imageGen');
     const arCSS = showAspectRatioToCSS(aspectRatio);
     // ── Height presets — fill the panel vs. the compact inline card ──
     // `mediaH`   → visual media (image/video/pdf/sheets/docs/generic file)
@@ -220,9 +255,16 @@ export function ShowContentRenderer({ type, title = '', description = '', path =
     // its sandbox read is a base64 text read, but a stored copy is bytes.
     const storedCopy = isSessionAttachmentRef(attachment) ? attachment : null;
     const blobFilePath = showBlobSource({ effectiveType, attachment, sandboxPath });
-    const { blobUrl, blob: rawBlob, isLoading: blobLoading, error: blobError, } = useBinaryBlob(blobFilePath);
     // HEIC conversion — converts the raw blob to renderable JPEG
     const isHeic = isImage && isHeicFile(fileName);
+    // Every other image draws from the page's shared image store (R38): by its
+    // sha256 when another surface already loaded those bytes, else read once.
+    const sharedImage = useSharedImage(isImage && !isHeic ? blobFilePath : null, isImage && !isHeic ? sha256 : null);
+    const binary = useBinaryBlob(isImage && !isHeic ? null : blobFilePath);
+    const { blob: rawBlob } = binary;
+    const blobUrl = isImage && !isHeic ? sharedImage.url : binary.blobUrl;
+    const blobLoading = isImage && !isHeic ? sharedImage.loading : binary.isLoading;
+    const blobError = isImage && !isHeic ? sharedImage.error : binary.error;
     const { url: heicImageUrl, isConverting: heicConverting } = useHeicBlob(isHeic ? rawBlob : null, fileName);
     // PDF: base64 content via SDK, decoded by PdfRenderer into a Blob URL.
     const pdfLoadPath = isPdf && sandboxPath && !storedCopy ? sandboxPath : null;
@@ -352,13 +394,7 @@ export function ShowContentRenderer({ type, title = '', description = '', path =
         if (!safeExternalUrl) {
             return (_jsx("div", { className: "px-5 py-4", children: _jsxs("div", { className: "text-muted-foreground flex items-center gap-2 truncate font-mono text-xs", children: [_jsx(Globe, { className: "size-3.5 shrink-0" }), url] }) }));
         }
-        const favicon = showFavicon(safeExternalUrl);
-        const domain = showDomain(safeExternalUrl);
-        return (_jsx("div", { className: cn('px-5 py-5', fill && 'flex h-full items-center'), children: _jsxs("a", { href: safeExternalUrl, target: "_blank", rel: "noopener noreferrer", className: "group border-border/30 bg-muted/5 hover:bg-muted/20 flex w-full items-center gap-4 rounded-2xl border p-4 transition-colors", children: [_jsx("div", { className: "bg-muted/30 flex size-10 shrink-0 items-center justify-center overflow-hidden rounded-lg", children: favicon ? (
-                        /* eslint-disable-next-line @next/next/no-img-element */
-                        _jsx("img", { src: favicon, alt: "", className: "size-6 rounded", onError: (e) => {
-                                e.target.style.display = 'none';
-                            } })) : (_jsx(Globe, { className: "text-muted-foreground/50 size-5" })) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "text-foreground group-hover:text-primary truncate text-sm font-medium transition-colors", children: title || domain }), _jsx("div", { className: "text-muted-foreground/60 mt-0.5 truncate font-mono text-xs", children: domain }), description && (_jsx("div", { className: "text-muted-foreground mt-1 line-clamp-2 text-xs", children: description }))] }), _jsx(ExternalLink, { className: "text-muted-foreground/30 group-hover:text-muted-foreground/60 size-4 shrink-0 transition-colors" })] }) }));
+        return (_jsx("div", { className: cn('flex justify-center px-5 py-5', fill && 'h-full items-center'), children: _jsx(ShowLink, { url: safeExternalUrl, title: title, description: description }) }));
     }
     // ═════════════════════════════════════════════════════════════════════════
     // Image — loaded via useBinaryBlob → blobUrl → ImageRenderer
@@ -369,10 +405,16 @@ export function ShowContentRenderer({ type, title = '', description = '', path =
     // it an image had no way to open in the side panel.
     // ═════════════════════════════════════════════════════════════════════════
     if (isImage && path) {
-        if (blobLoading || heicConverting)
-            return _jsx(RendererFallback, { className: mediaH });
-        if (blobError)
-            return _jsx(LoadError, { message: blobError });
+        // The same frame the image_gen card draws while its image is on the way,
+        // inside the same header the loaded image gets, so nothing grows on load.
+        // Never a bare path.
+        if (blobLoading || heicConverting) {
+            return framed(_jsx("div", { className: mediaH, children: _jsx(ImageFrame, { aspectRatio: "auto", src: null, alt: title || fileName, pending: true, label: _jsxs("span", { className: "text-muted-foreground flex items-center gap-2 text-xs", children: [_jsx(Loading, { className: "size-4 shrink-0" }), tImageGen('loading')] }), className: "h-full rounded-none" }) }));
+        }
+        // Never the read's raw error text on an image (R38): a short note and Try again.
+        if (blobError) {
+            return framed(_jsx("div", { className: mediaH, children: _jsx(ImageFrame, { aspectRatio: "auto", src: null, alt: title || fileName, pending: false, label: _jsx(ImageUnavailable, { onRetry: sharedImage.retry }), className: "h-full rounded-none" }) }));
+        }
         // HEIC: use the converted JPEG URL
         const imageUrl = isHeic ? heicImageUrl : blobUrl;
         if (imageUrl) {
@@ -695,7 +737,7 @@ export function ShowCarousel({ items, LocalhostPreview, onIndexChange, fill = fa
     return (_jsxs("div", { role: "group", className: cn('outline-none', fill && 'flex h-full flex-col'), 
         // -1: a click on the content focuses the card, so ←/→ page it next,
         // without adding a Tab stop. Tab still reaches the chevrons inside.
-        tabIndex: fill || count < 2 ? undefined : -1, onKeyDown: fill || count < 2 ? undefined : (e) => handleArrowKey(e), children: [_jsx("div", { className: cn(fill ? 'min-h-0 flex-1 overflow-hidden' : 'min-h-[420px]'), children: currentItem.status === 'pending' ? (_jsxs("div", { className: cn('flex items-center justify-center gap-3', fill ? 'h-full' : 'min-h-[420px]'), children: [_jsx(Loading, { className: "text-muted-foreground size-4" }), _jsx(TextShimmer, { duration: 1, spread: 2, className: "text-sm", children: tHardcodedUi.raw('componentsSessionToolRenderers.line4935JsxTextPreparingOutput') })] })) : (_jsx(ShowContentRenderer, { type: currentItem.type, title: currentItem.title, description: currentItem.description, path: currentItem.path, url: currentItem.url, content: currentItem.content, language: currentItem.language, aspectRatio: currentItem.aspect_ratio, attachment: currentItem.attachment, LocalhostPreview: LocalhostPreview, toolbarActions: toolbarActions, fill: fill })) }), count > 1 && !hideNav && (_jsxs("div", { className: "border-border flex shrink-0 items-center gap-2 border-t px-2 py-1.5 pr-3.5", children: [_jsxs("div", { className: "flex shrink-0 items-center", children: [_jsx(Button, { type: "button", variant: "ghost", size: "icon", onClick: prev, className: "hit-area-2 hit-area-r-0 transition-transform active:scale-[0.96]", disabled: currentIndex === 0, "aria-label": tI18nComplete.raw('text81b35f1b4332'), children: _jsx(ChevronLeft, { className: "size-4" }) }), _jsx(Button, { type: "button", variant: "ghost", size: "icon", onClick: next, className: "hit-area-2 hit-area-l-0 transition-transform active:scale-[0.96]", disabled: currentIndex >= count - 1, "aria-label": tI18nComplete.raw('text1e47d4f7a1a3'), children: _jsx(ChevronRight, { className: "size-4" }) })] }), _jsx(FadedScrollArea, { ref: stripRef, orientation: "horizontal", fadeColor: "from-secondary", className: "min-w-0 flex-1 overscroll-x-contain", children: _jsx("div", { className: "flex w-max min-w-0 items-center gap-1", children: items.map((item, i) => {
+        tabIndex: fill || count < 2 ? undefined : -1, onKeyDown: fill || count < 2 ? undefined : (e) => handleArrowKey(e), children: [_jsx("div", { className: cn(fill ? 'min-h-0 flex-1 overflow-hidden' : 'min-h-[420px]'), children: currentItem.status === 'pending' ? (_jsxs("div", { className: cn('flex items-center justify-center gap-3', fill ? 'h-full' : 'min-h-[420px]'), children: [_jsx(Loading, { className: "text-muted-foreground size-4" }), _jsx(TextShimmer, { duration: 1, spread: 2, className: "text-sm", children: tHardcodedUi.raw('componentsSessionToolRenderers.line4935JsxTextPreparingOutput') })] })) : (_jsx(ShowContentRenderer, { type: currentItem.type, title: currentItem.title, description: currentItem.description, path: currentItem.path, url: currentItem.url, content: currentItem.content, language: currentItem.language, aspectRatio: currentItem.aspect_ratio, attachment: currentItem.attachment, sha256: currentItem.sha256, LocalhostPreview: LocalhostPreview, toolbarActions: toolbarActions, fill: fill })) }), count > 1 && !hideNav && (_jsxs("div", { className: "border-border flex shrink-0 items-center gap-2 border-t px-2 py-1.5 pr-3.5", children: [_jsxs("div", { className: "flex shrink-0 items-center", children: [_jsx(Button, { type: "button", variant: "ghost", size: "icon", onClick: prev, className: "hit-area-2 hit-area-r-0 transition-transform active:scale-[0.96]", disabled: currentIndex === 0, "aria-label": tI18nComplete.raw('text81b35f1b4332'), children: _jsx(ChevronLeft, { className: "size-4" }) }), _jsx(Button, { type: "button", variant: "ghost", size: "icon", onClick: next, className: "hit-area-2 hit-area-l-0 transition-transform active:scale-[0.96]", disabled: currentIndex >= count - 1, "aria-label": tI18nComplete.raw('text1e47d4f7a1a3'), children: _jsx(ChevronRight, { className: "size-4" }) })] }), _jsx(FadedScrollArea, { ref: stripRef, orientation: "horizontal", fadeColor: "from-secondary", className: "min-w-0 flex-1 overscroll-x-contain", children: _jsx("div", { className: "flex w-max min-w-0 items-center gap-1", children: items.map((item, i) => {
                                 const label = labels[i] ?? 'Item';
                                 const isPortLabel = label.startsWith(':');
                                 return (_jsx("button", { ref: (el) => {

package/dist/files/runtime/file-source.js

@@ -3,6 +3,7 @@ import { downloadFile, uploadFile } from '../../internal/files/runtime-files.js'
 import { useFileContent } from './hooks/index.js';
 import { useBinaryBlob } from './hooks/use-binary-blob.js';
 import { useFileRefresh } from './hooks/use-file-refresh.js';
+import { useViewerImage } from './hooks/use-shared-image.js';
 // Do not import this component through the project-files barrel. The barrel
 // reaches useGitStatus through useChangeRequests and re-enters packages/ui/src/files/runtime.
 // Webpack cannot evaluate that async cycle while building this module constant.
@@ -19,4 +20,5 @@ export const workspaceFileSource = {
     upload: uploadFile,
     Breadcrumbs: FilePathBreadcrumbs,
     useRefresh: useFileRefresh,
+    useSharedImage: useViewerImage,
 };

package/dist/files/runtime/hooks/use-binary-blob.d.ts

@@ -21,9 +21,18 @@ export { binaryBlobKeys };
  * renders its bytes instead of waiting on a box that is not coming. A stored
  * copy is immutable, so it is never refetched and never polled.
  */
-export declare function useBinaryBlob(filePath: string | null): {
+export declare function useBinaryBlob(filePath: string | null, options?: {
+    /**
+     * An image tile's wait (R38): a runtime still starting is polled with a
+     * backoff and given up after about 2 min (`imageWakingRefetchInterval`),
+     * instead of the viewer's open-ended waking poll.
+     */
+    imageWait?: boolean;
+}): {
     blobUrl: string | null;
     blob: Blob | null;
     isLoading: boolean;
     error: string | null;
+    /** The image wait gave up (`options.imageWait`): show it unavailable, with Try again. */
+    waitedOut: boolean;
 };

package/dist/files/runtime/hooks/use-binary-blob.js

@@ -6,7 +6,7 @@ import { useEffect, useMemo, useState } from 'react';
 import { readRuntimeFileWithRetry } from '../../../internal/files/runtime-file-read.js';
 import { readFileAsBlob } from '../../../internal/files/runtime-files.js';
 import { keepBlobIfUnchanged } from './blob-identity.js';
-import { sandboxWakingRefetchInterval } from '../../../internal/files/file-read-retry.js';
+import { imageWaitedOut, imageWakingRefetchInterval, sandboxWakingRefetchInterval, } from '../../../internal/files/file-read-retry.js';
 import { useServerHealth } from './use-server-health.js';
 // ── Query keys ─────────────────────────────────────────────────────────────
 // Keyed by the SDK factory: the live event stream invalidates it on
@@ -34,7 +34,8 @@ export { binaryBlobKeys };
  * renders its bytes instead of waiting on a box that is not coming. A stored
  * copy is immutable, so it is never refetched and never polled.
  */
-export function useBinaryBlob(filePath) {
+export function useBinaryBlob(filePath, options) {
+    const imageWait = !!options?.imageWait;
     const serverUrl = useRuntimeStore((s) => s.getActiveServerUrl());
     // Asleep, not booting — the re-read below takes the slow lane.
     const { parked } = useServerHealth();
@@ -72,7 +73,11 @@ export function useBinaryBlob(filePath) {
         // A readiness 503 is a pending state, not a failure. A booting box earns the
         // fast cadence; a parked one is watched slowly. See the helper. A stored
         // copy has no box to wait for.
-        refetchInterval: (query) => stored ? false : sandboxWakingRefetchInterval(query.state.error, parked),
+        refetchInterval: (query) => stored
+            ? false
+            : imageWait
+                ? imageWakingRefetchInterval(query.state.error, query.state.errorUpdateCount)
+                : sandboxWakingRefetchInterval(query.state.error, parked),
     });
     const cachedBlob = query.data ?? null;
     // ── Blob URL — derived per-mount, revoked on unmount/change ─────────
@@ -98,5 +103,6 @@ export function useBinaryBlob(filePath) {
         blob: cachedBlob,
         isLoading: query.isLoading,
         error: query.error?.message ?? null,
-    }), [blobUrl, cachedBlob, query.isLoading, query.error?.message]);
+        waitedOut: imageWait && imageWaitedOut(query.error, query.errorUpdateCount),
+    }), [blobUrl, cachedBlob, query.isLoading, query.error, query.errorUpdateCount, imageWait]);
 }

package/dist/files/runtime/hooks/use-shared-image.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Drops every shared image: the digests, and the URL of every image no surface
+ * draws (the rest go when their surface unmounts). Runs on a sign-out and an
+ * account switch.
+ */
+export declare function clearSharedImages(): void;
+export interface SharedImage {
+    /** The image's object URL; null until its bytes are in. */
+    url: string | null;
+    /** `"<w> / <h>"` once any surface measured the image. */
+    naturalRatio: string | null;
+    /**
+     * The bytes are on the way: a read in flight, or the session runtime still
+     * starting (its URL not pinned yet, a waking 503), polled with a backoff for
+     * about 2 min.
+     */
+    loading: boolean;
+    /** A genuine read failure, or a wait that ran out. A host shows "Image unavailable" and `retry`, never this text. */
+    error: string | null;
+    /** Reads the file again, from a fresh wait. */
+    retry: () => void;
+    /** Records the image's natural size for the next surface that draws it. */
+    onNaturalSize: (width: number, height: number) => void;
+}
+/**
+ * The image at `path` (a sandbox path or a stored attachment ref), or the
+ * bytes with digest `sha256`. A digest already in `byDigest` draws at once and
+ * reads nothing. Otherwise the file is read through its one shared query, and
+ * bytes whose digest matches `sha256` join `byDigest`.
+ */
+export declare function useSharedImage(path: string | null, sha256?: string | null, options?: {
+    /**
+     * Keep the path's query mounted under a digest hit: the digest's bytes draw
+     * at once, and the file's own bytes replace them once read and found
+     * different. The viewer passes it, so its Refresh and `file.edited` always
+     * refetch the file, also when a card's caption named a digest for the path.
+     */
+    revalidate?: boolean;
+}): SharedImage;
+/** The full-screen viewer's image (`FileSource.useSharedImage`): a digest draws at once, the file is always read too. */
+export declare function useViewerImage(path: string | null, sha256?: string | null): SharedImage;