@askdkc/dsh-cli 0.11.3

package/lib/types/ink/reconciler.d.ts

@@ -0,0 +1,43 @@
+import createReconciler from 'react-reconciler';
+import { type DOMElement, type TextNode } from './dom.js';
+import { Dispatcher } from './events/dispatcher.js';
+/**
+ * Walk a fiber's owner chain and return the names of the components that
+ * rendered it, skipping host elements.
+ * @param fiber - the fiber whose owner chain to walk.
+ * @returns the component display names, outermost first.
+ */
+export declare function getOwnerChain(fiber: unknown): string[];
+/**
+ * Read the DSH_TUI_DEBUG_REPAINTS flag once and cache it.
+ * @returns whether repaint debugging is enabled.
+ */
+export declare function isDebugRepaintsEnabled(): boolean;
+/** The terminal event dispatcher that routes input events to registered handlers. */
+export declare const dispatcher: Dispatcher;
+/**
+ * Record the yoga layout duration of the current commit.
+ * @param ms - the layout duration in milliseconds.
+ */
+export declare function recordYogaMs(ms: number): void;
+/**
+ * The yoga layout duration recorded by recordYogaMs.
+ * @returns the layout duration in milliseconds.
+ */
+export declare function getLastYogaMs(): number;
+/** Mark the start of the current commit for commit-duration profiling. */
+export declare function markCommitStart(): void;
+/**
+ * The duration of the last commit, from markCommitStart to resetAfterCommit.
+ * @returns the commit duration in milliseconds.
+ */
+export declare function getLastCommitMs(): number;
+/** Reset all commit and layout profiling counters to zero. */
+export declare function resetProfileCounters(): void;
+/**
+ * The react-reconciler instance that renders React elements into the Ink
+ * DOM tree, wired to the event dispatcher for update priorities.
+ */
+declare const reconciler: createReconciler.Reconciler<DOMElement, DOMElement, TextNode, DOMElement, unknown, DOMElement>;
+export default reconciler;
+//# sourceMappingURL=reconciler.d.ts.map

package/lib/types/ink/reconciler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconciler.d.ts","sourceRoot":"","sources":["../../../src/ink/reconciler.ts"],"names":[],"mappings":"AAGA,OAAO,gBAAgB,MAAM,kBAAkB,CAAA;AAG/C,OAAO,EAKL,KAAK,UAAU,EAUf,KAAK,QAAQ,EACd,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAsInD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAmBtD;AAGD;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAKhD;AAED,qFAAqF;AACrF,eAAO,MAAM,UAAU,YAAmB,CAAA;AAkB1C;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE7C;AACD;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AACD,0EAA0E;AAC1E,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AACD;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AACD,8DAA8D;AAC9D,wBAAgB,oBAAoB,IAAI,IAAI,CAI3C;AAGD;;;GAGG;AACH,QAAA,MAAM,UAAU,gGA+Rd,CAAA;AAMF,eAAe,UAAU,CAAA"}

package/lib/types/ink/reconciler.js

