@textui/core 0.1.0

package/src/runtime/reconcile.ts

@@ -0,0 +1,335 @@
+import type { BindingPath, ComponentNode, ErrorFallback, RenderError } from '../types/graph.js';
+import type { Runtime } from './runtime.js';
+import type { Instance } from './instance.js';
+import {
+  createInstance, expandTemplate, findFunction, markDirty, normalizeChildren,
+  unmountInstance, updateProps, walkInstances,
+} from './instance.js';
+import { isTemplateChildren } from './bindings.js';
+import { setCurrentInstance } from './hooks.js';
+
+/**
+ * The render pass: a node graph in, a retained instance tree out.
+ *
+ * Two things make this cheap enough to run per frame. Instances are matched by
+ * key and component name, so an unchanged subtree keeps its hooks and its
+ * layout. And an instance is only re-rendered when something marked it dirty -
+ * its own state, a store path it read, or its parent handing it new props.
+ */
+
+export interface RenderOptions {
+  /** Re-render everything, ignoring dirty flags. After a theme change. */
+  force?: boolean;
+  /** Record why each instance rendered. */
+  diagnostics?: boolean;
+}
+
+const MAX_DEPTH = 200;
+
+export function renderTree(
+  runtime: Runtime,
+  root: Instance | null,
+  node: ComponentNode,
+  options: RenderOptions = {},
+): Instance {
+  const instance = reconcile(runtime, null, root ?? undefined, node, options, 0, undefined);
+  return instance;
+}
+
+/** Match by component name and key; anything else is a fresh mount. */
+function canReuse(existing: Instance | undefined, node: ComponentNode): existing is Instance {
+  if (!existing) return false;
+  if (existing.component !== node.component) return false;
+  return existing.key === node.key;
+}
+
+export function reconcile(
+  runtime: Runtime,
+  parent: Instance | null,
+  existing: Instance | undefined,
+  node: ComponentNode,
+  options: RenderOptions,
+  depth: number,
+  dataContext: BindingPath | undefined,
+): Instance {
+  if (depth > MAX_DEPTH) {
+    throw new Error(
+      `[textui] component tree exceeded ${MAX_DEPTH} levels at <${node.component}> - ` +
+      'a component is almost certainly rendering itself',
+    );
+  }
+
+  let instance: Instance;
+  if (canReuse(existing, node)) {
+    instance = existing;
+    instance.parent = parent;
+  } else {
+    if (existing) unmountInstance(existing);
+    instance = createInstance(runtime, node, parent);
+  }
+
+  // The data context has to be in place before props resolve, or a relative
+  // path in a templated row has nothing to resolve against.
+  instance.dataContext = dataContext ?? parent?.dataContext;
+
+  const resolved = findFunction(runtime, node);
+  instance.kind = resolved.kind;
+  instance.fn = resolved.fn;
+  instance.host = resolved.host;
+  instance.definition = resolved.definition;
+
+  const previousProps = instance.props;
+  updateProps(instance, node);
+
+  const propsChanged = !shallowEqual(previousProps, instance.props);
+  const mustRender = options.force || instance.dirty || !instance.mounted || propsChanged;
+
+  if (!mustRender) {
+    // Clean itself, but something below changed: reconcile the children it
+    // produced last time rather than re-running this component.
+    if (instance.childDirty) {
+      instance.childDirty = false;
+      reconcileChildren(runtime, instance, instance.lastChildren, options, depth);
+    }
+    return instance;
+  }
+
+  if (options.diagnostics && !instance.renderReason) {
+    instance.renderReason = !instance.mounted ? 'mount' : propsChanged ? 'props' : 'dirty';
+  }
+
+  instance.dirty = false;
+  instance.childDirty = false;
+  instance.mounted = true;
+  instance.error = undefined;
+
+  subscribeToReads(instance);
+
+  const childNodes = renderToNodes(runtime, instance, options);
+  instance.lastChildren = childNodes;
+  reconcileChildren(runtime, instance, childNodes, options, depth);
+
+  if (!options.diagnostics) instance.renderReason = undefined;
+  return instance;
+}
+
+/** Produce this instance's child nodes, whatever kind it is. */
+function renderToNodes(
+  runtime: Runtime,
+  instance: Instance,
+  options: RenderOptions,
+): { node: ComponentNode; dataContext?: BindingPath }[] {
+  const childrenProp = instance.props.children;
+
+  const wrap = (nodes: ComponentNode[]): { node: ComponentNode }[] =>
+    nodes.map((node) => ({ node }));
+
+  switch (instance.kind) {
+    case 'function': {
+      const fn = instance.fn;
+      if (!fn) return [];
+      setCurrentInstance(instance);
+      try {
+        const output = fn(instance.props);
+        return wrap(normalizeChildren(output));
+      } catch (err) {
+        instance.error = err;
+        runtime.onError(err, `render of <${instance.component}>`);
+        return wrap(normalizeChildren(fallbackFor(instance, err)));
+      } finally {
+        setCurrentInstance(null);
+      }
+    }
+
+    case 'template': {
+      const template = instance.definition?.renderer.kind === 'template'
+        ? instance.definition.renderer.template
+        : null;
+      if (!template) return [];
+      // The template receives this node's props as its data context.
+      return wrap([{ ...template, ...stripStructural(instance.props) }]);
+    }
+
+    case 'host': {
+      if (isTemplateChildren(childrenProp)) {
+        const expanded = expandTemplate(runtime, childrenProp, instance.dataContext);
+        return expanded.nodes.map((node, i) => ({
+          node,
+          dataContext: expanded.contexts[i],
+        }));
+      }
+      return wrap(normalizeChildren(childrenProp));
+    }
+
+    case 'missing': {
+      resolveLazy(runtime, instance);
+      return wrap(normalizeChildren(missingNode(instance, options)));
+    }
+  }
+}
+
+function stripStructural(props: Record<string, unknown>): Record<string, unknown> {
+  const { children: _children, ...rest } = props;
+  return rest;
+}
+
+/** A lazily-registered component resolves in the background and re-renders. */
+function resolveLazy(runtime: Runtime, instance: Instance): void {
+  const def = instance.definition;
+  if (!def || def.renderer.kind !== 'lazy') return;
+  void runtime.components
+    .resolve(instance.component)
+    .then(() => {
+      markDirty(instance, 'lazy component resolved');
+      runtime.requestRender();
+    })
+    .catch((err: unknown) => runtime.onError(err, `resolving <${instance.component}>`));
+}
+
+/**
+ * A name that was never registered is a runtime miss, not a compile error -
+ * that is the price of the graph being data, so the miss has to be visible
+ * rather than silent.
+ */
+function missingNode(instance: Instance, options: RenderOptions): ComponentNode {
+  if (instance.definition?.renderer.kind === 'lazy') {
+    return { component: 'text', content: '', dim: true };
+  }
+  const fallback = instance.node.$meta?.fallback;
+  if (fallback) {
+    // A miss is not a throw, but it is the same question - what does this
+    // render instead - so a fallback answers both.
+    const message = `no component registered as "${instance.component}"`;
+    return applyFallback(fallback, {
+      error: new Error(message), message, component: instance.component,
+    });
+  }
+  return {
+    component: 'text',
+    content: options.diagnostics
+      ? `<${instance.component}?>`
+      : `<${instance.component}>`,
+    fg: 'danger',
+  };
+}
+
+/**
+ * Render a declared fallback.
+ *
+ * A function fallback is handed the failure. A node fallback is handed it as
+ * the `error` and `errorMessage` props, so the graph stays data and a
+ * registered component can render the failure without the registry holding a
+ * function. Props the fallback declares itself win.
+ */
+function applyFallback(fallback: ErrorFallback, failure: RenderError): ComponentNode {
+  if (typeof fallback === 'function') return fallback(failure);
+  return { error: failure.error, errorMessage: failure.message, ...fallback };
+}
+
+function fallbackFor(instance: Instance, err: unknown): ComponentNode {
+  const fallback = instance.node.$meta?.fallback ?? instance.definition?.fallback;
+  const message = err instanceof Error ? err.message : String(err);
+  if (fallback) {
+    return applyFallback(fallback, { error: err, message, component: instance.component });
+  }
+
+  return {
+    component: 'text',
+    content: `${instance.component}: ${message}`,
+    fg: 'danger',
+    wrap: 'word',
+  };
+}
+
+/**
+ * Subscribe to exactly the store paths this instance's props read. Nothing
+ * else re-renders it, which is what keeps a hundred-row list from re-rendering
+ * because an unrelated counter moved.
+ */
+function subscribeToReads(instance: Instance): void {
+  for (const sub of instance.subscriptions) sub.dispose();
+  instance.subscriptions = [];
+
+  if (instance.reads.size === 0) return;
+
+  for (const path of instance.reads) {
+    instance.subscriptions.push(
+      instance.runtime.store.subscribe(path as BindingPath, () => {
+        markDirty(instance, `store ${path}`);
+        instance.runtime.requestRender();
+      }),
+    );
+  }
+}
+
+function reconcileChildren(
+  runtime: Runtime,
+  instance: Instance,
+  childNodes: { node: ComponentNode; dataContext?: BindingPath }[],
+  options: RenderOptions,
+  depth: number,
+): void {
+  const previous = instance.children;
+  const byKey = new Map<string | number, Instance>();
+  for (let i = 0; i < previous.length; i++) {
+    const child = previous[i] as Instance;
+    byKey.set(child.key ?? `__index_${i}`, child);
+  }
+
+  const next: Instance[] = [];
+  const used = new Set<Instance>();
+
+  for (let i = 0; i < childNodes.length; i++) {
+    const entry = childNodes[i] as { node: ComponentNode; dataContext?: BindingPath };
+    const key = entry.node.key ?? `__index_${i}`;
+    const candidate = byKey.get(key);
+    const reusable = candidate && !used.has(candidate) ? candidate : undefined;
+
+    const child = reconcile(
+      runtime, instance, reusable, entry.node, options, depth + 1,
+      entry.dataContext ?? instance.dataContext,
+    );
+
+    if (reusable) used.add(reusable);
+    next.push(child);
+  }
+
+  /*
+   * `next` as a set, because `includes` inside a loop over `previous` is
+   * quadratic - fine for a row of buttons, not for a list with a thousand
+   * children, which is exactly where a reconciler has to stay cheap.
+   *
+   * Built only here, where the answer is needed, rather than alongside `used`.
+   */
+  const kept = new Set(next);
+  for (const child of previous) {
+    if (!used.has(child) && !kept.has(child)) unmountInstance(child);
+  }
+
+  instance.children = next;
+}
+
+function shallowEqual(a: Record<string, unknown>, b: Record<string, unknown>): boolean {
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!Object.is(a[key], b[key])) return false;
+  }
+  return true;
+}
+
+/** Every effect queued during the last render, parents last. */
+export function collectEffects(root: Instance): (() => void)[] {
+  const effects: (() => void)[] = [];
+  walkInstances(root, (instance) => {
+    if (instance.pendingEffects.length === 0) return;
+    effects.push(...instance.pendingEffects);
+    instance.pendingEffects = [];
+  });
+  return effects;
+}
+
+export function disposeTree(root: Instance): void {
+  unmountInstance(root);
+}

