aimux-cli 0.1.0

package/dist/instance-registry.js

@@ -0,0 +1,208 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import * as lockfile from "proper-lockfile";
+import { getInstancesPath, getAimuxDirFor } from "./paths.js";
+import { findMainRepo } from "./worktree.js";
+import { debug } from "./debug.js";
+const HEARTBEAT_STALE_MS = 15_000;
+const LOCK_RETRIES = { retries: 5, minTimeout: 50 };
+/**
+ * Check if a PID is alive.
+ */
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Filter out dead instances (dead PID or stale heartbeat).
+ */
+function pruneDeadEntries(instances) {
+    const now = Date.now();
+    return instances.filter((inst) => {
+        if (!isPidAlive(inst.pid)) {
+            debug(`pruning dead instance ${inst.instanceId} (PID ${inst.pid} dead)`, "instance");
+            return false;
+        }
+        const heartbeatAge = now - new Date(inst.heartbeat).getTime();
+        if (heartbeatAge > HEARTBEAT_STALE_MS) {
+            debug(`pruning stale instance ${inst.instanceId} (heartbeat ${Math.round(heartbeatAge / 1000)}s old)`, "instance");
+            return false;
+        }
+        return true;
+    });
+}
+/**
+ * Read instances.json, returning empty array if missing or corrupt.
+ */
+function readInstancesFile(filePath) {
+    if (!existsSync(filePath))
+        return [];
+    try {
+        return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Ensure the directory for the instances file exists and the file is created.
+ */
+function ensureInstancesFile(filePath) {
+    const dir = filePath.replace(/\/[^/]+$/, "");
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    if (!existsSync(filePath)) {
+        writeFileSync(filePath, "[]");
+    }
+}
+/**
+ * Run an operation against instances.json with locking.
+ * Operates on both the global project state dir and the main repo (for cross-worktree discovery).
+ */
+async function withLockedInstances(cwd, fn) {
+    const paths = getInstancesPaths(cwd);
+    for (const filePath of paths) {
+        ensureInstancesFile(filePath);
+        let release;
+        try {
+            release = await lockfile.lock(filePath, { retries: LOCK_RETRIES });
+            const instances = readInstancesFile(filePath);
+            const updated = fn(instances, filePath);
+            writeFileSync(filePath, JSON.stringify(updated, null, 2) + "\n");
+        }
+        finally {
+            if (release)
+                await release();
+        }
+    }
+}
+/**
+ * Get all instances.json paths to update (global project state + main repo .aimux/ if different).
+ * The global path is primary; the in-repo path is for cross-worktree discovery by older instances.
+ */
+function getInstancesPaths(cwd) {
+    const globalPath = getInstancesPath();
+    const paths = [globalPath];
+    // Also write to in-repo .aimux/ for backward compat with older instances
+    try {
+        const mainRepo = findMainRepo(cwd);
+        const inRepoPath = join(getAimuxDirFor(mainRepo), "instances.json");
+        if (inRepoPath !== globalPath) {
+            paths.push(inRepoPath);
+        }
+    }
+    catch {
+        // Not in a git repo or worktree detection failed — global only
+    }
+    return paths;
+}
+/**
+ * Register this instance in instances.json.
+ */
+export async function registerInstance(instanceId, cwd) {
+    let remoteInstances = [];
+    await withLockedInstances(cwd, (instances) => {
+        const pruned = pruneDeadEntries(instances);
+        const entry = {
+            instanceId,
+            pid: process.pid,
+            startedAt: new Date().toISOString(),
+            heartbeat: new Date().toISOString(),
+            cwd,
+            sessions: [],
+        };
+        const updated = [...pruned, entry];
+        remoteInstances = pruned.filter((i) => i.instanceId !== instanceId);
+        return updated;
+    });
+    if (remoteInstances.length > 0) {
+        debug(`registered instance ${instanceId}, found ${remoteInstances.length} other instance(s)`, "instance");
+    }
+    else {
+        debug(`registered instance ${instanceId} (sole instance)`, "instance");
+    }
+    return remoteInstances;
+}
+/**
+ * Unregister this instance from instances.json.
+ */
+export async function unregisterInstance(instanceId, cwd) {
+    await withLockedInstances(cwd, (instances) => {
+        return instances.filter((i) => i.instanceId !== instanceId);
+    });
+    debug(`unregistered instance ${instanceId}`, "instance");
+}
+/**
+ * Update heartbeat timestamp and sessions list. Also prunes dead instances.
+ * Returns the session IDs that were in the registry BEFORE this update
+ * (so the caller can detect which were claimed by comparing against expectations).
+ */
+export async function updateHeartbeat(instanceId, sessions, cwd) {
+    // Collect previous session IDs across ALL instances.json files (global + in-repo).
+    // withLockedInstances calls the callback once per file, so we merge results.
+    const allPreviousIds = new Set();
+    await withLockedInstances(cwd, (instances) => {
+        // Prune dead instances, but never prune ourselves — we know we're alive
+        const pruned = pruneDeadEntries(instances.filter((i) => i.instanceId !== instanceId));
+        const self = instances.find((i) => i.instanceId === instanceId);
+        const result = pruned.map((inst) => inst);
+        if (self) {
+            for (const s of self.sessions)
+                allPreviousIds.add(s.id);
+            result.push({ ...self, heartbeat: new Date().toISOString(), sessions });
+        }
+        return result;
+    });
+    return [...allPreviousIds];
+}
+/**
+ * Get instances belonging to other aimux processes.
+ * Reads from all known instances.json files for cross-worktree visibility.
+ */
+export function getRemoteInstances(ownInstanceId, cwd) {
+    const paths = getInstancesPaths(cwd);
+    const seen = new Set();
+    const result = [];
+    for (const filePath of paths) {
+        const instances = readInstancesFile(filePath);
+        const alive = pruneDeadEntries(instances);
+        for (const inst of alive) {
+            if (inst.instanceId !== ownInstanceId && !seen.has(inst.instanceId)) {
+                seen.add(inst.instanceId);
+                result.push(inst);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Remove a session from another instance's entry (takeover step).
+ * Returns the claimed session ref, or undefined if not found.
+ */
+export async function claimSession(sessionId, fromInstanceId, cwd) {
+    let claimed;
+    await withLockedInstances(cwd, (instances) => {
+        return instances.map((inst) => {
+            if (inst.instanceId === fromInstanceId) {
+                const session = inst.sessions.find((s) => s.id === sessionId);
+                if (session) {
+                    claimed = session;
+                    debug(`claimed session ${sessionId} from instance ${fromInstanceId}`, "instance");
+                    return {
+                        ...inst,
+                        sessions: inst.sessions.filter((s) => s.id !== sessionId),
+                    };
+                }
+            }
+            return inst;
+        });
+    });
+    return claimed;
+}
+//# sourceMappingURL=instance-registry.js.map

package/dist/instance-registry.js.map

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

package/dist/key-parser.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Terminal CSI escape sequence parser.
+ *
+ * Normalizes raw terminal key sequences into a clean KeyEvent format.
+ * Handles xterm modifyOtherKeys, kitty keyboard protocol, and standard CSI.
+ *
+ * This is the single choke point for all terminal key handling —
+ * swap this module to change the parsing strategy.
+ */
+export interface KeyEvent {
+    /** The printable character, or empty for special keys */
+    char: string;
+    /** Named key: "enter", "tab", "backspace", "escape", "up", "down", "left", "right", "home", "end", "delete", "pageup", "pagedown", "f1"-"f12", "focusin", "focusout" */
+    name: string;
+    shift: boolean;
+    ctrl: boolean;
+    alt: boolean;
+    /** The raw input string (for debugging) */
+    raw: string;
+}
+/**
+ * Parse raw stdin data into KeyEvents.
+ * Returns an array because a single stdin chunk can contain multiple key sequences.
+ */
+export declare function parseKeys(data: Buffer | string): KeyEvent[];
+/**
+ * Check if a KeyEvent matches a key descriptor.
+ * Examples: "ctrl+o", "shift+enter", "ctrl+shift+left", "alt+b"
+ */
+export declare function matchKey(event: KeyEvent, descriptor: string): boolean;

package/dist/key-parser.js

@@ -0,0 +1,272 @@
+/**
+ * Terminal CSI escape sequence parser.
+ *
+ * Normalizes raw terminal key sequences into a clean KeyEvent format.
+ * Handles xterm modifyOtherKeys, kitty keyboard protocol, and standard CSI.
+ *
+ * This is the single choke point for all terminal key handling —
+ * swap this module to change the parsing strategy.
+ */
+// Modifier bitmask (shared by xterm and standard CSI):
+// 1=none, 2=shift, 3=alt, 4=shift+alt, 5=ctrl, 6=ctrl+shift, 7=ctrl+alt, 8=ctrl+shift+alt
+function parseModifier(mod) {
+    const m = mod - 1; // convert to 0-based bitmask
+    return {
+        shift: !!(m & 1),
+        alt: !!(m & 2),
+        ctrl: !!(m & 4),
+    };
+}
+const KEYCODE_NAMES = {
+    9: "tab",
+    13: "enter",
+    27: "escape",
+    127: "backspace",
+};
+const CSI_FINAL_NAMES = {
+    A: "up",
+    B: "down",
+    C: "right",
+    D: "left",
+    H: "home",
+    F: "end",
+};
+const CSI_TILDE_NAMES = {
+    1: "home",
+    2: "insert",
+    3: "delete",
+    4: "end",
+    5: "pageup",
+    6: "pagedown",
+    11: "f1",
+    12: "f2",
+    13: "f3",
+    14: "f4",
+    15: "f5",
+    17: "f6",
+    18: "f7",
+    19: "f8",
+    20: "f9",
+    21: "f10",
+    23: "f11",
+    24: "f12",
+};
+/**
+ * Parse raw stdin data into KeyEvents.
+ * Returns an array because a single stdin chunk can contain multiple key sequences.
+ */
+export function parseKeys(data) {
+    const str = typeof data === "string" ? data : data.toString("utf-8");
+    const events = [];
+    let i = 0;
+    while (i < str.length) {
+        // ESC sequence
+        if (str[i] === "\x1b") {
+            // Bracketed paste: ESC [200~ ... ESC [201~
+            // Terminals wrap pasted text in these markers
+            if (str.startsWith("\x1b[200~", i)) {
+                const pasteStart = i + 6; // skip ESC [200~
+                const pasteEnd = str.indexOf("\x1b[201~", pasteStart);
+                const content = pasteEnd >= 0 ? str.slice(pasteStart, pasteEnd) : str.slice(pasteStart); // no end marker yet — take everything
+                if (content) {
+                    events.push({ char: content, name: "paste", shift: false, ctrl: false, alt: false, raw: content });
+                }
+                i = pasteEnd >= 0 ? pasteEnd + 6 : str.length;
+                continue;
+            }
+            // CSI: ESC [
+            if (i + 1 < str.length && str[i + 1] === "[") {
+                const parsed = parseCSI(str, i + 2);
+                if (parsed) {
+                    parsed.event.raw = str.slice(i, i + 2 + parsed.consumed);
+                    events.push(parsed.event);
+                    i += 2 + parsed.consumed;
+                    continue;
+                }
+            }
+            // SS3: ESC O (used by some terminals for arrow keys, function keys)
+            if (i + 1 < str.length && str[i + 1] === "O") {
+                if (i + 2 < str.length) {
+                    const ch = str[i + 2];
+                    const name = CSI_FINAL_NAMES[ch];
+                    if (name) {
+                        events.push({ char: "", name, shift: false, ctrl: false, alt: false, raw: str.slice(i, i + 3) });
+                        i += 3;
+                        continue;
+                    }
+                    // SS3 P-S = F1-F4
+                    if (ch >= "P" && ch <= "S") {
+                        const fNum = ch.charCodeAt(0) - "P".charCodeAt(0) + 1;
+                        events.push({
+                            char: "",
+                            name: `f${fNum}`,
+                            shift: false,
+                            ctrl: false,
+                            alt: false,
+                            raw: str.slice(i, i + 3),
+                        });
+                        i += 3;
+                        continue;
+                    }
+                }
+            }
+            // ESC + single char = Alt+char (meta key)
+            if (i + 1 < str.length && str[i + 1] !== "\x1b") {
+                const ch = str[i + 1];
+                const code = ch.charCodeAt(0);
+                // Map control characters to their names (e.g., 0x7F = backspace, 0x0D = enter)
+                const ctrlName = code === 127 || code === 8
+                    ? "backspace"
+                    : code === 13
+                        ? "enter"
+                        : code === 9
+                            ? "tab"
+                            : code < 32
+                                ? String.fromCharCode(code + 96) // Ctrl+letter
+                                : "";
+                events.push({
+                    char: ctrlName ? "" : ch,
+                    name: ctrlName || ch,
+                    shift: false,
+                    ctrl: code < 32 && code !== 13 && code !== 9 && code !== 8,
+                    alt: true,
+                    raw: str.slice(i, i + 2),
+                });
+                i += 2;
+                continue;
+            }
+            // Lone ESC
+            events.push({ char: "", name: "escape", shift: false, ctrl: false, alt: false, raw: "\x1b" });
+            i++;
+            continue;
+        }
+        // Control characters
+        const code = str.charCodeAt(i);
+        if (code < 32 || code === 127) {
+            if (code === 13) {
+                events.push({ char: "", name: "enter", shift: false, ctrl: false, alt: false, raw: str[i] });
+            }
+            else if (code === 9) {
+                events.push({ char: "", name: "tab", shift: false, ctrl: false, alt: false, raw: str[i] });
+            }
+            else if (code === 127 || code === 8) {
+                events.push({ char: "", name: "backspace", shift: false, ctrl: false, alt: false, raw: str[i] });
+            }
+            else {
+                // Ctrl+letter: Ctrl+A = 1, Ctrl+B = 2, ..., Ctrl+Z = 26
+                const letter = String.fromCharCode(code + 96); // 1 -> 'a', etc.
+                events.push({ char: "", name: letter, shift: false, ctrl: true, alt: false, raw: str[i] });
+            }
+            i++;
+            continue;
+        }
+        // Regular printable character(s) — batch consecutive printable chars
+        let end = i + 1;
+        while (end < str.length && str.charCodeAt(end) >= 32 && str[end] !== "\x1b") {
+            end++;
+        }
+        const chars = str.slice(i, end);
+        events.push({ char: chars, name: "", shift: false, ctrl: false, alt: false, raw: chars });
+        i = end;
+    }
+    return events;
+}
+/**
+ * Parse CSI sequence parameters (after ESC [).
+ * Returns the parsed event and number of characters consumed after "ESC [".
+ */
+function parseCSI(str, start) {
+    // Collect parameter bytes (digits and semicolons) and the final byte
+    let i = start;
+    let params = "";
+    // Collect parameter bytes: 0x30-0x3F (digits, semicolons, etc.)
+    while (i < str.length && str.charCodeAt(i) >= 0x30 && str.charCodeAt(i) <= 0x3f) {
+        params += str[i];
+        i++;
+    }
+    // Final byte: 0x40-0x7E
+    if (i >= str.length)
+        return null;
+    const finalByte = str[i];
+    const finalCode = finalByte.charCodeAt(0);
+    if (finalCode < 0x40 || finalCode > 0x7e)
+        return null;
+    const consumed = i - start + 1;
+    const parts = params.split(";").map(Number);
+    // Kitty keyboard protocol: ESC [ keycode ; modifier u
+    if (finalByte === "u") {
+        const keycode = parts[0] ?? 0;
+        const mods = parseModifier(parts[1] ?? 1);
+        const name = KEYCODE_NAMES[keycode] ?? "";
+        const char = name ? "" : String.fromCharCode(keycode);
+        return {
+            event: { char, name: name || char, ...mods, raw: "" },
+            consumed,
+        };
+    }
+    // xterm modifyOtherKeys: ESC [ 27 ; modifier ; keycode ~
+    if (finalByte === "~" && parts[0] === 27 && parts.length >= 3) {
+        const mods = parseModifier(parts[1] ?? 1);
+        const keycode = parts[2] ?? 0;
+        const name = KEYCODE_NAMES[keycode] ?? "";
+        const char = name ? "" : String.fromCharCode(keycode);
+        return {
+            event: { char, name: name || char, ...mods, raw: "" },
+            consumed,
+        };
+    }
+    // Standard CSI with tilde: ESC [ number ~ (with optional modifier)
+    if (finalByte === "~") {
+        const keyNum = parts[0] ?? 0;
+        const mods = parseModifier(parts[1] ?? 1);
+        const name = CSI_TILDE_NAMES[keyNum] ?? "";
+        if (name) {
+            return {
+                event: { char: "", name, ...mods, raw: "" },
+                consumed,
+            };
+        }
+        return null;
+    }
+    // Standard CSI arrow/nav: ESC [ (modifier ;)? final
+    // e.g., ESC [ 1 ; 2 A = Shift+Up
+    if (finalByte === "I") {
+        return {
+            event: { char: "", name: "focusin", shift: false, ctrl: false, alt: false, raw: "" },
+            consumed,
+        };
+    }
+    if (finalByte === "O") {
+        return {
+            event: { char: "", name: "focusout", shift: false, ctrl: false, alt: false, raw: "" },
+            consumed,
+        };
+    }
+    const name = CSI_FINAL_NAMES[finalByte];
+    if (name) {
+        // Modifier is in the last param if there are two parts
+        const mod = parts.length >= 2 ? (parts[1] ?? 1) : 1;
+        const mods = parseModifier(mod);
+        return {
+            event: { char: "", name, ...mods, raw: "" },
+            consumed,
+        };
+    }
+    return null;
+}
+/**
+ * Check if a KeyEvent matches a key descriptor.
+ * Examples: "ctrl+o", "shift+enter", "ctrl+shift+left", "alt+b"
+ */
+export function matchKey(event, descriptor) {
+    const parts = descriptor.toLowerCase().split("+");
+    const key = parts.pop();
+    const wantCtrl = parts.includes("ctrl");
+    const wantShift = parts.includes("shift");
+    const wantAlt = parts.includes("alt");
+    return (event.ctrl === wantCtrl &&
+        event.shift === wantShift &&
+        event.alt === wantAlt &&
+        (event.name === key || event.char === key));
+}
+//# sourceMappingURL=key-parser.js.map

package/dist/key-parser.js.map

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

package/dist/last-used.d.ts

@@ -0,0 +1,31 @@
+export interface LastUsedEntry {
+    lastUsedAt: string;
+}
+export interface LastUsedClientState {
+    recentIds: string[];
+    updatedAt: string;
+}
+export interface LastUsedState {
+    version: number;
+    items: Record<string, LastUsedEntry>;
+    clients: Record<string, LastUsedClientState>;
+    projectRecentIds: string[];
+    updatedAt?: string;
+}
+export interface MarkLastUsedOptions {
+    itemId: string;
+    clientSession?: string;
+    usedAt?: string;
+}
+export declare function getLastUsedPath(projectRoot: string): string;
+export declare function loadLastUsedState(projectRoot: string): LastUsedState;
+export declare function markLastUsed(projectRoot: string, options: MarkLastUsedOptions): LastUsedState;
+export declare function getLastUsedAt(projectRoot: string, itemId: string): string | undefined;
+export declare function getRecentRankMap(projectRoot: string, clientSession?: string): Map<string, number>;
+export declare function compareLastUsed(left: {
+    id: string;
+    lastUsedAt?: string;
+}, right: {
+    id: string;
+    lastUsedAt?: string;
+}, rankMap: Map<string, number>): number;

package/dist/last-used.js

@@ -0,0 +1,93 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { getProjectStateDirFor } from "./paths.js";
+import { join } from "node:path";
+import { parseRecencyTimestamp } from "./recency.js";
+const LAST_USED_VERSION = 1;
+const MAX_RECENT_IDS = 64;
+const EMPTY_STATE = {
+    version: LAST_USED_VERSION,
+    items: {},
+    clients: {},
+    projectRecentIds: [],
+};
+export function getLastUsedPath(projectRoot) {
+    return join(getProjectStateDirFor(projectRoot), "last-used.json");
+}
+export function loadLastUsedState(projectRoot) {
+    const path = getLastUsedPath(projectRoot);
+    if (!existsSync(path))
+        return { ...EMPTY_STATE };
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return normalizeLastUsedState(parsed);
+    }
+    catch {
+        return { ...EMPTY_STATE };
+    }
+}
+export function markLastUsed(projectRoot, options) {
+    const itemId = options.itemId?.trim();
+    if (!itemId)
+        return loadLastUsedState(projectRoot);
+    const usedAt = options.usedAt?.trim() || new Date().toISOString();
+    const state = loadLastUsedState(projectRoot);
+    state.items[itemId] = { lastUsedAt: usedAt };
+    state.projectRecentIds = pushRecentId(state.projectRecentIds, itemId);
+    const clientSession = options.clientSession?.trim();
+    if (clientSession) {
+        const existing = state.clients[clientSession] ?? { recentIds: [], updatedAt: usedAt };
+        state.clients[clientSession] = {
+            recentIds: pushRecentId(existing.recentIds, itemId),
+            updatedAt: usedAt,
+        };
+    }
+    state.updatedAt = usedAt;
+    persistLastUsedState(projectRoot, state);
+    return state;
+}
+export function getLastUsedAt(projectRoot, itemId) {
+    return loadLastUsedState(projectRoot).items[itemId]?.lastUsedAt;
+}
+export function getRecentRankMap(projectRoot, clientSession) {
+    const state = loadLastUsedState(projectRoot);
+    const clientIds = clientSession ? (state.clients[clientSession]?.recentIds ?? []) : [];
+    const ordered = [...clientIds, ...state.projectRecentIds.filter((id) => !clientIds.includes(id))];
+    return new Map(ordered.map((id, index) => [id, index]));
+}
+export function compareLastUsed(left, right, rankMap) {
+    const leftRank = rankMap.get(left.id) ?? Number.MAX_SAFE_INTEGER;
+    const rightRank = rankMap.get(right.id) ?? Number.MAX_SAFE_INTEGER;
+    if (leftRank !== rightRank)
+        return leftRank - rightRank;
+    const leftUsedAt = parseRecencyTimestamp(left.lastUsedAt) ?? 0;
+    const rightUsedAt = parseRecencyTimestamp(right.lastUsedAt) ?? 0;
+    return rightUsedAt - leftUsedAt;
+}
+function persistLastUsedState(projectRoot, state) {
+    const dir = getProjectStateDirFor(projectRoot);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(getLastUsedPath(projectRoot), JSON.stringify(state, null, 2));
+}
+function normalizeLastUsedState(state) {
+    const items = Object.fromEntries(Object.entries(state.items ?? {}).flatMap(([itemId, value]) => typeof value?.lastUsedAt === "string" ? [[itemId, { lastUsedAt: value.lastUsedAt }]] : []));
+    const clients = Object.fromEntries(Object.entries(state.clients ?? {}).map(([clientSession, value]) => [
+        clientSession,
+        {
+            recentIds: Array.isArray(value?.recentIds) ? value.recentIds.filter(Boolean).slice(0, MAX_RECENT_IDS) : [],
+            updatedAt: typeof value?.updatedAt === "string" ? value.updatedAt : "",
+        },
+    ]));
+    return {
+        version: LAST_USED_VERSION,
+        items,
+        clients,
+        projectRecentIds: Array.isArray(state.projectRecentIds)
+            ? state.projectRecentIds.filter(Boolean).slice(0, MAX_RECENT_IDS)
+            : [],
+        updatedAt: typeof state.updatedAt === "string" ? state.updatedAt : undefined,
+    };
+}
+function pushRecentId(ids, itemId) {
+    return [itemId, ...ids.filter((entry) => entry !== itemId)].slice(0, MAX_RECENT_IDS);
+}
+//# sourceMappingURL=last-used.js.map