@@ -0,0 +1,414 @@
+/* eslint-disable custom-rules/no-top-level-side-effects */
+import { appendFileSync } from 'fs';
+import createReconciler from 'react-reconciler';
+import { getYogaCounters } from '../native-ts/yoga-layout/index.js';
+import { isEnvTruthy } from '../utils/envUtils.js';
+import { appendChildNode, clearYogaNodeReferences, createNode, createTextNode, insertBeforeNode, markDirty, removeChildNode, setAttribute, setStyle, setTextNodeValue, setTextStyles, } from './dom.js';
+import { Dispatcher } from './events/dispatcher.js';
+import { EVENT_HANDLER_PROPS } from './events/event-handlers.js';
+import { getFocusManager, getRootNode } from './focus.js';
+import { LayoutDisplay } from './layout/node.js';
+import applyStyles from './styles.js';
+// We need to conditionally perform devtools connection to avoid
+// accidentally breaking other third-party code.
+// See https://github.com/vadimdemedes/ink/issues/384
+if (process.env.NODE_ENV === 'development') {
+    try {
+        // eslint-disable-next-line custom-rules/no-top-level-dynamic-import -- dev-only; NODE_ENV check is DCE'd in production
+        void import('./devtools.js');
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }
+    catch (error) {
+        if (error.code === 'ERR_MODULE_NOT_FOUND') {
+            // biome-ignore lint/suspicious/noConsole: intentional warning
+            console.warn(`
+The environment variable DEV is set to true, so Ink tried to import \`react-devtools-core\`,
+but this failed as it was not installed. Debugging with React Devtools requires it.
+
+To install use this command:
+
+$ npm install --save-dev react-devtools-core
+				`.trim() + '\n');
+        }
+        else {
+            // eslint-disable-next-line @typescript-eslint/only-throw-error
+            throw error;
+        }
+    }
+}
+const diff = (before, after) => {
+    if (before === after) {
+        return;
+    }
+    if (!before) {
+        return after;
+    }
+    const changed = {};
+    let isChanged = false;
+    for (const key of Object.keys(before)) {
+        const isDeleted = after ? !Object.hasOwn(after, key) : true;
+        if (isDeleted) {
+            changed[key] = undefined;
+            isChanged = true;
+        }
+    }
+    if (after) {
+        for (const key of Object.keys(after)) {
+            if (after[key] !== before[key]) {
+                changed[key] = after[key];
+                isChanged = true;
+            }
+        }
+    }
+    return isChanged ? changed : undefined;
+};
+const cleanupYogaNode = (node) => {
+    const yogaNode = node.yogaNode;
+    if (yogaNode) {
+        yogaNode.unsetMeasureFunc();
+        // Clear all references BEFORE freeing to prevent other code from
+        // accessing freed WASM memory during concurrent operations
+        clearYogaNodeReferences(node);
+        yogaNode.freeRecursive();
+    }
+};
+function setEventHandler(node, key, value) {
+    if (!node._eventHandlers) {
+        node._eventHandlers = {};
+    }
+    node._eventHandlers[key] = value;
+}
+function applyProp(node, key, value) {
+    if (key === 'children')
+        return;
+    if (key === 'style') {
+        setStyle(node, value);
+        if (node.yogaNode) {
+            applyStyles(node.yogaNode, value);
+        }
+        return;
+    }
+    if (key === 'textStyles') {
+        node.textStyles = value;
+        return;
+    }
+    if (EVENT_HANDLER_PROPS.has(key)) {
+        setEventHandler(node, key, value);
+        return;
+    }
+    setAttribute(node, key, value);
+}
+/**
+ * Walk a fiber's owner chain and return the names of the components that
+ * rendered it, skipping host elements.
+ * @param fiber - the fiber whose owner chain to walk.
+ * @returns the component display names, outermost first.
+ */
+export function getOwnerChain(fiber) {
+    const chain = [];
+    const seen = new Set();
+    let cur = fiber;
+    for (let i = 0; cur && i < 50; i++) {
+        if (seen.has(cur))
+            break;
+        seen.add(cur);
+        const t = cur.elementType;
+        const name = typeof t === 'function'
+            ? t.displayName ||
+                t.name
+            : typeof t === 'string'
+                ? undefined // host element (ink-box etc) — skip
+                : t?.displayName || t?.name;
+        if (name && name !== chain[chain.length - 1])
+            chain.push(name);
+        cur = cur._debugOwner ?? cur.return;
+    }
+    return chain;
+}
+let debugRepaints;
+/**
+ * Read the DSH_TUI_DEBUG_REPAINTS flag once and cache it.
+ * @returns whether repaint debugging is enabled.
+ */
+export function isDebugRepaintsEnabled() {
+    if (debugRepaints === undefined) {
+        debugRepaints = isEnvTruthy(process.env.DSH_TUI_DEBUG_REPAINTS);
+    }
+    return debugRepaints;
+}
+/** The terminal event dispatcher that routes input events to registered handlers. */
+export const dispatcher = new Dispatcher();
+// --- COMMIT INSTRUMENTATION (temp debugging) ---
+// eslint-disable-next-line custom-rules/no-process-env-top-level -- debug instrumentation, read-once is fine
+const COMMIT_LOG = process.env.DSH_TUI_COMMIT_LOG;
+let _commits = 0;
+let _lastLog = 0;
+let _lastCommitAt = 0;
+let _maxGapMs = 0;
+let _createCount = 0;
+let _prepareAt = 0;
+// --- END ---
+// --- SCROLL PROFILING (bench/scroll-e2e.sh reads via getLastYogaMs) ---
+// Set by onComputeLayout wrapper in ink.tsx; read by onRender for phases.
+let _lastYogaMs = 0;
+let _lastCommitMs = 0;
+let _commitStart = 0;
+/**
+ * Record the yoga layout duration of the current commit.
+ * @param ms - the layout duration in milliseconds.
+ */
+export function recordYogaMs(ms) {
+    _lastYogaMs = ms;
+}
+/**
+ * The yoga layout duration recorded by recordYogaMs.
+ * @returns the layout duration in milliseconds.
+ */
+export function getLastYogaMs() {
+    return _lastYogaMs;
+}
+/** Mark the start of the current commit for commit-duration profiling. */
+export function markCommitStart() {
+    _commitStart = performance.now();
+}
+/**
+ * The duration of the last commit, from markCommitStart to resetAfterCommit.
+ * @returns the commit duration in milliseconds.
+ */
+export function getLastCommitMs() {
+    return _lastCommitMs;
+}
+/** Reset all commit and layout profiling counters to zero. */
+export function resetProfileCounters() {
+    _lastYogaMs = 0;
+    _lastCommitMs = 0;
+    _commitStart = 0;
+}
+// --- END ---
+/**
+ * The react-reconciler instance that renders React elements into the Ink
+ * DOM tree, wired to the event dispatcher for update priorities.
+ */
+const reconciler = createReconciler({
+    getRootHostContext: () => ({ isInsideText: false }),
+    prepareForCommit: () => {
+        if (COMMIT_LOG)
+            _prepareAt = performance.now();
+        return null;
+    },
+    preparePortalMount: () => null,
+    clearContainer: () => false,
+    resetAfterCommit(rootNode) {
+        _lastCommitMs = _commitStart > 0 ? performance.now() - _commitStart : 0;
+        _commitStart = 0;
+        if (COMMIT_LOG) {
+            const now = performance.now();
+            _commits++;
+            const gap = _lastCommitAt > 0 ? now - _lastCommitAt : 0;
+            if (gap > _maxGapMs)
+                _maxGapMs = gap;
+            _lastCommitAt = now;
+            const reconcileMs = _prepareAt > 0 ? now - _prepareAt : 0;
+            if (gap > 30 || reconcileMs > 20 || _createCount > 50) {
+                // eslint-disable-next-line custom-rules/no-sync-fs -- debug instrumentation
+                appendFileSync(COMMIT_LOG, `${now.toFixed(1)} gap=${gap.toFixed(1)}ms reconcile=${reconcileMs.toFixed(1)}ms creates=${_createCount}\n`);
+            }
+            _createCount = 0;
+            if (now - _lastLog > 1000) {
+                // eslint-disable-next-line custom-rules/no-sync-fs -- debug instrumentation
+                appendFileSync(COMMIT_LOG, `${now.toFixed(1)} commits=${_commits}/s maxGap=${_maxGapMs.toFixed(1)}ms\n`);
+                _commits = 0;
+                _maxGapMs = 0;
+                _lastLog = now;
+            }
+        }
+        const _t0 = COMMIT_LOG ? performance.now() : 0;
+        if (typeof rootNode.onComputeLayout === 'function') {
+            rootNode.onComputeLayout();
+        }
+        if (COMMIT_LOG) {
+            const layoutMs = performance.now() - _t0;
+            if (layoutMs > 20) {
+                const c = getYogaCounters();
+                // eslint-disable-next-line custom-rules/no-sync-fs -- debug instrumentation
+                appendFileSync(COMMIT_LOG, `${_t0.toFixed(1)} SLOW_YOGA ${layoutMs.toFixed(1)}ms visited=${c.visited} measured=${c.measured} hits=${c.cacheHits} live=${c.live}\n`);
+            }
+        }
+        if (process.env.NODE_ENV === 'test') {
+            if (rootNode.childNodes.length === 0 && rootNode.hasRenderedContent) {
+                return;
+            }
+            if (rootNode.childNodes.length > 0) {
+                rootNode.hasRenderedContent = true;
+            }
+            rootNode.onImmediateRender?.();
+            return;
+        }
+        const _tr = COMMIT_LOG ? performance.now() : 0;
+        rootNode.onRender?.();
+        if (COMMIT_LOG) {
+            const renderMs = performance.now() - _tr;
+            if (renderMs > 10) {
+                // eslint-disable-next-line custom-rules/no-sync-fs -- debug instrumentation
+                appendFileSync(COMMIT_LOG, `${_tr.toFixed(1)} SLOW_PAINT ${renderMs.toFixed(1)}ms\n`);
+            }
+        }
+    },
+    getChildHostContext(parentHostContext, type) {
+        const previousIsInsideText = parentHostContext.isInsideText;
+        const isInsideText = type === 'ink-text' || type === 'ink-virtual-text' || type === 'ink-link';
+        if (previousIsInsideText === isInsideText) {
+            return parentHostContext;
+        }
+        return { isInsideText };
+    },
+    shouldSetTextContent: () => false,
+    createInstance(originalType, newProps, _root, hostContext, internalHandle) {
+        if (hostContext.isInsideText &&
+            (originalType === 'ink-box' || originalType === 'ink-image')) {
+            throw new Error(`<${originalType === 'ink-image' ? 'Image' : 'Box'}> can't be nested inside <Text> component`);
+        }
+        const type = originalType === 'ink-text' && hostContext.isInsideText
+            ? 'ink-virtual-text'
+            : originalType;
+        const node = createNode(type);
+        if (COMMIT_LOG)
+            _createCount++;
+        for (const [key, value] of Object.entries(newProps)) {
+            applyProp(node, key, value);
+        }
+        if (isDebugRepaintsEnabled()) {
+            node.debugOwnerChain = getOwnerChain(internalHandle);
+        }
+        return node;
+    },
+    createTextInstance(text, _root, hostContext) {
+        if (!hostContext.isInsideText) {
+            throw new Error(`Text string "${text}" must be rendered inside <Text> component`);
+        }
+        return createTextNode(text);
+    },
+    resetTextContent() { },
+    hideTextInstance(node) {
+        setTextNodeValue(node, '');
+    },
+    unhideTextInstance(node, text) {
+        setTextNodeValue(node, text);
+    },
+    getPublicInstance: (instance) => instance,
+    hideInstance(node) {
+        node.isHidden = true;
+        node.yogaNode?.setDisplay(LayoutDisplay.None);
+        markDirty(node);
+    },
+    unhideInstance(node) {
+        node.isHidden = false;
+        node.yogaNode?.setDisplay(LayoutDisplay.Flex);
+        markDirty(node);
+    },
+    appendInitialChild: appendChildNode,
+    appendChild: appendChildNode,
+    insertBefore: insertBeforeNode,
+    finalizeInitialChildren(_node, _type, props) {
+        return props['autoFocus'] === true;
+    },
+    commitMount(node) {
+        getFocusManager(node).handleAutoFocus(node);
+    },
+    isPrimaryRenderer: true,
+    supportsMutation: true,
+    supportsPersistence: false,
+    supportsHydration: false,
+    scheduleTimeout: setTimeout,
+    cancelTimeout: clearTimeout,
+    noTimeout: -1,
+    getCurrentUpdatePriority: () => dispatcher.currentUpdatePriority,
+    beforeActiveInstanceBlur() { },
+    afterActiveInstanceBlur() { },
+    detachDeletedInstance() { },
+    getInstanceFromNode: () => null,
+    prepareScopeUpdate() { },
+    getInstanceFromScope: () => null,
+    appendChildToContainer: appendChildNode,
+    insertInContainerBefore: insertBeforeNode,
+    removeChildFromContainer(node, removeNode) {
+        removeChildNode(node, removeNode);
+        cleanupYogaNode(removeNode);
+        getFocusManager(node).handleNodeRemoved(removeNode, node);
+    },
+    // React 19 commitUpdate receives old and new props directly instead of an updatePayload
+    commitUpdate(node, _type, oldProps, newProps) {
+        const props = diff(oldProps, newProps);
+        const style = diff(oldProps['style'], newProps['style']);
+        if (props) {
+            for (const [key, value] of Object.entries(props)) {
+                if (key === 'style') {
+                    setStyle(node, value);
+                    continue;
+                }
+                if (key === 'textStyles') {
+                    setTextStyles(node, value);
+                    continue;
+                }
+                if (EVENT_HANDLER_PROPS.has(key)) {
+                    setEventHandler(node, key, value);
+                    continue;
+                }
+                setAttribute(node, key, value);
+            }
+        }
+        if (style && node.yogaNode) {
+            applyStyles(node.yogaNode, style, newProps['style']);
+        }
+    },
+    commitTextUpdate(node, _oldText, newText) {
+        setTextNodeValue(node, newText);
+    },
+    removeChild(node, removeNode) {
+        removeChildNode(node, removeNode);
+        cleanupYogaNode(removeNode);
+        if (removeNode.nodeName !== '#text') {
+            const root = getRootNode(node);
+            root.focusManager.handleNodeRemoved(removeNode, root);
+        }
+    },
+    // React 19 required methods
+    maySuspendCommit() {
+        return false;
+    },
+    preloadInstance() {
+        return true;
+    },
+    startSuspendingCommit() { },
+    suspendInstance() { },
+    waitForCommitToBeReady() {
+        return null;
+    },
+    NotPendingTransition: null,
+    HostTransitionContext: {
+        $$typeof: Symbol.for('react.context'),
+        _currentValue: null,
+    },
+    setCurrentUpdatePriority(newPriority) {
+        dispatcher.currentUpdatePriority = newPriority;
+    },
+    resolveUpdatePriority() {
+        return dispatcher.resolveEventPriority();
+    },
+    resetFormInstance() { },
+    requestPostPaintCallback() { },
+    shouldAttemptEagerTransition() {
+        return false;
+    },
+    trackSchedulerEvent() { },
+    resolveEventType() {
+        return dispatcher.currentEvent?.type ?? null;
+    },
+    resolveEventTimeStamp() {
+        return dispatcher.currentEvent?.timeStamp ?? -1.1;
+    },
+});
+// Wire the reconciler's discreteUpdates into the dispatcher.
+// This breaks the import cycle: dispatcher.ts doesn't import reconciler.ts.
+dispatcher.discreteUpdates = reconciler.discreteUpdates.bind(reconciler);
+export default reconciler;

