@textui/core 0.1.0

package/dist/runtime/reconcile.js

@@ -0,0 +1,260 @@
+import { createInstance, expandTemplate, findFunction, markDirty, normalizeChildren, unmountInstance, updateProps, walkInstances, } from './instance.js';
+import { isTemplateChildren } from './bindings.js';
+import { setCurrentInstance } from './hooks.js';
+const MAX_DEPTH = 200;
+export function renderTree(runtime, root, node, options = {}) {
+    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, node) {
+    if (!existing)
+        return false;
+    if (existing.component !== node.component)
+        return false;
+    return existing.key === node.key;
+}
+export function reconcile(runtime, parent, existing, node, options, depth, dataContext) {
+    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;
+    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, instance, options) {
+    const childrenProp = instance.props.children;
+    const wrap = (nodes) => 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) {
+    const { children: _children, ...rest } = props;
+    return rest;
+}
+/** A lazily-registered component resolves in the background and re-renders. */
+function resolveLazy(runtime, instance) {
+    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) => 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, options) {
+    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, failure) {
+    if (typeof fallback === 'function')
+        return fallback(failure);
+    return { error: failure.error, errorMessage: failure.message, ...fallback };
+}
+function fallbackFor(instance, err) {
+    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) {
+    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, () => {
+            markDirty(instance, `store ${path}`);
+            instance.runtime.requestRender();
+        }));
+    }
+}
+function reconcileChildren(runtime, instance, childNodes, options, depth) {
+    const previous = instance.children;
+    const byKey = new Map();
+    for (let i = 0; i < previous.length; i++) {
+        const child = previous[i];
+        byKey.set(child.key ?? `__index_${i}`, child);
+    }
+    const next = [];
+    const used = new Set();
+    for (let i = 0; i < childNodes.length; i++) {
+        const entry = childNodes[i];
+        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, b) {
+    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) {
+    const effects = [];
+    walkInstances(root, (instance) => {
+        if (instance.pendingEffects.length === 0)
+            return;
+        effects.push(...instance.pendingEffects);
+        instance.pendingEffects = [];
+    });
+    return effects;
+}
+export function disposeTree(root) {
+    unmountInstance(root);
+}

package/dist/runtime/runtime.d.ts

@@ -0,0 +1,42 @@
+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;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/runtime/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,QAAQ,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,YAAY,CAAC;IACrB,SAAS,EAAE,eAAe,CAAC;IAC3B,IAAI,EAAE,IAAI,CAAC;IAEX,KAAK,IAAI,aAAa,CAAC;IACvB,YAAY,IAAI,oBAAoB,CAAC;IACrC,IAAI,IAAI,IAAI,CAAC;IAEb,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;IAC7D,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAE5C,yDAAyD;IACzD,aAAa,IAAI,IAAI,CAAC;IAEtB,0EAA0E;IAC1E,GAAG,IAAI,SAAS,GAAG,IAAI,CAAC;IAExB,mCAAmC;IACnC,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9C"}

package/dist/runtime/runtime.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/style.d.ts

@@ -0,0 +1,55 @@
+import type { Style, 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 { 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 declare const STYLE_KEYS: Set<string>;
+export interface InteractionState {
+    focused: boolean;
+    hovered: boolean;
+    active: boolean;
+    selected: boolean;
+    disabled: boolean;
+}
+export declare const NO_INTERACTION: InteractionState;
+export declare function mergeStyles(...styles: (Style | undefined)[]): Style;
+/** Flatten a `style` prop, applying state overlays in a fixed order. */
+export declare function flattenStyleInput(input: StyleInput | undefined, state: InteractionState): Style;
+/** Pick the style keys written inline as convenience props. */
+export declare function styleFromProps(props: Record<string, unknown>): Style;
+export declare function resolveStyle(props: Record<string, unknown>, theme: ResolvedTheme, component: string, defaultStyle: Style | undefined, state: InteractionState): Style;
+/** A token name, a literal colour, or nothing. */
+export declare function resolveColor(value: StyleColor | undefined, theme: ResolvedTheme, fallback?: Color): Color;
+export declare function packStyleColor(value: StyleColor | undefined, theme: ResolvedTheme, fallback?: Color): PackedColor;
+export declare function attrsFromStyle(style: Style): number;
+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;
+}
+export declare function resolveBorder(spec: BorderSpec | undefined, theme: ResolvedTheme): ResolvedBorder;
+//# sourceMappingURL=style.d.ts.map

package/dist/runtime/style.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"style.d.ts","sourceRoot":"","sources":["../../src/runtime/style.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAiB,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAKrD,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjE;;;;;;;GAOG;AAEH,eAAO,MAAM,UAAU,aAQrB,CAAC;AAEH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,eAAO,MAAM,cAAc,EAAE,gBAE5B,CAAC;AASF,wBAAgB,WAAW,CAAC,GAAG,MAAM,EAAE,CAAC,KAAK,GAAG,SAAS,CAAC,EAAE,GAAG,KAAK,CAOnE;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,EAAE,KAAK,EAAE,gBAAgB,GAAG,KAAK,CAmB/F;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAMpE;AAED,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,aAAa,EACpB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,KAAK,GAAG,SAAS,EAC/B,KAAK,EAAE,gBAAgB,GACtB,KAAK,CAYP;AAID,kDAAkD;AAClD,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,KAAK,EAAE,aAAa,EACpB,QAAQ,GAAE,KAAiB,GAC1B,KAAK,CAGP;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,KAAK,EAAE,aAAa,EACpB,QAAQ,GAAE,KAAiB,GAC1B,WAAW,CAEb;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAUnD;AAID,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,UAAU,GAAG,SAAS,CAAC;IAC9B,8DAA8D;IAC9D,MAAM,EAAE;QAAE,GAAG,CAAC,EAAE,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,UAAU,CAAC;QAAC,MAAM,CAAC,EAAE,UAAU,CAAC;QAAC,IAAI,CAAC,EAAE,UAAU,CAAA;KAAE,CAAC;IACzF,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE;QAAE,GAAG,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;IACxE,KAAK,EAAE,KAAK,CAAC;CACd;AAgBD,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,EAAE,KAAK,EAAE,aAAa,GAAG,cAAc,CAoChG"}

package/dist/runtime/style.js

@@ -0,0 +1,143 @@
+import { ATTR_BLINK, ATTR_BOLD, ATTR_DIM, ATTR_INVERSE, ATTR_ITALIC, ATTR_STRIKE, ATTR_UNDERLINE, } from '../types/cells.js';
+import { packColor } 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([
+    '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 const NO_INTERACTION = {
+    focused: false, hovered: false, active: false, selected: false, disabled: false,
+};
+function isStateful(value) {
+    return ('base' in value || 'focus' in value || 'hover' in value ||
+        'active' in value || 'selected' in value || 'disabled' in value);
+}
+export function mergeStyles(...styles) {
+    const out = {};
+    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, state) {
+    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) {
+    const out = {};
+    for (const key of Object.keys(props)) {
+        if (STYLE_KEYS.has(key) && props[key] !== undefined)
+            out[key] = props[key];
+    }
+    return out;
+}
+export function resolveStyle(props, theme, component, defaultStyle, state) {
+    const variants = [];
+    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, state));
+}
+// ------------------------------------------------------------------ colour
+/** A token name, a literal colour, or nothing. */
+export function resolveColor(value, theme, fallback = 'default') {
+    if (value === undefined)
+        return fallback;
+    return theme.color(value);
+}
+export function packStyleColor(value, theme, fallback = 'default') {
+    return packColor(resolveColor(value, theme, fallback));
+}
+export function attrsFromStyle(style) {
+    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;
+}
+const NO_BORDER = {
+    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, theme) {
+    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/dist/themes/borders.d.ts

@@ -0,0 +1,10 @@
+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 declare const BORDER_SETS: Record<BorderStyle, BorderChars>;
+export declare function borderCharsFor(style: BorderStyle, unicode: 'ascii' | 'bmp' | 'full'): BorderChars;
+//# sourceMappingURL=borders.d.ts.map

package/dist/themes/borders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"borders.d.ts","sourceRoot":"","sources":["../../src/themes/borders.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,WAAW,CAuDxD,CAAC;AAqBF,wBAAgB,cAAc,CAC5B,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,GAChC,WAAW,CAOb"}

package/dist/themes/borders.js

@@ -0,0 +1,88 @@
+/**
+ * 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 = {
+    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 = {
+    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 = {
+    thick: 'single',
+    half: 'single',
+};
+export function borderCharsFor(style, unicode) {
+    if (unicode === 'ascii')
+        return BORDER_SETS[ASCII_FALLBACK[style]];
+    if (unicode === 'bmp') {
+        const fallback = BMP_FALLBACK[style];
+        return BORDER_SETS[fallback ?? style];
+    }
+    return BORDER_SETS[style];
+}

package/dist/themes/builtin.d.ts

@@ -0,0 +1,31 @@
+import type { ThemeDefinition } from '../types/theme.js';
+/**
+ * The built-in themes.
+ *
+ * `dark` and `light` are the two bases; everything else extends one of them
+ * and restates only what it changes. The three that follow exist because the
+ * same application should be able to look like a dense operator console, an
+ * airy report or a workbench without a component knowing which - so the
+ * difference lives here, in border style and density, not in the catalog.
+ */
+export declare const DARK: ThemeDefinition;
+export declare const LIGHT: ThemeDefinition;
+/** Dense, bordered, high contrast. Every region is a labelled box. */
+export declare const CONSOLE: ThemeDefinition;
+/** Borderless. Whitespace and alignment do the separating. */
+export declare const PAPER: ThemeDefinition;
+/** Rounded chrome around a persistent frame. */
+export declare const WORKBENCH: ThemeDefinition;
+/** No colour at all. What a `colorDepth: 0` terminal or a pipe gets. */
+export declare const MONO: ThemeDefinition;
+/**
+ * Paper, after dark.
+ *
+ * The same airy, borderless, warm-accented character as `paper` - the point of
+ * it is the restraint, not the brightness - with the ink and the page swapped.
+ * A warm dark rather than a blue one, so the two read as one family and a
+ * reader moving between them is not moving between two different products.
+ */
+export declare const PAPER_DARK: ThemeDefinition;
+export declare const BUILTIN_THEMES: ThemeDefinition[];
+//# sourceMappingURL=builtin.d.ts.map

package/dist/themes/builtin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin.d.ts","sourceRoot":"","sources":["../../src/themes/builtin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;;;;;GAQG;AAEH,eAAO,MAAM,IAAI,EAAE,eA4ClB,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,eA4CnB,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,OAAO,EAAE,eAoCrB,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,KAAK,EAAE,eAiCnB,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,SAAS,EAAE,eAiCvB,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,IAAI,EAAE,eAwClB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,EAAE,eA8BxB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,eAAe,EAE3C,CAAC"}