@slowclap/rezi-core 0.1.0-fork.1

package/dist/theme/types.d.ts

@@ -0,0 +1,24 @@
+import type { Rgb24 } from "../widgets/style.js";
+import type { FocusIndicatorTokens, ThemeDefinition } from "./tokens.js";
+export type ThemeColors = Readonly<{
+    primary: Rgb24;
+    secondary: Rgb24;
+    success: Rgb24;
+    danger: Rgb24;
+    warning: Rgb24;
+    info: Rgb24;
+    muted: Rgb24;
+    bg: Rgb24;
+    fg: Rgb24;
+    border: Rgb24;
+    error: Rgb24;
+    [key: string]: Rgb24;
+}>;
+export type ThemeSpacing = readonly number[];
+export type Theme = Readonly<{
+    definition: ThemeDefinition;
+    colors: ThemeColors;
+    spacing: ThemeSpacing;
+    focusIndicator: FocusIndicatorTokens;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/dist/theme/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/theme/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEzE,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;IACjC,OAAO,EAAE,KAAK,CAAC;IACf,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,KAAK,CAAC;IACd,OAAO,EAAE,KAAK,CAAC;IACf,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,KAAK,CAAC;IACb,EAAE,EAAE,KAAK,CAAC;IACV,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,KAAK,CAAC;IACd,KAAK,EAAE,KAAK,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC;CACtB,CAAC,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,SAAS,MAAM,EAAE,CAAC;AAE7C,MAAM,MAAM,KAAK,GAAG,QAAQ,CAAC;IAC3B,UAAU,EAAE,eAAe,CAAC;IAC5B,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,YAAY,CAAC;IACtB,cAAc,EAAE,oBAAoB,CAAC;CACtC,CAAC,CAAC"}

package/dist/theme/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/theme/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/theme/types.ts"],"names":[],"mappings":""}

package/dist/theme/validate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * packages/core/src/theme/validate.ts — Strict semantic theme validation.
+ *
+ * Why: Ensures custom theme definitions provide all required semantic tokens
+ * with deterministic, path-specific error messages.
+ */
+import type { ThemeDefinition } from "./tokens.js";
+/**
+ * Validate a semantic theme definition.
+ *
+ * Throws on first invalid value with deterministic path-specific errors.
+ * Missing required paths are reported together in deterministic order.
+ */
+export declare function validateTheme(theme: unknown): ThemeDefinition;
+//# sourceMappingURL=validate.d.ts.map

package/dist/theme/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/theme/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AA4JnD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAuB7D"}

package/dist/theme/validate.js

@@ -0,0 +1,165 @@
+/**
+ * packages/core/src/theme/validate.ts — Strict semantic theme validation.
+ *
+ * Why: Ensures custom theme definitions provide all required semantic tokens
+ * with deterministic, path-specific error messages.
+ */
+const REQUIRED_COLOR_PATHS = [
+    "name",
+    "colors.bg.base",
+    "colors.bg.elevated",
+    "colors.bg.overlay",
+    "colors.bg.subtle",
+    "colors.fg.primary",
+    "colors.fg.secondary",
+    "colors.fg.muted",
+    "colors.fg.inverse",
+    "colors.accent.primary",
+    "colors.accent.secondary",
+    "colors.accent.tertiary",
+    "colors.success",
+    "colors.warning",
+    "colors.error",
+    "colors.info",
+    "colors.focus.ring",
+    "colors.focus.bg",
+    "colors.selected.bg",
+    "colors.selected.fg",
+    "colors.disabled.fg",
+    "colors.disabled.bg",
+    "colors.diagnostic.error",
+    "colors.diagnostic.warning",
+    "colors.diagnostic.info",
+    "colors.diagnostic.hint",
+    "colors.border.subtle",
+    "colors.border.default",
+    "colors.border.strong",
+];
+const REQUIRED_WIDGET_COLOR_PATHS = [
+    "widget.syntax.keyword",
+    "widget.syntax.type",
+    "widget.syntax.string",
+    "widget.syntax.number",
+    "widget.syntax.comment",
+    "widget.syntax.operator",
+    "widget.syntax.punctuation",
+    "widget.syntax.function",
+    "widget.syntax.variable",
+    "widget.syntax.cursorFg",
+    "widget.syntax.cursorBg",
+    "widget.diff.addBg",
+    "widget.diff.deleteBg",
+    "widget.diff.addFg",
+    "widget.diff.deleteFg",
+    "widget.diff.hunkHeader",
+    "widget.diff.lineNumber",
+    "widget.diff.border",
+    "widget.logs.trace",
+    "widget.logs.debug",
+    "widget.logs.info",
+    "widget.logs.warn",
+    "widget.logs.error",
+    "widget.toast.info",
+    "widget.toast.success",
+    "widget.toast.warning",
+    "widget.toast.error",
+    "widget.chart.primary",
+    "widget.chart.accent",
+    "widget.chart.muted",
+    "widget.chart.success",
+    "widget.chart.warning",
+    "widget.chart.danger",
+];
+const REQUIRED_SPACING_PATHS = [
+    "spacing.xs",
+    "spacing.sm",
+    "spacing.md",
+    "spacing.lg",
+    "spacing.xl",
+    "spacing.2xl",
+];
+const REQUIRED_FOCUS_STYLE_PATHS = ["focusIndicator.bold", "focusIndicator.underline"];
+const REQUIRED_THEME_PATHS = [
+    ...REQUIRED_COLOR_PATHS,
+    ...REQUIRED_WIDGET_COLOR_PATHS,
+    ...REQUIRED_SPACING_PATHS,
+    ...REQUIRED_FOCUS_STYLE_PATHS,
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getPathValue(root, path) {
+    const parts = path.split(".");
+    let cursor = root;
+    for (const part of parts) {
+        if (!isRecord(cursor) || !(part in cursor))
+            return undefined;
+        cursor = cursor[part];
+    }
+    return cursor;
+}
+function formatValue(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number" ||
+        typeof value === "boolean" ||
+        value === null ||
+        value === undefined) {
+        return String(value);
+    }
+    if (Array.isArray(value))
+        return "[array]";
+    return "[object]";
+}
+function throwMissingPaths(theme) {
+    const missing = REQUIRED_THEME_PATHS.filter((path) => getPathValue(theme, path) === undefined);
+    if (missing.length === 0)
+        return;
+    throw new Error(`Theme validation failed: missing required token path(s): ${missing.join(", ")}`);
+}
+function validateName(path, value) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Theme validation failed at ${path}: expected non-empty string (received ${formatValue(value)})`);
+    }
+}
+function validateRgb(path, value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 0x00ffffff) {
+        throw new Error(`Theme validation failed at ${path}: expected packed Rgb24 integer 0..0x00FFFFFF (received ${formatValue(value)})`);
+    }
+}
+function validateSpacingValue(path, value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new Error(`Theme validation failed at ${path}: spacing token must be a non-negative integer (received ${formatValue(value)})`);
+    }
+}
+function validateFocusStyle(path, value) {
+    if (typeof value !== "boolean") {
+        throw new Error(`Theme validation failed at ${path}: focus indicator style must be a boolean (received ${formatValue(value)})`);
+    }
+}
+/**
+ * Validate a semantic theme definition.
+ *
+ * Throws on first invalid value with deterministic path-specific errors.
+ * Missing required paths are reported together in deterministic order.
+ */
+export function validateTheme(theme) {
+    throwMissingPaths(theme);
+    validateName("name", getPathValue(theme, "name"));
+    for (const path of REQUIRED_COLOR_PATHS) {
+        if (path === "name")
+            continue;
+        validateRgb(path, getPathValue(theme, path));
+    }
+    for (const path of REQUIRED_WIDGET_COLOR_PATHS) {
+        validateRgb(path, getPathValue(theme, path));
+    }
+    for (const path of REQUIRED_SPACING_PATHS) {
+        validateSpacingValue(path, getPathValue(theme, path));
+    }
+    for (const path of REQUIRED_FOCUS_STYLE_PATHS) {
+        validateFocusStyle(path, getPathValue(theme, path));
+    }
+    return theme;
+}
+//# sourceMappingURL=validate.js.map

package/dist/theme/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/theme/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,oBAAoB,GAAG;IAC3B,MAAM;IACN,gBAAgB;IAChB,oBAAoB;IACpB,mBAAmB;IACnB,kBAAkB;IAClB,mBAAmB;IACnB,qBAAqB;IACrB,iBAAiB;IACjB,mBAAmB;IACnB,uBAAuB;IACvB,yBAAyB;IACzB,wBAAwB;IACxB,gBAAgB;IAChB,gBAAgB;IAChB,cAAc;IACd,aAAa;IACb,mBAAmB;IACnB,iBAAiB;IACjB,oBAAoB;IACpB,oBAAoB;IACpB,oBAAoB;IACpB,oBAAoB;IACpB,yBAAyB;IACzB,2BAA2B;IAC3B,wBAAwB;IACxB,wBAAwB;IACxB,sBAAsB;IACtB,uBAAuB;IACvB,sBAAsB;CACd,CAAC;AAEX,MAAM,2BAA2B,GAAG;IAClC,uBAAuB;IACvB,oBAAoB;IACpB,sBAAsB;IACtB,sBAAsB;IACtB,uBAAuB;IACvB,wBAAwB;IACxB,2BAA2B;IAC3B,wBAAwB;IACxB,wBAAwB;IACxB,wBAAwB;IACxB,wBAAwB;IACxB,mBAAmB;IACnB,sBAAsB;IACtB,mBAAmB;IACnB,sBAAsB;IACtB,wBAAwB;IACxB,wBAAwB;IACxB,oBAAoB;IACpB,mBAAmB;IACnB,mBAAmB;IACnB,kBAAkB;IAClB,kBAAkB;IAClB,mBAAmB;IACnB,mBAAmB;IACnB,sBAAsB;IACtB,sBAAsB;IACtB,oBAAoB;IACpB,sBAAsB;IACtB,qBAAqB;IACrB,oBAAoB;IACpB,sBAAsB;IACtB,sBAAsB;IACtB,qBAAqB;CACb,CAAC;AAEX,MAAM,sBAAsB,GAAG;IAC7B,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,aAAa;CACL,CAAC;AAEX,MAAM,0BAA0B,GAAG,CAAC,qBAAqB,EAAE,0BAA0B,CAAU,CAAC;AAEhG,MAAM,oBAAoB,GAAG;IAC3B,GAAG,oBAAoB;IACvB,GAAG,2BAA2B;IAC9B,GAAG,sBAAsB;IACzB,GAAG,0BAA0B;CACrB,CAAC;AAEX,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,YAAY,CAAC,IAAa,EAAE,IAAY;IAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM,GAAY,IAAI,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,MAAM,CAAC;YAAE,OAAO,SAAS,CAAC;QAC7D,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC5D,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,KAAK,KAAK,SAAS;QAC1B,KAAK,KAAK,IAAI;QACd,KAAK,KAAK,SAAS,EACnB,CAAC;QACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAc;IACvC,MAAM,OAAO,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC;IAC/F,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACjC,MAAM,IAAI,KAAK,CAAC,4DAA4D,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACpG,CAAC;AAED,SAAS,YAAY,CAAC,IAAY,EAAE,KAAc;IAChD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CACb,8BAA8B,IAAI,yCAAyC,WAAW,CAAC,KAAK,CAAC,GAAG,CACjG,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,IAAY,EAAE,KAAc;IAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,UAAU,EAAE,CAAC;QAC7F,MAAM,IAAI,KAAK,CACb,8BAA8B,IAAI,2DAA2D,WAAW,CAAC,KAAK,CAAC,GAAG,CACnH,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,oBAAoB,CAAC,IAAY,EAAE,KAAc;IACxD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACvE,MAAM,IAAI,KAAK,CACb,8BAA8B,IAAI,4DAA4D,WAAW,CAAC,KAAK,CAAC,GAAG,CACpH,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAY,EAAE,KAAc;IACtD,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,8BAA8B,IAAI,uDAAuD,WAAW,CAAC,KAAK,CAAC,GAAG,CAC/G,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAEzB,YAAY,CAAC,MAAM,EAAE,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IAElD,KAAK,MAAM,IAAI,IAAI,oBAAoB,EAAE,CAAC;QACxC,IAAI,IAAI,KAAK,MAAM;YAAE,SAAS;QAC9B,WAAW,CAAC,IAAI,EAAE,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,2BAA2B,EAAE,CAAC;QAC/C,WAAW,CAAC,IAAI,EAAE,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,sBAAsB,EAAE,CAAC;QAC1C,oBAAoB,CAAC,IAAI,EAAE,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,0BAA0B,EAAE,CAAC;QAC9C,kBAAkB,CAAC,IAAI,EAAE,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,KAAwB,CAAC;AAClC,CAAC"}

package/dist/ui/capabilities.d.ts

@@ -0,0 +1,70 @@
+/**
+ * packages/core/src/ui/capabilities.ts — Capability tier detection.
+ *
+ * Why: Provides a simple A/B/C capability tier abstraction derived from
+ * terminal capabilities. Widgets and recipes use the tier to adapt styling
+ * (e.g., color depth, glyph selection, shadow effects).
+ *
+ * Tiers:
+ *   A — 16/256-color + unicode box drawing (no images)
+ *   B — Truecolor (24-bit RGB)
+ *   C — Enhanced: truecolor + image protocols (kitty/sixel/iterm2) or sub-cell canvas
+ *
+ * @see docs/design-system.md
+ */
+import type { TerminalCaps } from "../terminalCaps.js";
+import type { TerminalProfile } from "../terminalProfile.js";
+/**
+ * Capability tier: A (basic), B (truecolor), C (enhanced/images).
+ */
+export type CapabilityTier = "A" | "B" | "C";
+/**
+ * Resolved capability context passed to recipes and widgets.
+ */
+export type CapabilityContext = Readonly<{
+    /** The resolved tier */
+    tier: CapabilityTier;
+    /** True if truecolor (24-bit) is supported */
+    truecolor: boolean;
+    /** True if any image protocol is available */
+    hasImageProtocol: boolean;
+    /** True if extended underline styles work */
+    hasUnderlineStyles: boolean;
+    /** True if colored underlines work */
+    hasColoredUnderlines: boolean;
+    /** True if hyperlinks are supported */
+    hasHyperlinks: boolean;
+}>;
+/**
+ * Derive the capability tier from terminal capabilities.
+ *
+ * @param caps - Terminal capabilities from the engine
+ * @param profile - Optional terminal profile for image protocol detection
+ * @returns The resolved capability tier
+ */
+export declare function getCapabilityTier(caps: TerminalCaps, profile?: TerminalProfile): CapabilityTier;
+/**
+ * Build a full capability context from terminal capabilities.
+ *
+ * @param caps - Terminal capabilities from the engine
+ * @param profile - Optional terminal profile for extended detection
+ * @returns Resolved capability context
+ */
+export declare function resolveCapabilityContext(caps: TerminalCaps, profile?: TerminalProfile): CapabilityContext;
+/**
+ * Default capability context (conservative: Tier A).
+ */
+export declare const DEFAULT_CAPABILITY_CONTEXT: CapabilityContext;
+/**
+ * Map an RGB color to the nearest 256-color palette index.
+ *
+ * Used for Tier A color fallback. Implements the standard xterm-256 color
+ * cube mapping with grayscale ramp.
+ *
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @returns Nearest 256-color palette index (16-255)
+ */
+export declare function rgbTo256(r: number, g: number, b: number): number;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/ui/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/ui/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,wBAAwB;IACxB,IAAI,EAAE,cAAc,CAAC;IACrB,8CAA8C;IAC9C,SAAS,EAAE,OAAO,CAAC;IACnB,8CAA8C;IAC9C,gBAAgB,EAAE,OAAO,CAAC;IAC1B,6CAA6C;IAC7C,kBAAkB,EAAE,OAAO,CAAC;IAC5B,sCAAsC;IACtC,oBAAoB,EAAE,OAAO,CAAC;IAC9B,uCAAuC;IACvC,aAAa,EAAE,OAAO,CAAC;CACxB,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,cAAc,CAW/F;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,YAAY,EAClB,OAAO,CAAC,EAAE,eAAe,GACxB,iBAAiB,CAenB;AAED;;GAEG;AACH,eAAO,MAAM,0BAA0B,EAAE,iBAOvC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAuBhE"}

package/dist/ui/capabilities.js

@@ -0,0 +1,94 @@
+/**
+ * packages/core/src/ui/capabilities.ts — Capability tier detection.
+ *
+ * Why: Provides a simple A/B/C capability tier abstraction derived from
+ * terminal capabilities. Widgets and recipes use the tier to adapt styling
+ * (e.g., color depth, glyph selection, shadow effects).
+ *
+ * Tiers:
+ *   A — 16/256-color + unicode box drawing (no images)
+ *   B — Truecolor (24-bit RGB)
+ *   C — Enhanced: truecolor + image protocols (kitty/sixel/iterm2) or sub-cell canvas
+ *
+ * @see docs/design-system.md
+ */
+import { COLOR_MODE_RGB } from "../terminalCaps.js";
+/**
+ * Derive the capability tier from terminal capabilities.
+ *
+ * @param caps - Terminal capabilities from the engine
+ * @param profile - Optional terminal profile for image protocol detection
+ * @returns The resolved capability tier
+ */
+export function getCapabilityTier(caps, profile) {
+    const isTruecolor = caps.colorMode === COLOR_MODE_RGB;
+    if (!isTruecolor)
+        return "A";
+    // Check for image protocol support
+    const hasImages = profile !== undefined &&
+        (profile.supportsKittyGraphics || profile.supportsSixel || profile.supportsIterm2Images);
+    return hasImages ? "C" : "B";
+}
+/**
+ * Build a full capability context from terminal capabilities.
+ *
+ * @param caps - Terminal capabilities from the engine
+ * @param profile - Optional terminal profile for extended detection
+ * @returns Resolved capability context
+ */
+export function resolveCapabilityContext(caps, profile) {
+    const tier = getCapabilityTier(caps, profile);
+    const truecolor = caps.colorMode === COLOR_MODE_RGB;
+    return Object.freeze({
+        tier,
+        truecolor,
+        hasImageProtocol: profile !== undefined &&
+            (profile.supportsKittyGraphics || profile.supportsSixel || profile.supportsIterm2Images),
+        hasUnderlineStyles: caps.supportsUnderlineStyles || (profile?.supportsUnderlineStyles ?? false),
+        hasColoredUnderlines: caps.supportsColoredUnderlines || (profile?.supportsColoredUnderlines ?? false),
+        hasHyperlinks: caps.supportsHyperlinks || (profile?.supportsHyperlinks ?? false),
+    });
+}
+/**
+ * Default capability context (conservative: Tier A).
+ */
+export const DEFAULT_CAPABILITY_CONTEXT = Object.freeze({
+    tier: "A",
+    truecolor: false,
+    hasImageProtocol: false,
+    hasUnderlineStyles: false,
+    hasColoredUnderlines: false,
+    hasHyperlinks: false,
+});
+/**
+ * Map an RGB color to the nearest 256-color palette index.
+ *
+ * Used for Tier A color fallback. Implements the standard xterm-256 color
+ * cube mapping with grayscale ramp.
+ *
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @returns Nearest 256-color palette index (16-255)
+ */
+export function rgbTo256(r, g, b) {
+    // Check if grayscale is a better match
+    const gray = Math.round(0.2126 * r + 0.7152 * g + 0.0722 * b);
+    // 6x6x6 color cube (indices 16-231)
+    const ri = Math.round((r / 255) * 5);
+    const gi = Math.round((g / 255) * 5);
+    const bi = Math.round((b / 255) * 5);
+    const cubeIndex = 16 + 36 * ri + 6 * gi + bi;
+    // Reconstruct the cube color for distance comparison
+    const cubeR = ri * 51;
+    const cubeG = gi * 51;
+    const cubeB = bi * 51;
+    const cubeDist = (r - cubeR) ** 2 + (g - cubeG) ** 2 + (b - cubeB) ** 2;
+    // Grayscale ramp (indices 232-255): 24 shades from 8 to 238
+    const grayIndex = Math.round((gray - 8) / 10);
+    const clampedGrayIndex = Math.max(0, Math.min(23, grayIndex));
+    const grayValue = 8 + clampedGrayIndex * 10;
+    const grayDist = (r - grayValue) ** 2 + (g - grayValue) ** 2 + (b - grayValue) ** 2;
+    return grayDist < cubeDist ? 232 + clampedGrayIndex : cubeIndex;
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/ui/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/ui/capabilities.ts"],"names":[],"mappings":"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"}

package/dist/ui/designTokens.d.ts

@@ -0,0 +1,114 @@
+/**
+ * packages/core/src/ui/designTokens.ts — Extended design tokens.
+ *
+ * Why: Provides typography roles, elevation levels, and spacing presets
+ * that build on top of the base token system in theme/tokens.ts.
+ * These are the "design system layer" that widgets and recipes consume.
+ *
+ * @see docs/design-system.md
+ */
+import { type ColorTokens, type ThemeDefinition } from "../theme/tokens.js";
+import type { Rgb24 } from "../widgets/style.js";
+/**
+ * Typography role names.
+ */
+export type TypographyRole = "title" | "subtitle" | "body" | "caption" | "code" | "label" | "muted";
+/**
+ * Resolved typography style: TextStyle attributes for a given role.
+ */
+export type TypographyStyle = Readonly<{
+    fg: Rgb24;
+    bg?: Rgb24;
+    bold?: boolean;
+    dim?: boolean;
+    italic?: boolean;
+}>;
+/**
+ * Resolve a typography role to a TextStyle using theme colors.
+ */
+export declare function resolveTypography(colors: ColorTokens, role: TypographyRole): TypographyStyle;
+/**
+ * Elevation level for surfaces.
+ * 0 = base, 1 = card/panel, 2 = dropdown/overlay, 3 = modal.
+ */
+export type ElevationLevel = 0 | 1 | 2 | 3;
+/**
+ * Resolved surface style for a given elevation.
+ */
+export type SurfaceStyle = Readonly<{
+    /** Background color for this surface level */
+    bg: Rgb24;
+    /** Border color (none for level 0) */
+    border: Rgb24 | null;
+    /** Whether to render a shadow */
+    shadow: false | Readonly<{
+        density: "light" | "medium" | "dense";
+        offsetX?: number;
+        offsetY?: number;
+    }>;
+}>;
+/**
+ * Resolve a surface style for a given elevation level.
+ */
+export declare function resolveSurface(colors: ColorTokens, level: ElevationLevel): SurfaceStyle;
+/**
+ * Size variant for interactive widgets.
+ */
+export type WidgetSize = "sm" | "md" | "lg";
+/**
+ * Resolved spacing for a given widget size.
+ */
+export type SizeSpacing = Readonly<{
+    /** Horizontal padding (cells) */
+    px: number;
+    /** Vertical padding (cells) */
+    py: number;
+}>;
+type SizeSpacingInput = ThemeDefinition["spacing"] | readonly number[] | undefined;
+/**
+ * Resolve spacing for a widget size.
+ * If theme spacing tokens are provided, widget spacing derives from that scale.
+ */
+export declare function resolveSize(size: WidgetSize, spacing?: SizeSpacingInput): SizeSpacing;
+/**
+ * Visual variant for interactive widgets.
+ */
+export type WidgetVariant = "solid" | "soft" | "outline" | "ghost";
+/**
+ * Tone modifier for widget variants.
+ */
+export type WidgetTone = "default" | "primary" | "danger" | "success" | "warning";
+/**
+ * Resolve the accent color for a given tone.
+ */
+export declare function resolveToneColor(colors: ColorTokens, tone: WidgetTone): Rgb24;
+/**
+ * Resolve foreground color for text on a tone-colored background.
+ */
+export declare function resolveToneFg(colors: ColorTokens, tone: WidgetTone): Rgb24;
+/**
+ * Interactive widget state.
+ */
+export type WidgetState = "default" | "active-item" | "focus" | "pressed" | "disabled" | "loading" | "error" | "selected";
+/**
+ * Density setting for layout.
+ */
+export type Density = "compact" | "comfortable";
+/**
+ * Resolve gap size for a density setting.
+ */
+export declare function resolveDensityGap(density: Density): number;
+/**
+ * Resolve padding for a density setting.
+ */
+export declare function resolveDensityPadding(density: Density): number;
+/**
+ * Border variant for surfaces and containers.
+ */
+export type BorderVariant = "none" | "single" | "rounded" | "double" | "heavy" | "dashed";
+/**
+ * Resolve border variant for a given elevation and focus state.
+ */
+export declare function resolveBorderVariant(elevation: ElevationLevel, focused: boolean): BorderVariant;
+export {};
+//# sourceMappingURL=designTokens.d.ts.map

package/dist/ui/designTokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"designTokens.d.ts","sourceRoot":"","sources":["../../src/ui/designTokens.ts"],"names":[],"mappings":"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"}

package/dist/ui/designTokens.js

@@ -0,0 +1,144 @@
+/**
+ * packages/core/src/ui/designTokens.ts — Extended design tokens.
+ *
+ * Why: Provides typography roles, elevation levels, and spacing presets
+ * that build on top of the base token system in theme/tokens.ts.
+ * These are the "design system layer" that widgets and recipes consume.
+ *
+ * @see docs/design-system.md
+ */
+import { DEFAULT_THEME_SPACING } from "../theme/tokens.js";
+/**
+ * Resolve a typography role to a TextStyle using theme colors.
+ */
+export function resolveTypography(colors, role) {
+    switch (role) {
+        case "title":
+            return { fg: colors.fg.primary, bold: true };
+        case "subtitle":
+            return { fg: colors.fg.secondary, bold: true };
+        case "body":
+            return { fg: colors.fg.primary };
+        case "caption":
+            return { fg: colors.fg.secondary, dim: true, italic: true };
+        case "code":
+            return { fg: colors.accent.tertiary, bg: colors.bg.elevated };
+        case "label":
+            return { fg: colors.fg.primary, bold: true };
+        case "muted":
+            return { fg: colors.fg.muted, dim: true, italic: true };
+    }
+}
+/**
+ * Resolve a surface style for a given elevation level.
+ */
+export function resolveSurface(colors, level) {
+    switch (level) {
+        case 0:
+            return { bg: colors.bg.base, border: null, shadow: false };
+        case 1:
+            return { bg: colors.bg.elevated, border: colors.border.subtle, shadow: false };
+        case 2:
+            return {
+                bg: colors.bg.overlay,
+                border: colors.border.default,
+                shadow: { density: "light" },
+            };
+        case 3:
+            return {
+                bg: colors.bg.overlay,
+                border: colors.border.strong,
+                shadow: { density: "medium" },
+            };
+    }
+}
+function resolveSpacingToken(input, fallback) {
+    if (typeof input !== "number" || !Number.isFinite(input) || input < 0) {
+        return fallback;
+    }
+    return Math.trunc(input);
+}
+function isLegacySpacingInput(spacing) {
+    return Array.isArray(spacing);
+}
+/**
+ * Resolve spacing for a widget size.
+ * If theme spacing tokens are provided, widget spacing derives from that scale.
+ */
+export function resolveSize(size, spacing) {
+    let semanticSpacing;
+    let legacySpacing;
+    if (isLegacySpacingInput(spacing)) {
+        legacySpacing = spacing;
+    }
+    else {
+        semanticSpacing = spacing;
+    }
+    const legacyIsSemanticScale = (legacySpacing?.length ?? 0) >= 7;
+    const legacySmIndex = legacyIsSemanticScale ? 2 : 1;
+    const legacyMdIndex = legacyIsSemanticScale ? 3 : 2;
+    const legacyLgIndex = legacyIsSemanticScale ? 4 : 3;
+    const smPx = resolveSpacingToken(semanticSpacing?.sm ?? legacySpacing?.[legacySmIndex], DEFAULT_THEME_SPACING.sm);
+    const mdPx = resolveSpacingToken(semanticSpacing?.md ?? legacySpacing?.[legacyMdIndex], DEFAULT_THEME_SPACING.md);
+    const lgPx = resolveSpacingToken(semanticSpacing?.lg ?? legacySpacing?.[legacyLgIndex], DEFAULT_THEME_SPACING.lg);
+    switch (size) {
+        case "sm":
+            return { px: smPx, py: 0 };
+        case "md":
+            return { px: mdPx, py: 0 };
+        case "lg":
+            return { px: lgPx, py: 1 };
+    }
+}
+/**
+ * Resolve the accent color for a given tone.
+ */
+export function resolveToneColor(colors, tone) {
+    switch (tone) {
+        case "default":
+        case "primary":
+            return colors.accent.primary;
+        case "danger":
+            return colors.error;
+        case "success":
+            return colors.success;
+        case "warning":
+            return colors.warning;
+    }
+}
+/**
+ * Resolve foreground color for text on a tone-colored background.
+ */
+export function resolveToneFg(colors, tone) {
+    return colors.fg.inverse;
+}
+/**
+ * Resolve gap size for a density setting.
+ */
+export function resolveDensityGap(density) {
+    return density === "compact" ? 0 : 1;
+}
+/**
+ * Resolve padding for a density setting.
+ */
+export function resolveDensityPadding(density) {
+    return density === "compact" ? 0 : 1;
+}
+/**
+ * Resolve border variant for a given elevation and focus state.
+ */
+export function resolveBorderVariant(elevation, focused) {
+    if (focused)
+        return "heavy";
+    switch (elevation) {
+        case 0:
+            return "none";
+        case 1:
+            return "rounded";
+        case 2:
+            return "single";
+        case 3:
+            return "rounded";
+    }
+}
+//# sourceMappingURL=designTokens.js.map