package/src/runtime/runtime.ts

@@ -0,0 +1,47 @@
+import type { ReactiveStore, EventBus } from '../types/store.js';
+import type { ComponentRegistry } from '../types/component-registry.js';
+import type { ResolvedTheme } from '../types/theme.js';
+import type { TerminalCapabilities } from '../types/capabilities.js';
+import type { Size } from '../types/geometry.js';
+import type { ServiceContainer } from '../types/services.js';
+import type { FocusManager } from '../types/focus.js';
+import type { LayerManager } from '../types/layer.js';
+import type { AnimationDriver } from '../types/animation.js';
+import type { I18n } from '../types/i18n.js';
+import type { WhenEngine } from '../types/when.js';
+import type { TextUIApp } from '../types/app.js';
+
+/**
+ * What the reconciler and the hooks are allowed to reach.
+ *
+ * Narrower than the app on purpose: the render tree should depend on the few
+ * things it actually uses, so a component can be rendered by the test harness
+ * or the static renderer without an application, a terminal or a frame loop.
+ */
+export interface Runtime {
+  store: ReactiveStore;
+  events: EventBus;
+  when: WhenEngine;
+  components: ComponentRegistry;
+  services: ServiceContainer;
+  focus: FocusManager;
+  layers: LayerManager;
+  animation: AnimationDriver;
+  i18n: I18n;
+
+  theme(): ResolvedTheme;
+  capabilities(): TerminalCapabilities;
+  size(): Size;
+
+  execute(id: string, args?: Record<string, unknown>): unknown;
+  emit(path: string, payload?: unknown): void;
+
+  /** Ask for another frame. Coalesced by the scheduler. */
+  requestRender(): void;
+
+  /** The application, when there is one. Null under the static renderer. */
+  app(): TextUIApp | null;
+
+  /** Where render-time errors go. */
+  onError(err: unknown, context: string): void;
+}

