Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
/** Pure, shared by Images and Video. The backend owns order (pinned, then newest or manual key);
* this only reproduces it so a click lands instantly. */
export const GALLERY_CHANGED_EVENT = "unsloth:gallery-changed";
export type GalleryKind = "images" | "videos" | "audio";
/** Both pages stay mounted and load only on mount, so a restore from Settings needs this. */
export function notifyGalleryChanged(kind: GalleryKind): void {
if (typeof window === "undefined") return;
window.dispatchEvent(new CustomEvent(GALLERY_CHANGED_EVENT, { detail: { kind } }));
}
/** Calls back when kind changed elsewhere. Returns an unsubscriber. */
export function subscribeGalleryChanged(kind: GalleryKind, onChanged: () => void): () => void {
if (typeof window === "undefined") return () => {};
const handler = (event: Event) => {
const detail = (event as CustomEvent<{ kind?: string }>).detail;
if (detail?.kind === kind) onChanged();
};
window.addEventListener(GALLERY_CHANGED_EVENT, handler);
return () => window.removeEventListener(GALLERY_CHANGED_EVENT, handler);
}
export const ARCHIVE_CHANGED_EVENT = "unsloth:archive-changed";
/** Announce that the archived shelf of `kind` changed from Settings (a restore or a delete). Kept apart
* from the gallery event so a delete, which leaves the active strip as it was, does not refetch it. */
export function notifyArchiveChanged(kind: GalleryKind): void {
if (typeof window === "undefined") return;
window.dispatchEvent(new CustomEvent(ARCHIVE_CHANGED_EVENT, { detail: { kind } }));
}
/** Calls back when the archive of `kind` changed elsewhere. Returns an unsubscriber. */
export function subscribeArchiveChanged(kind: GalleryKind, onChanged: () => void): () => void {
if (typeof window === "undefined") return () => {};
const handler = (event: Event) => {
const detail = (event as CustomEvent<{ kind?: string }>).detail;
if (detail?.kind === kind) onChanged();
};
window.addEventListener(ARCHIVE_CHANGED_EVENT, handler);
return () => window.removeEventListener(ARCHIVE_CHANGED_EVENT, handler);
}
/** The two fields these helpers care about; both gallery record types structurally satisfy it. */
export interface FlaggableItem {
id: string;
pinned?: boolean;
archived?: boolean;
/** Epoch seconds (drag key, else file mtime). */
order_at?: number | null;
created_at: number | string;
}
/** Images store seconds, videos an ISO string. */
function orderKey(item: FlaggableItem): number {
if (typeof item.order_at === "number") return item.order_at;
return typeof item.created_at === "number"
? item.created_at
: Date.parse(item.created_at) / 1000;
}
function newestFirst<T extends FlaggableItem>(a: T, b: T): number {
return orderKey(b) - orderKey(a);
}
/** Pins keep ARRIVAL order (the server sorts by pin time, which the client never learns), except
* `justPinnedId`, which leads. */
export function sortGalleryItems<T extends FlaggableItem>(items: T[], justPinnedId?: string): T[] {
const pinned = items.filter((i) => i.pinned);
const rest = items.filter((i) => !i.pinned);
rest.sort(newestFirst);
if (justPinnedId) {
const at = pinned.findIndex((i) => i.id === justPinnedId);
if (at > 0) pinned.unshift(...pinned.splice(at, 1));
}
return [...pinned, ...rest];
}
/** Archiving is `removeGalleryItem`, not this. */
export function applyPin<T extends FlaggableItem>(items: T[], id: string, pinned: boolean): T[] {
const next = items.map((i) => (i.id === id ? { ...i, pinned } : i));
return sortGalleryItems(next, pinned ? id : undefined);
}
/** Backend pin rule: between pins pins it, between unpinned unpins it, on the boundary keeps it.
* Returns `items` unchanged for a no-op. */
export function moveGalleryItem<T extends FlaggableItem>(
items: T[],
id: string,
afterId: string | null,
): T[] {
const from = items.findIndex((i) => i.id === id);
if (from < 0 || afterId === id) return items;
const rest = items.filter((i) => i.id !== id);
const at = afterId === null ? 0 : rest.findIndex((i) => i.id === afterId) + 1;
if (afterId !== null && at === 0) return items;
const moved = items[from];
const above = rest[at - 1];
const below = rest[at];
const pinned =
above && below
? Boolean(above.pinned) === Boolean(below.pinned)
? Boolean(above.pinned)
: Boolean(moved.pinned)
: Boolean((above ?? below ?? moved).pinned);
if (at === from && pinned === Boolean(moved.pinned)) return items;
return [...rest.slice(0, at), { ...moved, pinned }, ...rest.slice(at)];
}
/** In a filtered view hidden neighbours would decide the pin, so keep the shown state. */
export function scopedMoveAfterId<T extends FlaggableItem>(
items: T[],
inView: (item: T) => boolean,
id: string,
afterId: string | null,
): string | null {
const view = items.filter(inView);
const intended = moveGalleryItem(view, id, afterId);
if (intended === view) return afterId;
const at = intended.findIndex((i) => i.id === id);
const wantPinned = Boolean(intended[at]?.pinned);
const above = intended[at - 1];
const below = intended[at + 1];
const rest = items.filter((i) => i.id !== id);
const first = above ? rest.findIndex((i) => i.id === above.id) : -1;
const last = below ? rest.findIndex((i) => i.id === below.id) : rest.length;
for (let gap = first; gap < last; gap++) {
const candidate = gap < 0 ? null : rest[gap].id;
const moved = moveGalleryItem(items, id, candidate).find((i) => i.id === id);
if (Boolean(moved?.pinned) === wantPinned) return candidate;
}
return afterId;
}
export function pinnedOrder<T extends FlaggableItem>(items: T[]): string[] {
return items.filter((i) => i.pinned).map((i) => i.id);
}
/** `applyPin(..., true)` would promote it to the head. Ids absent from `order` were pinned
* mid-request and score -1, so the newest pin leads. */
export function restorePinOrder<T extends FlaggableItem>(
items: T[],
id: string,
order: readonly string[],
): T[] {
const next = items.map((i) => (i.id === id ? { ...i, pinned: true } : i));
const pinned = next.filter((i) => i.pinned);
const rest = next.filter((i) => !i.pinned);
rest.sort(newestFirst);
pinned.sort((a, b) => order.indexOf(a.id) - order.indexOf(b.id));
return [...pinned, ...rest];
}
/** Drops any a concurrent load already brought in. */
export function mergeGenerated<T extends FlaggableItem>(items: T[], fresh: T[]): T[] {
const known = new Set(items.map((i) => i.id));
return sortGalleryItems([...fresh.filter((i) => !known.has(i.id)), ...items]);
}
/** Bounds a recovery probe so a huge pin count cannot scan the gallery. */
export const NEW_RECORD_PROBE_MAX_PAGES = 5;
/** Proves a generation whose POST response was lost reached the server. A saved record is the
* first UNPINNED row, not row 0. */
export interface NewRecordProbeBaseline {
knownIds: ReadonlySet<string>;
/** An all-pinned window with more pages behind it cannot judge, since every unpinned row is
* unfamiliar. */
canJudgeUnpinned: boolean;
}
export function newRecordProbeBaseline<T extends FlaggableItem>(
loaded: T[],
hasMore: boolean,
knownIds: ReadonlySet<string>,
): NewRecordProbeBaseline {
return { knownIds, canJudgeUnpinned: loaded.some((i) => !i.pinned) || !hasMore };
}
export async function hasUnknownRecord<T extends FlaggableItem>(
baseline: NewRecordProbeBaseline,
fetchPage: (offset: number) => Promise<{ items: T[]; hasMore: boolean }>,
pageSize: number,
maxPages: number = NEW_RECORD_PROBE_MAX_PAGES,
): Promise<boolean> {
// Refuse to claim proof; the caller reports the submission error loudly.
if (!baseline.canJudgeUnpinned) return false;
for (let page = 0; page < maxPages; page += 1) {
const { items, hasMore } = await fetchPage(page * pageSize);
for (const record of items) {
// A saved record is never pinned, so an unfamiliar pin is not evidence.
if (record.pinned) continue;
return !baseline.knownIds.has(record.id);
}
if (!hasMore || items.length === 0) return false;
}
return false;
}
/** Dropped once a key goes idle so the map stays small. */
const queues = new Map<string, Promise<unknown>>();
/** Click order per key; keys stay parallel. A rejection does not break the chain. */
export function serializeById<T>(key: string, task: () => Promise<T>): Promise<T> {
const previous = queues.get(key);
const run = previous ? previous.then(task, task) : task();
const settled = run.then(
() => {},
() => {},
);
queues.set(key, settled);
void settled.then(() => {
// Only the last link clears the key.
if (queues.get(key) === settled) queues.delete(key);
});
return run;
}
export function removeGalleryItem<T extends FlaggableItem>(items: T[], id: string): T[] {
return items.filter((i) => i.id !== id);
}
/** Attempts a page fetch may make before giving up, so a burst of actions cannot spin it. */
export const PAGE_MAX_ATTEMPTS = 4;
/** For a GET that REPLACES the strip: a response snapshotted before a pin or archive would revert
* it. Retries rather than fails; null after `maxAttempts` keeps the optimistic state. */
export async function fetchWhileStable<T>(
token: () => number,
fetch: () => Promise<T>,
maxAttempts: number = PAGE_MAX_ATTEMPTS,
): Promise<T | null> {
for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
const before = token();
const result = await fetch();
if (token() === before) return result;
}
return null;
}
/**
* Archiving shortens the server's shelf mid-request, so a page at the old offset skips a record.
* `count()` catches a drop during the fetch, `token()` a mutation starting during it, and
* `pending()` the gap between those two.
*/
export async function fetchNextPage<T>(
count: () => number,
token: () => number,
pending: () => number,
fetchPage: (offset: number) => Promise<T>,
maxAttempts: number = PAGE_MAX_ATTEMPTS,
): Promise<{ page: T; offset: number } | null> {
for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
const offset = count();
const before = token();
const page = await fetchPage(offset);
if (pending() === 0 && count() === offset && token() === before) {
return { page, offset };
}
}
return null;
}
/** Falls to a neighbour so the preview never blanks with items on screen; `remaining` excludes
* the removed item. */
export function nextSelectedId<T extends FlaggableItem>(
remaining: T[],
removedId: string,
selectedId: string | null,
removedIndex: number,
): string | null {
if (selectedId !== removedId) return selectedId;
if (remaining.length === 0) return null;
return remaining[Math.min(Math.max(removedIndex, 0), remaining.length - 1)].id;
}