package/lib/types/ink/render-border.d.ts

@@ -0,0 +1,41 @@
+import { type Boxes, type BoxStyle } from 'cli-boxes';
+import type { DOMNode } from './dom.js';
+import type Output from './output.js';
+import type { Color } from './styles.js';
+/** Options for embedding a text label into a border line. */
+export type BorderTextOptions = {
+    content: string;
+    position: 'top' | 'bottom';
+    align: 'start' | 'end' | 'center';
+    offset?: number;
+};
+/** Built-in border styles beyond those provided by cli-boxes. */
+export declare const CUSTOM_BORDER_STYLES: {
+    readonly dashed: {
+        readonly top: "╌";
+        readonly left: "╎";
+        readonly right: "╎";
+        readonly bottom: "╌";
+        readonly topLeft: " ";
+        readonly topRight: " ";
+        readonly bottomLeft: " ";
+        readonly bottomRight: " ";
+    };
+};
+/** A border style: a cli-boxes key, a custom style key, or an explicit box style. */
+export type BorderStyle = keyof Boxes | keyof typeof CUSTOM_BORDER_STYLES | BoxStyle;
+/**
+ * Render the node's border, including any embedded border text, into the
+ * output buffer when a border style is set.
+ * @param x - the border's left column.
+ * @param y - the border's top row.
+ * @param node - the node whose border style to render.
+ * @param output - the output buffer receiving the border writes.
+ * @param background - the surface color the border's cells belong to, when the
+ *   node paints its own rect (own background, `opaque`, or an occlusion color
+ *   while a terminal image sits behind it). Transparent bordered overlays pass
+ *   undefined and keep terminal-transparent border cells.
+ */
+declare const renderBorder: (x: number, y: number, node: DOMNode, output: Output, background?: Color) => void;
+export default renderBorder;
+//# sourceMappingURL=render-border.d.ts.map