package/src/runtime/style.ts

@@ -0,0 +1,205 @@
+import type { Style, StatefulStyle, StyleInput, BorderSpec, BorderStyle, StyleColor } from '../types/style.js';
+import type { ResolvedTheme } from '../types/theme.js';
+import type { Edges } from '../types/geometry.js';
+import type { Color } from '../types/cells.js';
+import type { BorderChars } from '../types/style.js';
+import {
+  ATTR_BLINK, ATTR_BOLD, ATTR_DIM, ATTR_INVERSE, ATTR_ITALIC,
+  ATTR_STRIKE, ATTR_UNDERLINE,
+} from '../types/cells.js';
+import { packColor, type PackedColor } from '../render/color.js';
+
+/**
+ * Style resolution.
+ *
+ * Five sources, merged in one fixed order so the answer to "why is this blue"
+ * is always the same walk: the theme's entry for this component, the
+ * component's own default, convenience props written inline, the `style` prop,
+ * and finally the state overlay for focus, hover, active, selected, disabled.
+ */
+
+export const STYLE_KEYS = new Set<string>([
+  'display', 'direction', 'gap', 'columnGap', 'rowGap', 'flexWrap', 'padding', 'margin',
+  'width', 'height', 'minWidth', 'maxWidth', 'minHeight', 'maxHeight',
+  'flex', 'shrink', 'basis', 'align', 'alignSelf', 'justify',
+  'position', 'top', 'right', 'bottom', 'left', 'zIndex',
+  'overflow', 'overflowX', 'overflowY',
+  'fg', 'bg', 'bold', 'dim', 'italic', 'underline', 'inverse', 'strike', 'blink',
+  'border', 'wrap', 'textAlign', 'fill', 'scrim', 'scrimStrength',
+]);
+
+export interface InteractionState {
+  focused: boolean;
+  hovered: boolean;
+  active: boolean;
+  selected: boolean;
+  disabled: boolean;
+}
+
+export const NO_INTERACTION: InteractionState = {
+  focused: false, hovered: false, active: false, selected: false, disabled: false,
+};
+
+function isStateful(value: Style | StatefulStyle): value is StatefulStyle {
+  return (
+    'base' in value || 'focus' in value || 'hover' in value ||
+    'active' in value || 'selected' in value || 'disabled' in value
+  );
+}
+
+export function mergeStyles(...styles: (Style | undefined)[]): Style {
+  const out: Style = {};
+  for (const style of styles) {
+    if (!style) continue;
+    Object.assign(out, style);
+  }
+  return out;
+}
+
+/** Flatten a `style` prop, applying state overlays in a fixed order. */
+export function flattenStyleInput(input: StyleInput | undefined, state: InteractionState): Style {
+  if (!input) return {};
+
+  if (Array.isArray(input)) {
+    return mergeStyles(...input.map((item) => (item ? flattenStyleInput(item, state) : undefined)));
+  }
+
+  if (!isStateful(input)) return input;
+
+  // Order matters: selected loses to active, active loses to focus, and
+  // disabled wins over everything - a disabled control is not focusable.
+  return mergeStyles(
+    input.base,
+    state.selected ? input.selected : undefined,
+    state.hovered ? input.hover : undefined,
+    state.active ? input.active : undefined,
+    state.focused ? input.focus : undefined,
+    state.disabled ? input.disabled : undefined,
+  );
+}
+
+/** Pick the style keys written inline as convenience props. */
+export function styleFromProps(props: Record<string, unknown>): Style {
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(props)) {
+    if (STYLE_KEYS.has(key) && props[key] !== undefined) out[key] = props[key];
+  }
+  return out as Style;
+}
+
+export function resolveStyle(
+  props: Record<string, unknown>,
+  theme: ResolvedTheme,
+  component: string,
+  defaultStyle: Style | undefined,
+  state: InteractionState,
+): Style {
+  const variants: string[] = [];
+  if (typeof props.variant === 'string') variants.push(props.variant);
+  if (typeof props.tone === 'string') variants.push(props.tone);
+  if (typeof props.size === 'string') variants.push(props.size);
+
+  return mergeStyles(
+    theme.styleFor(component, variants),
+    defaultStyle,
+    styleFromProps(props),
+    flattenStyleInput(props.style as StyleInput | undefined, state),
+  );
+}
+
+// ------------------------------------------------------------------ colour
+
+/** A token name, a literal colour, or nothing. */
+export function resolveColor(
+  value: StyleColor | undefined,
+  theme: ResolvedTheme,
+  fallback: Color = 'default',
+): Color {
+  if (value === undefined) return fallback;
+  return theme.color(value as string);
+}
+
+export function packStyleColor(
+  value: StyleColor | undefined,
+  theme: ResolvedTheme,
+  fallback: Color = 'default',
+): PackedColor {
+  return packColor(resolveColor(value, theme, fallback));
+}
+
+export function attrsFromStyle(style: Style): number {
+  let attrs = 0;
+  if (style.bold) attrs |= ATTR_BOLD;
+  if (style.dim) attrs |= ATTR_DIM;
+  if (style.italic) attrs |= ATTR_ITALIC;
+  if (style.underline) attrs |= ATTR_UNDERLINE;
+  if (style.inverse) attrs |= ATTR_INVERSE;
+  if (style.strike) attrs |= ATTR_STRIKE;
+  if (style.blink) attrs |= ATTR_BLINK;
+  return attrs;
+}
+
+// ------------------------------------------------------------------ border
+
+export interface ResolvedBorder {
+  style: BorderStyle;
+  chars: BorderChars;
+  color: StyleColor | undefined;
+  /** Per-edge overrides. Undefined here means "use `color`". */
+  colors: { top?: StyleColor; right?: StyleColor; bottom?: StyleColor; left?: StyleColor };
+  dim: boolean;
+  sides: { top: boolean; right: boolean; bottom: boolean; left: boolean };
+  edges: Edges;
+}
+
+const NO_BORDER: ResolvedBorder = {
+  style: 'none',
+  chars: {
+    topLeft: ' ', top: ' ', topRight: ' ', right: ' ', bottomRight: ' ',
+    bottom: ' ', bottomLeft: ' ', left: ' ', cross: ' ',
+    teeTop: ' ', teeBottom: ' ', teeLeft: ' ', teeRight: ' ',
+  },
+  color: undefined,
+  colors: {},
+  dim: false,
+  sides: { top: false, right: false, bottom: false, left: false },
+  edges: { top: 0, right: 0, bottom: 0, left: 0 },
+};
+
+export function resolveBorder(spec: BorderSpec | undefined, theme: ResolvedTheme): ResolvedBorder {
+  if (spec === undefined) return NO_BORDER;
+
+  const style = typeof spec === 'string' ? spec : spec.style ?? theme.border;
+  if (style === 'none') return NO_BORDER;
+
+  // Naming any side means naming all of them. `sides: { left: true }` has to
+  // mean a left rule and nothing else - if unspecified sides defaulted to
+  // true, every panel divider in every shell would draw a full box instead.
+  const sidesSpec = typeof spec === 'string' ? undefined : spec.sides;
+  const sides = sidesSpec
+    ? {
+        top: sidesSpec.top === true,
+        right: sidesSpec.right === true,
+        bottom: sidesSpec.bottom === true,
+        left: sidesSpec.left === true,
+      }
+    : { top: true, right: true, bottom: true, left: true };
+
+  const base = theme.borderChars(style);
+  const chars = typeof spec === 'string' || !spec.chars ? base : { ...base, ...spec.chars };
+
+  return {
+    style,
+    chars,
+    color: typeof spec === 'string' ? undefined : spec.color,
+    colors: typeof spec === 'string' ? {} : spec.colors ?? {},
+    dim: typeof spec !== 'string' && spec.dim === true,
+    sides,
+    edges: {
+      top: sides.top ? 1 : 0,
+      right: sides.right ? 1 : 0,
+      bottom: sides.bottom ? 1 : 0,
+      left: sides.left ? 1 : 0,
+    },
+  };
+}

