@litfamily/litcodex 1.0.0

package/dist/install/spinner-motion.js

@@ -0,0 +1,51 @@
+import { Worker } from "node:worker_threads";
+const MOTION_WORKER_SOURCE = String.raw `
+const { writeSync } = require("node:fs");
+const { workerData } = require("node:worker_threads");
+const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const state = new Int32Array(workerData.state);
+let frameIndex = 0;
+let timer;
+
+function stopIfRequested() {
+  if (Atomics.load(state, 0) !== 2) return false;
+  if (timer !== undefined) clearInterval(timer);
+  process.exit(0);
+}
+
+function render() {
+  if (stopIfRequested()) return;
+  if (Atomics.compareExchange(state, 0, 0, 1) !== 0) return;
+  try {
+    const frame = frames[frameIndex] ?? frames[0];
+    writeSync(workerData.fd, "\r\u001b[2K  \u001b[38;2;255;176;32m" + frame + "\u001b[39m " + workerData.label);
+    frameIndex = (frameIndex + 1) % frames.length;
+  } finally {
+    Atomics.store(state, 0, 0);
+    Atomics.notify(state, 0);
+  }
+}
+
+render();
+timer = setInterval(render, 80);
+`;
+export function createBlockingSpinnerMotion(fd) {
+    return {
+        start(label) {
+            const state = new Int32Array(new SharedArrayBuffer(4));
+            const worker = new Worker(MOTION_WORKER_SOURCE, {
+                eval: true,
+                workerData: { fd, label, state: state.buffer },
+            });
+            worker.unref();
+            return () => stopMotion(state);
+        },
+    };
+}
+function stopMotion(state) {
+    while (Atomics.compareExchange(state, 0, 0, 2) !== 0) {
+        if (Atomics.load(state, 0) === 2)
+            return;
+        Atomics.wait(state, 0, 1, 50);
+    }
+}

package/dist/install/strict-config-probe.d.ts

@@ -0,0 +1,14 @@
+import { type SpawnLike } from "./codex.js";
+export type StrictConfigProbe = {
+    readonly kind: "accepted";
+} | {
+    readonly kind: "rejected";
+} | {
+    readonly kind: "timeout";
+};
+export declare function probeStrictConfig(args: {
+    readonly codexBin: string;
+    readonly spawn: SpawnLike;
+    readonly overrides: readonly string[];
+    readonly env?: NodeJS.ProcessEnv;
+}): StrictConfigProbe;

package/dist/install/strict-config-probe.js