package/lib/types/ink/render-border.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-border.d.ts","sourceRoot":"","sources":["../../../src/ink/render-border.ts"],"names":[],"mappings":"AACA,OAAiB,EAAE,KAAK,KAAK,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAA;AAE/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAExC,6DAA6D;AAC7D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,KAAK,GAAG,QAAQ,CAAA;IAC1B,KAAK,EAAE,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAA;IACjC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,iEAAiE;AACjE,eAAO,MAAM,oBAAoB;;;;;;;;;;;CAYvB,CAAA;AAEV,qFAAqF;AACrF,MAAM,MAAM,WAAW,GACnB,MAAM,KAAK,GACX,MAAM,OAAO,oBAAoB,GACjC,QAAQ,CAAA;AA0DZ;;;;;;;;;;;GAWG;AACH,QAAA,MAAM,YAAY,GAChB,GAAG,MAAM,EACT,GAAG,MAAM,EACT,MAAM,OAAO,EACb,QAAQ,MAAM,EACd,aAAa,KAAK,KACjB,IAqJF,CAAA;AAED,eAAe,YAAY,CAAA"}

package/lib/types/ink/render-border.js

@@ -0,0 +1,159 @@
+import chalk from 'chalk';
+import cliBoxes from 'cli-boxes';
+import { applyColor, applyTextStyles } from './colorize.js';
+import { stringWidth } from './stringWidth.js';
+/** Built-in border styles beyond those provided by cli-boxes. */
+export const CUSTOM_BORDER_STYLES = {
+    dashed: {
+        top: '╌',
+        left: '╎',
+        right: '╎',
+        bottom: '╌',
+        // there aren't any line-drawing characters for dashes unfortunately
+        topLeft: ' ',
+        topRight: ' ',
+        bottomLeft: ' ',
+        bottomRight: ' ',
+    },
+};
+function embedTextInBorder(borderLine, text, align, offset = 0, borderChar) {
+    const textLength = stringWidth(text);
+    const borderLength = borderLine.length;
+    if (textLength >= borderLength - 2) {
+        return ['', text.substring(0, borderLength), ''];
+    }
+    let position;
+    if (align === 'center') {
+        position = Math.floor((borderLength - textLength) / 2);
+    }
+    else if (align === 'start') {
+        position = offset + 1; // +1 to account for corner character
+    }
+    else {
+        // align === 'end'
+        position = borderLength - textLength - offset - 1; // -1 for corner character
+    }
+    // Ensure position is valid
+    position = Math.max(1, Math.min(position, borderLength - textLength - 1));
+    const before = borderLine.substring(0, 1) + borderChar.repeat(position - 1);
+    const after = borderChar.repeat(borderLength - position - textLength - 1) +
+        borderLine.substring(borderLength - 1);
+    return [before, text, after];
+}
+function styleBorderLine(line, color, dim, background) {
+    let styled = applyColor(line, color);
+    if (dim) {
+        styled = chalk.dim(styled);
+    }
+    // The cells a border occupies belong to the surface it frames. Without an
+    // explicit background they diff back to the terminal default, which reads
+    // as a black frame around any bordered surface sitting on a colored one (a
+    // tooltip over the preview card, that card over a tool card) and as a black
+    // hole wherever a Sixel raster is exposed by a border row or column.
+    if (background !== undefined) {
+        styled = applyTextStyles(styled, { backgroundColor: background });
+    }
+    return styled;
+}
+/**
+ * Render the node's border, including any embedded border text, into the
+ * output buffer when a border style is set.
+ * @param x - the border's left column.
+ * @param y - the border's top row.
+ * @param node - the node whose border style to render.
+ * @param output - the output buffer receiving the border writes.
+ * @param background - the surface color the border's cells belong to, when the
+ *   node paints its own rect (own background, `opaque`, or an occlusion color
+ *   while a terminal image sits behind it). Transparent bordered overlays pass
+ *   undefined and keep terminal-transparent border cells.
+ */
+const renderBorder = (x, y, node, output, background) => {
+    if (node.style.borderStyle) {
+        const width = Math.floor(node.yogaNode.getComputedWidth());
+        const height = Math.floor(node.yogaNode.getComputedHeight());
+        const box = typeof node.style.borderStyle === 'string'
+            ? (CUSTOM_BORDER_STYLES[node.style.borderStyle] ?? cliBoxes[node.style.borderStyle])
+            : node.style.borderStyle;
+        const topBorderColor = node.style.borderTopColor ?? node.style.borderColor;
+        const bottomBorderColor = node.style.borderBottomColor ?? node.style.borderColor;
+        const leftBorderColor = node.style.borderLeftColor ?? node.style.borderColor;
+        const rightBorderColor = node.style.borderRightColor ?? node.style.borderColor;
+        const dimTopBorderColor = node.style.borderTopDimColor ?? node.style.borderDimColor;
+        const dimBottomBorderColor = node.style.borderBottomDimColor ?? node.style.borderDimColor;
+        const dimLeftBorderColor = node.style.borderLeftDimColor ?? node.style.borderDimColor;
+        const dimRightBorderColor = node.style.borderRightDimColor ?? node.style.borderDimColor;
+        const showTopBorder = node.style.borderTop !== false;
+        const showBottomBorder = node.style.borderBottom !== false;
+        const showLeftBorder = node.style.borderLeft !== false;
+        const showRightBorder = node.style.borderRight !== false;
+        const contentWidth = Math.max(0, width - (showLeftBorder ? 1 : 0) - (showRightBorder ? 1 : 0));
+        const topBorderLine = showTopBorder
+            ? (showLeftBorder ? box.topLeft : '') +
+                box.top.repeat(contentWidth) +
+                (showRightBorder ? box.topRight : '')
+            : '';
+        // Handle text in top border
+        let topBorder;
+        if (showTopBorder && node.style.borderText?.position === 'top') {
+            const [before, text, after] = embedTextInBorder(topBorderLine, node.style.borderText.content, node.style.borderText.align, node.style.borderText.offset, box.top);
+            topBorder =
+                styleBorderLine(before, topBorderColor, dimTopBorderColor, background) +
+                    text +
+                    styleBorderLine(after, topBorderColor, dimTopBorderColor, background);
+        }
+        else if (showTopBorder) {
+            topBorder = styleBorderLine(topBorderLine, topBorderColor, dimTopBorderColor, background);
+        }
+        let verticalBorderHeight = height;
+        if (showTopBorder) {
+            verticalBorderHeight -= 1;
+        }
+        if (showBottomBorder) {
+            verticalBorderHeight -= 1;
+        }
+        verticalBorderHeight = Math.max(0, verticalBorderHeight);
+        let leftBorder = (applyColor(box.left, leftBorderColor) + '\n').repeat(verticalBorderHeight);
+        if (dimLeftBorderColor) {
+            leftBorder = chalk.dim(leftBorder);
+        }
+        let rightBorder = (applyColor(box.right, rightBorderColor) + '\n').repeat(verticalBorderHeight);
+        if (dimRightBorderColor) {
+            rightBorder = chalk.dim(rightBorder);
+        }
+        if (background !== undefined) {
+            leftBorder = applyTextStyles(leftBorder, { backgroundColor: background });
+            rightBorder = applyTextStyles(rightBorder, { backgroundColor: background });
+        }
+        const bottomBorderLine = showBottomBorder
+            ? (showLeftBorder ? box.bottomLeft : '') +
+                box.bottom.repeat(contentWidth) +
+                (showRightBorder ? box.bottomRight : '')
+            : '';
+        // Handle text in bottom border
+        let bottomBorder;
+        if (showBottomBorder && node.style.borderText?.position === 'bottom') {
+            const [before, text, after] = embedTextInBorder(bottomBorderLine, node.style.borderText.content, node.style.borderText.align, node.style.borderText.offset, box.bottom);
+            bottomBorder =
+                styleBorderLine(before, bottomBorderColor, dimBottomBorderColor, background) +
+                    text +
+                    styleBorderLine(after, bottomBorderColor, dimBottomBorderColor, background);
+        }
+        else if (showBottomBorder) {
+            bottomBorder = styleBorderLine(bottomBorderLine, bottomBorderColor, dimBottomBorderColor, background);
+        }
+        const offsetY = showTopBorder ? 1 : 0;
+        if (topBorder) {
+            output.write(x, y, topBorder);
+        }
+        if (showLeftBorder) {
+            output.write(x, y + offsetY, leftBorder);
+        }
+        if (showRightBorder) {
+            output.write(x + width - 1, y + offsetY, rightBorder);
+        }
+        if (bottomBorder) {
+            output.write(x, y + height - 1, bottomBorder);
+        }
+    }
+};
+export default renderBorder;