package/src/themes/borders.ts

@@ -0,0 +1,95 @@
+import type { BorderChars, BorderStyle } from '../types/style.js';
+
+/**
+ * Border glyph sets.
+ *
+ * `ascii` is not a fallback nobody sees - it is what an `unicode: 'ascii'`
+ * terminal actually gets, so it has to look deliberate rather than broken.
+ */
+export const BORDER_SETS: Record<BorderStyle, BorderChars> = {
+  none: {
+    topLeft: ' ', top: ' ', topRight: ' ',
+    right: ' ', bottomRight: ' ', bottom: ' ',
+    bottomLeft: ' ', left: ' ',
+    cross: ' ', teeTop: ' ', teeBottom: ' ', teeLeft: ' ', teeRight: ' ',
+  },
+  single: {
+    topLeft: '┌', top: '─', topRight: '┐',
+    right: '│', bottomRight: '┘', bottom: '─',
+    bottomLeft: '└', left: '│',
+    cross: '┼', teeTop: '┬', teeBottom: '┴', teeLeft: '┤', teeRight: '├',
+  },
+  round: {
+    topLeft: '╭', top: '─', topRight: '╮',
+    right: '│', bottomRight: '╯', bottom: '─',
+    bottomLeft: '╰', left: '│',
+    cross: '┼', teeTop: '┬', teeBottom: '┴', teeLeft: '┤', teeRight: '├',
+  },
+  double: {
+    topLeft: '╔', top: '═', topRight: '╗',
+    right: '║', bottomRight: '╝', bottom: '═',
+    bottomLeft: '╚', left: '║',
+    cross: '╬', teeTop: '╦', teeBottom: '╩', teeLeft: '╣', teeRight: '╠',
+  },
+  bold: {
+    topLeft: '┏', top: '━', topRight: '┓',
+    right: '┃', bottomRight: '┛', bottom: '━',
+    bottomLeft: '┗', left: '┃',
+    cross: '╋', teeTop: '┳', teeBottom: '┻', teeLeft: '┫', teeRight: '┣',
+  },
+  thick: {
+    topLeft: '▛', top: '▀', topRight: '▜',
+    right: '▐', bottomRight: '▟', bottom: '▄',
+    bottomLeft: '▙', left: '▌',
+    cross: '┼', teeTop: '┬', teeBottom: '┴', teeLeft: '┤', teeRight: '├',
+  },
+  half: {
+    topLeft: '▗', top: '▄', topRight: '▖',
+    right: '▌', bottomRight: '▘', bottom: '▀',
+    bottomLeft: '▝', left: '▐',
+    cross: '┼', teeTop: '┬', teeBottom: '┴', teeLeft: '┤', teeRight: '├',
+  },
+  dashed: {
+    topLeft: '┌', top: '╌', topRight: '┐',
+    right: '╎', bottomRight: '┘', bottom: '╌',
+    bottomLeft: '└', left: '╎',
+    cross: '┼', teeTop: '┬', teeBottom: '┴', teeLeft: '┤', teeRight: '├',
+  },
+  ascii: {
+    topLeft: '+', top: '-', topRight: '+',
+    right: '|', bottomRight: '+', bottom: '-',
+    bottomLeft: '+', left: '|',
+    cross: '+', teeTop: '+', teeBottom: '+', teeLeft: '+', teeRight: '+',
+  },
+};
+
+/** What each style degrades to when the terminal cannot draw it. */
+const ASCII_FALLBACK: Record<BorderStyle, BorderStyle> = {
+  none: 'none',
+  single: 'ascii',
+  round: 'ascii',
+  double: 'ascii',
+  bold: 'ascii',
+  thick: 'ascii',
+  half: 'ascii',
+  dashed: 'ascii',
+  ascii: 'ascii',
+};
+
+/** Block-drawing styles need more than the BMP box-drawing range. */
+const BMP_FALLBACK: Partial<Record<BorderStyle, BorderStyle>> = {
+  thick: 'single',
+  half: 'single',
+};
+
+export function borderCharsFor(
+  style: BorderStyle,
+  unicode: 'ascii' | 'bmp' | 'full',
+): BorderChars {
+  if (unicode === 'ascii') return BORDER_SETS[ASCII_FALLBACK[style]] as BorderChars;
+  if (unicode === 'bmp') {
+    const fallback = BMP_FALLBACK[style];
+    return BORDER_SETS[fallback ?? style] as BorderChars;
+  }
+  return BORDER_SETS[style] as BorderChars;
+}