@@ -0,0 +1,53 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveCodexHome } from "./codex.js";
+const STRICT_CONFIG_PROBE_TIMEOUT_MS = 60_000;
+export function probeStrictConfig(args) {
+    if (args.env === undefined)
+        return runProbe(args);
+    const sourceHome = resolveCodexHome(args.env);
+    const probeHome = mkdtempSync(join(tmpdir(), "litcodex-strict-config-"));
+    try {
+        const sourceConfig = join(sourceHome, "config.toml");
+        if (existsSync(sourceConfig)) {
+            writeFileSync(join(probeHome, "config.toml"), readFileSync(sourceConfig), { mode: 0o600 });
+        }
+        return runProbe({ ...args, env: { ...args.env, CODEX_HOME: probeHome } });
+    }
+    finally {
+        rmSync(probeHome, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
+    }
+}
+function runProbe(args) {
+    const result = args.spawn(args.codexBin, ["--strict-config", ...args.overrides.flatMap((value) => ["-c", value]), "doctor", "--json"], {
+        stdio: "pipe",
+        timeout: STRICT_CONFIG_PROBE_TIMEOUT_MS,
+        ...(args.env === undefined ? {} : { env: args.env }),
+    });
+    if (isTimeout(result))
+        return { kind: "timeout" };
+    if (result.error)
+        return { kind: "rejected" };
+    try {
+        const parsed = JSON.parse(result.stdout ?? "");
+        return configLoadStatus(parsed) === "ok" ? { kind: "accepted" } : { kind: "rejected" };
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return { kind: "rejected" };
+        throw error;
+    }
+}
+function isTimeout(result) {
+    return result.error instanceof Error && "code" in result.error && result.error.code === "ETIMEDOUT";
+}
+function configLoadStatus(value) {
+    if (!isRecord(value) || !isRecord(value["checks"]) || !isRecord(value["checks"]["config.load"]))
+        return null;
+    const status = value["checks"]["config.load"]["status"];
+    return typeof status === "string" ? status : null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/install/types.d.ts

@@ -0,0 +1,102 @@
+/** Parsed, typed install options (parse-don't-validate boundary out of argv). */
+export interface InstallOptions {
+    readonly dryRun: boolean;
+    readonly noTui: boolean;
+    readonly autonomous: boolean;
+    readonly force: boolean;
+    readonly json: boolean;
+    readonly yes: boolean;
+    readonly profile: import("../config-migration/gpt56-policy.js").Gpt56Profile;
+    /** Explicit lead model id (e.g. "gpt-5.6-sol", "gpt-5.6", "gpt-5.6-luna"). */
+    readonly leadModel: string;
+    readonly effort: import("../config-migration/gpt56-policy.js").ReasoningEffort;
+    /** Selected helper route (Codex 0.144.0 has no global helper-default key). */
+    readonly subagentModel: string;
+    readonly subagentEffort: import("../config-migration/gpt56-policy.js").ReasoningEffort;
+    readonly style?: string;
+    readonly reconfigure: boolean;
+    /** Resolved absolute Codex home (never relative). */
+    readonly codexHome: string;
+    /** Stable local marketplace path, or an explicit developer `--repo` override. */
+    readonly repoUrl: string;
+    /** Absolute repo root used to resolve the bundled marketplace metadata / hooks. */
+    readonly repoRoot: string;
+}
+export type InstallStepKind = "marketplace-add" | "plugin-add" | "hooks-register" | "agents-install" | "config-update" | "verify";
+export interface InstallStep {
+    readonly kind: InstallStepKind;
+    /** Human one-line label (LitCodex-native; no legacy tokens). */
+    readonly title: string;
+    /** argv to spawn (always `codex …`), or null for an in-process step. */
+    readonly command: readonly string[] | null;
+    /** True when a prior identical state makes this a probe-gated no-op. */
+    readonly skippable: boolean;
+}
+export type InstallStepStatus = "ok" | "skipped" | "failed";
+export type InstallPreflightStage = "host-capabilities" | "config-dry-run" | "marketplace-payload";
+export interface InstallPreflightResult {
+    readonly stage: InstallPreflightStage;
+    readonly status: Exclude<InstallStepStatus, "failed">;
+    readonly detail: string;
+}
+export interface InstallStepResult {
+    readonly kind: InstallStepKind;
+    readonly status: InstallStepStatus;
+    readonly detail: string;
+    /** Clean child-process lines captured for decorated, post-spinner receipts. */
+    readonly receipts?: readonly string[];
+    readonly agentRoutes?: readonly AgentRoute[];
+}
+export interface AgentRoute {
+    readonly file: string;
+    readonly role: string;
+    readonly model: string;
+    readonly effort: string;
+}
+export interface AgentRoutingReport {
+    readonly healthy: boolean;
+    readonly issues: readonly string[];
+    readonly desiredConfig: string;
+    readonly installedTomls: string;
+    /** Safe user-owned route differences retained during an ordinary reinstall. */
+    readonly preservedRoutes: string;
+    readonly spawnOverride: string;
+    readonly effectiveChild: string;
+}
+export interface InstallResult {
+    readonly ok: boolean;
+    readonly steps: readonly InstallStepResult[];
+    readonly codexHome: string;
+    readonly capabilities?: import("./host-capabilities.js").HostCapabilities;
+}
+export interface DoctorReport {
+    readonly ok: boolean;
+    readonly marketplaceRegistered: boolean;
+    readonly pluginInstalled: boolean;
+    readonly hooksWired: boolean;
+    readonly configManaged: boolean;
+    readonly effectiveConfig: EffectiveConfigReport;
+    readonly agentRouting: AgentRoutingReport;
+    readonly codexBinaryFound: boolean;
+    readonly agentsInstalled: boolean;
+    readonly skillCatalogComplete: boolean;
+    readonly missingSkillIds: readonly string[];
+    readonly missingSkillResourcePaths: readonly string[];
+    readonly handoffInstalled: boolean;
+    readonly scientificVisualizationInstalled: boolean;
+    readonly capabilities: import("./host-capabilities.js").HostCapabilities;
+    readonly issues: readonly string[];
+    readonly warnings: readonly string[];
+    /** Read-only foreground update barrier state; the updater owns the receipt/journal files. */
+    readonly autoUpdate?: AutoUpdateDoctorReport;
+}
+export interface AutoUpdateDoctorReport {
+    readonly enabled: boolean;
+    readonly status: string | null;
+    readonly receiptPath: string;
+    readonly detail: string;
+}
+export interface EffectiveConfigReport {
+    readonly state: "applied" | "preserved" | "unavailable";
+    readonly detail: string;
+}

package/dist/install/types.js

@@ -0,0 +1,5 @@
+// M12 / T17 — installer shared types (S12 §Public-contract types.ts).
+//
+// Pure type declarations only. The installer is self-contained: the ONLY child process it ever
+// spawns is `codex`; no exec-wrapper, no forwarder. `--dry-run` performs zero spawns and zero writes.
+export {};

package/dist/install/uninstall.d.ts

@@ -0,0 +1,26 @@
+import type { SpawnLike } from "./codex.js";
+export interface UninstallFs {
+    existsSync(path: string): boolean;
+    readdirSync(path: string): string[];
+    rmSync(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): void;
+    lstatSync?(path: string): {
+        isSymbolicLink(): boolean;
+        isDirectory(): boolean;
+        isFile?(): boolean;
+    };
+    readFileSync?(path: string, encoding: "utf8"): string;
+    writeFileSync?(path: string, data: string): void;
+}
+export interface UninstallDeps {
+    readonly codexBin: string;
+    readonly codexHome: string;
+    readonly spawn: SpawnLike;
+    readonly fs: UninstallFs;
+}
+export declare function runUninstall(deps: UninstallDeps): {
+    readonly ok: boolean;
+    readonly codexHome: string;
+};

package/dist/install/uninstall.js

@@ -0,0 +1,227 @@
+import { createHash } from "node:crypto";
+import { lstatSync as nativeLstatSync } from "node:fs";
+import { join } from "node:path";
+import { removeSubagentDefaults } from "../config-migration/multi-agent-v2-guard.js";
+import { ensureNativeDefaultAgentConfig } from "../config-migration/native-default-route.js";
+import { NATIVE_DEFAULT_AGENT_FILE } from "./agent-routing.js";
+import { prepareAgentSources } from "./agents-install.js";
+import { isSafeManagedMarketplaceRoot, LITCODEX_MARKETPLACE, LITCODEX_PLUGIN_REF, managedMarketplaceRoot, } from "./marketplace.js";
+import { resolvePackageRoot } from "./package-root.js";
+export function runUninstall(deps) {
+    if (!isSafeUninstallPaths(deps))
+        return { ok: false, codexHome: deps.codexHome };
+    const plugin = deps.spawn(deps.codexBin, ["plugin", "remove", LITCODEX_PLUGIN_REF], { stdio: "inherit" });
+    if (!isSafeUninstallPaths(deps))
+        return { ok: false, codexHome: deps.codexHome };
+    const marketplace = deps.spawn(deps.codexBin, ["plugin", "marketplace", "remove", LITCODEX_MARKETPLACE], {
+        stdio: "inherit",
+    });
+    const pluginOk = !plugin.error && plugin.status === 0;
+    const marketplaceOk = !marketplace.error && marketplace.status === 0;
+    if (!isSafeUninstallPaths(deps))
+        return { ok: false, codexHome: deps.codexHome };
+    if (marketplaceOk) {
+        deps.fs.rmSync(managedMarketplaceRoot(deps.codexHome), { recursive: true, force: true });
+    }
+    removeManagedAgents(deps);
+    removeManagedSubagentDefaults(deps);
+    return { ok: pluginOk && marketplaceOk, codexHome: deps.codexHome };
+}
+function isSafeUninstallPaths(deps) {
+    if (!isSafeManagedMarketplaceRoot(deps.codexHome, deps.fs))
+        return false;
+    const configPath = join(deps.codexHome, "config.toml");
+    try {
+        const stat = deps.fs.lstatSync?.(configPath) ?? nativeLstatSync(configPath);
+        if (stat.isSymbolicLink() || stat.isFile?.() !== true || deps.fs.readFileSync === undefined)
+            return false;
+        try {
+            deps.fs.readFileSync(configPath, "utf8");
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    catch (error) {
+        return error.code === "ENOENT";
+    }
+}
+/** Strip the two managed `[agents]` subagent-default keys from config.toml. Best-effort. */
+function removeManagedSubagentDefaults(deps) {
+    const { readFileSync, writeFileSync } = deps.fs;
+    if (readFileSync === undefined || writeFileSync === undefined)
+        return;
+    const configPath = join(deps.codexHome, "config.toml");
+    if (!deps.fs.existsSync(configPath))
+        return;
+    try {
+        const before = readFileSync(configPath, "utf8");
+        const after = removeSubagentDefaults(before);
+        if (after !== before)
+            writeFileSync(configPath, after);
+    }
+    catch {
+        // Config cleanup must not hide the authoritative Codex removal result.
+    }
+}
+function removeManagedAgents(deps) {
+    if (!isDirectoryNonSymlink(deps, deps.codexHome))
+        return;
+    const managedDefault = join(deps.codexHome, "litcodex-default.toml");
+    if (isManagedNativeDefault(deps, managedDefault) && removeNativeDefaultBinding(deps, managedDefault)) {
+        try {
+            deps.fs.rmSync(managedDefault);
+        }
+        catch {
+            // Best-effort agent cleanup must not hide the authoritative Codex removal result.
+        }
+    }
+    const agentsDir = join(deps.codexHome, "agents");
+    if (!isDirectoryNonSymlink(deps, agentsDir) || deps.fs.readFileSync === undefined)
+        return;
+    try {
+        const repoRoot = resolvePackageRoot();
+        const sources = ["api-key", "chatgpt"].flatMap((authMode) => prepareAgentSources({ now: Date.now, repoRoot, authMode }).sources);
+        for (const file of deps.fs.readdirSync(agentsDir)) {
+            if (file === NATIVE_DEFAULT_AGENT_FILE || !/^litcodex-[^/\\]+\.toml$/.test(file))
+                continue;
+            const path = join(agentsDir, file);
+            if (!isRegularNonSymlink(deps, path))
+                continue;
+            try {
+                const content = deps.fs.readFileSync(path, "utf8");
+                if (sources.some((source) => source.file === file && source.content === content))
+                    deps.fs.rmSync(path);
+            }
+            catch {
+                // Preserve unreadable or unremovable roles while checking independent files.
+            }
+        }
+    }
+    catch {
+        // Best-effort agent cleanup must not hide the authoritative Codex removal result.
+    }
+}
+const MANAGED_DEFAULT_HEADER = [
+    'name = "default"',
+    'description = "General-purpose LitCodex helper route for omitted-agent dispatch."',
+    'nickname_candidates = ["Worker"]',
+];
+const MANAGED_DEFAULT_BODY_SHA256 = "896348bda14e53d96e54edfe3d2d01199810c1a18523c52b03a897a0596934e7";
+const MANAGED_DEFAULT_EFFORTS = {
+    "gpt-5.6": ["high", "xhigh", "max"],
+    "gpt-5.6-sol": ["high", "xhigh", "max"],
+    "gpt-5.6-luna": ["high", "max"],
+    "gpt-5.6-terra": ["high", "xhigh"],
+    "gpt-6-astra": ["low", "medium", "high", "xhigh", "max"],
+};
+function isManagedNativeDefault(deps, path) {
+    if (!deps.fs.existsSync(path) || !isRegularNonSymlink(deps, path) || deps.fs.readFileSync === undefined) {
+        return false;
+    }
+    try {
+        return isManagedNativeDefaultContent(deps.fs.readFileSync(path, "utf8"));
+    }
+    catch {
+        return false;
+    }
+}
+function isDirectoryNonSymlink(deps, path) {
+    try {
+        const stat = deps.fs.lstatSync?.(path) ?? nativeLstatSync(path);
+        return !stat.isSymbolicLink() && stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isRegularNonSymlink(deps, path) {
+    try {
+        const stat = deps.fs.lstatSync?.(path) ?? nativeLstatSync(path);
+        return !stat.isSymbolicLink() && !stat.isDirectory() && stat.isFile?.() === true;
+    }
+    catch {
+        return false;
+    }
+}
+function isManagedNativeDefaultContent(content) {
+    const lines = content.split("\n");
+    if (lines.slice(0, MANAGED_DEFAULT_HEADER.length).join("\n") !== MANAGED_DEFAULT_HEADER.join("\n") ||
+        lines[5] !== "" ||
+        lines[6] !== 'developer_instructions = """') {
+        return false;
+    }
+    const model = lines[3]?.match(/^model = "([^"\r\n]+)"$/u)?.[1] ?? "";
+    const effort = lines[4]?.match(/^model_reasoning_effort = "([^"\r\n]+)"$/u)?.[1] ?? "";
+    const body = lines.slice(6).join("\n");
+    return (MANAGED_DEFAULT_EFFORTS[model]?.includes(effort) === true &&
+        createHash("sha256").update(body).digest("hex") === MANAGED_DEFAULT_BODY_SHA256);
+}
+/** Remove only the generated native binding; ambiguous/user-shaped bindings block target deletion. */
+function removeNativeDefaultBinding(deps, target) {
+    const configPath = join(deps.codexHome, "config.toml");
+    const { readFileSync, writeFileSync } = deps.fs;
+    if (!deps.fs.existsSync(configPath))
+        return true;
+    if (readFileSync === undefined)
+        return false;
+    let before;
+    try {
+        before = readFileSync(configPath, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const after = withoutGeneratedNativeBinding(before, target);
+    if (after === null)
+        return false;
+    if (after === before)
+        return true;
+    if (writeFileSync === undefined)
+        return false;
+    try {
+        writeFileSync(configPath, after);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function withoutGeneratedNativeBinding(config, target) {
+    const block = `[agents.default]\nconfig_file = ${JSON.stringify(target)}\n`;
+    const start = config.indexOf(block);
+    const targetLiterals = [target, JSON.stringify(target)];
+    const mentionsTarget = (value) => targetLiterals.some((literal) => value.includes(literal));
+    if (start < 0) {
+        try {
+            if (ensureNativeDefaultAgentConfig(config, target) === config)
+                return null;
+        }
+        catch {
+            return null;
+        }
+        return mentionsTarget(config) ? null : config;
+    }
+    if (config.indexOf(block, start + block.length) >= 0)
+        return null;
+    try {
+        if (ensureNativeDefaultAgentConfig(config, target) !== config)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const after = config.slice(start + block.length);
+    if (mentionsTarget(config.slice(0, start) + after))
+        return null;
+    for (const line of after.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "")
+            continue;
+        if (trimmed.startsWith("[") && trimmed.endsWith("]"))
+            break;
+        return null;
+    }
+    return config.slice(0, start) + after;
+}

package/dist/postinstall.d.ts

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

package/dist/postinstall.js

@@ -0,0 +1,35 @@
+// npm postinstall welcome banner for litcodex-ai.
+//
+// Prints a fire/ember-branded welcome + next-steps box ONLY on a real `npm install -g` (not CI,
+// not workspace installs, not dev). Wraps everything so a failure exits 0 silently — a postinstall
+// must never break `npm install`. No network, no fs writes, no deps beyond Node built-ins.
+import { createRequire } from "node:module";
+import { renderBanner, shouldDecorate } from "./ui.js";
+function main() {
+    // Gate: only show on a real global install, not CI/workspace/dev.
+    if (process.env["npm_config_global"] !== "true")
+        return;
+    if (process.env["CI"])
+        return;
+    const color = shouldDecorate({ isTty: Boolean(process.stdout.isTTY), env: process.env });
+    const version = createRequire(import.meta.url)("../package.json").version;
+    const banner = renderBanner({ version, color });
+    process.stdout.write(banner);
+    if (color) {
+        const arrow = "\x1b[38;2;255;106;0m›\x1b[0m";
+        process.stdout.write(`  \x1b[1mGet started\x1b[0m\n`);
+        process.stdout.write(`    ${arrow} \x1b[1mlitcodex install\x1b[0m   \x1b[2mregister the Codex plugin + hook\x1b[0m\n`);
+        process.stdout.write(`    ${arrow} then type \x1b[1mlit\x1b[0m in Codex   \x1b[2mand the loop ignites\x1b[0m 🔥\n\n`);
+    }
+    else {
+        process.stdout.write("  Get started\n");
+        process.stdout.write("    > litcodex install   register the Codex plugin + hook\n");
+        process.stdout.write("    > then type  lit  in Codex   and the loop ignites\n\n");
+    }
+}
+try {
+    main();
+}
+catch {
+    // Never fail npm install.
+}

package/dist/ui-style.d.ts

@@ -0,0 +1,23 @@
+export declare function shouldDecorate(opts: {
+    readonly isTty: boolean;
+    readonly env: NodeJS.ProcessEnv;
+    readonly noTui?: boolean;
+    readonly json?: boolean;
+}): boolean;
+export declare function reset(text: string): string;
+export declare function bold(text: string, color: boolean): string;
+export declare function dim(text: string, color: boolean): string;
+export declare function fg(text: string, r: number, g: number, b: number, color: boolean): string;
+export declare function orange(text: string, color: boolean): string;
+export declare function amber(text: string, color: boolean): string;
+export declare function ember(text: string, color: boolean): string;
+export declare function green(text: string, color: boolean): string;
+export declare function red(text: string, color: boolean): string;
+export interface RGB {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+}
+export declare function gradient(text: string, stops: readonly RGB[], color: boolean): string;
+export declare const FIRE_GRADIENT: readonly RGB[];
+export declare const CLEAR_LINE = "\r\u001B[2K";

package/dist/ui-style.js

@@ -0,0 +1,73 @@
+// ANSI styling shared by LitCodex CLI surfaces and the canonical mark's terminal policy.
+import { colorMode } from "@litcodex/lit-loop/dist/lit-mark.js";
+const ESC = "\x1b[";
+const RESET_CODE = `${ESC}0m`;
+export function shouldDecorate(opts) {
+    return !opts.noTui && colorMode(opts) !== "none";
+}
+export function reset(text) {
+    return `${text}${RESET_CODE}`;
+}
+export function bold(text, color) {
+    return color ? `${ESC}1m${text}${RESET_CODE}` : text;
+}
+export function dim(text, color) {
+    return color ? `${ESC}2m${text}${RESET_CODE}` : text;
+}
+export function fg(text, r, g, b, color) {
+    return color ? `${ESC}38;2;${r};${g};${b}m${text}${RESET_CODE}` : text;
+}
+export function orange(text, color) {
+    return fg(text, 255, 106, 0, color);
+}
+export function amber(text, color) {
+    return fg(text, 255, 176, 32, color);
+}
+export function ember(text, color) {
+    return fg(text, 212, 58, 0, color);
+}
+export function green(text, color) {
+    return fg(text, 80, 200, 80, color);
+}
+export function red(text, color) {
+    return fg(text, 230, 60, 60, color);
+}
+function interpolateRgb(stops, t) {
+    const segmentCount = stops.length - 1;
+    const segment = Math.min(Math.floor(t * segmentCount), segmentCount - 1);
+    const local = t * segmentCount - segment;
+    const start = stops[segment] ?? stops[0] ?? { r: 255, g: 106, b: 0 };
+    const end = stops[segment + 1] ?? start;
+    return {
+        r: Math.round(start.r + (end.r - start.r) * local),
+        g: Math.round(start.g + (end.g - start.g) * local),
+        b: Math.round(start.b + (end.b - start.b) * local),
+    };
+}
+export function gradient(text, stops, color) {
+    if (!color || stops.length === 0)
+        return text;
+    const characters = [...text];
+    const visible = characters.filter((character) => character !== " ").length;
+    if (visible === 0)
+        return text;
+    let output = "";
+    let visibleIndex = 0;
+    for (const character of characters) {
+        if (character === " ") {
+            output += character;
+            continue;
+        }
+        const ratio = visible === 1 ? 0 : visibleIndex / (visible - 1);
+        const colorAtCharacter = interpolateRgb(stops, ratio);
+        output += `${ESC}38;2;${colorAtCharacter.r};${colorAtCharacter.g};${colorAtCharacter.b}m${character}`;
+        visibleIndex += 1;
+    }
+    return `${output}${RESET_CODE}`;
+}
+export const FIRE_GRADIENT = [
+    { r: 255, g: 106, b: 0 },
+    { r: 255, g: 176, b: 32 },
+    { r: 212, g: 58, b: 0 },
+];
+export const CLEAR_LINE = `\r${ESC}2K`;

package/dist/ui.d.ts

@@ -0,0 +1,10 @@
+export { renderInstallFailure, renderInstallReceipt, renderPreflightIntro, renderStepIntro, renderStepResult, } from "./install/install-presentation.js";
+export { humanLabel, preflightLabel, Spinner, } from "./install/install-ui.js";
+export * from "./ui-style.js";
+/** Render the canonical LIT banner inside the existing install-plan frame. */
+export declare function renderBanner(opts: {
+    readonly version: string;
+    readonly subtitle?: string;
+    readonly color: boolean;
+    readonly env?: NodeJS.ProcessEnv;
+}): string;

package/dist/ui.js

@@ -0,0 +1,25 @@
+// Public TUI barrel + LitCodex title banner.
+import { banner, colorize, colorMode, sessionLockup, supportsBlocks } from "@litcodex/lit-loop/dist/lit-mark.js";
+import { dim } from "./ui-style.js";
+export { renderInstallFailure, renderInstallReceipt, renderPreflightIntro, renderStepIntro, renderStepResult, } from "./install/install-presentation.js";
+export { humanLabel, preflightLabel, Spinner, } from "./install/install-ui.js";
+export * from "./ui-style.js";
+/** Render the canonical LIT banner inside the existing install-plan frame. */
+export function renderBanner(opts) {
+    const env = opts.env ?? process.env;
+    const blocks = supportsBlocks(env);
+    const mode = colorMode({ isTty: opts.color, env });
+    const rows = blocks ? colorize(banner, { mode }) : ["LIT"];
+    const rule = (blocks ? "━" : "-").repeat(46);
+    return [
+        "",
+        `  ${rule}`,
+        "",
+        ...rows,
+        `${blocks ? sessionLockup : "codex"} v${opts.version}`,
+        `       ${dim(opts.subtitle ?? "loop-native agent harness for Codex", mode !== "none")}`,
+        "",
+        `  ${rule}`,
+        "",
+    ].join("\n");
+}