@gitkraken/core-gitlens 0.4.0 → 0.4.100

package/src/plus/integrations/results.ts

@@ -0,0 +1,275 @@
+import { AuthenticationError, RequestNotFoundError, RequestRateLimitError } from '../../git/errors.js';
+import type { IntegrationIds } from './constants.js';
+
+export interface ConnectionStateChangeEvent {
+	key: string;
+	reason: 'connected' | 'disconnected';
+}
+
+/**
+ * A per-provider, per-connection warning surfaced alongside (partial) read results. Consumers use
+ * these to drive auth recovery, retry, or truncation messaging without the read itself throwing.
+ *
+ * `kind` is the programmatic discriminant (a rate-limit is retryable, a 404 is not, an auth failure
+ * needs re-connection); `isAuth` is retained as a convenience mirror of `kind === 'auth'`.
+ */
+export type ProviderWarningKind = 'auth' | 'rate-limit' | 'not-found' | 'no-connection' | 'other';
+
+export interface ProviderWarning {
+	providerId: IntegrationIds;
+	/** Disambiguates connections on self-managed hosts (where one provider id spans multiple domains). */
+	domain?: string;
+	/** The specific token/connection the read was pinned to, when a `connectionId` was supplied. */
+	connectionId?: string;
+	message: string;
+	kind: ProviderWarningKind;
+	/** Convenience mirror of `kind === 'auth'`. */
+	isAuth: boolean;
+}
+
+export interface ProviderPageInfo {
+	/**
+	 * The 1-based POSITION of the returned page. One convention across every paged read, page-number and
+	 * cursor paging alike, so a `getNextPageParam`-style consumer can key off it uniformly:
+	 * - the page number the provider itself reported, when it reports one (authoritative);
+	 * - else the position the caller addressed: the page encoded in a threaded page cursor, or the `page`
+	 *   supplied alongside an opaque cursor (1 when the caller supplied no `page`);
+	 * - else, for a read that can be advanced by page number, the requested `page` — the provider either
+	 *   honored it or the internal drain reached it (see the paging contract on `IntegrationManager`);
+	 * - else 1: a cursor-only read with no cursor threaded back ignores a requested page number and answers
+	 *   with its first page, so echoing the request would mislabel page 1 as page N.
+	 *
+	 * A page past the provider's terminal cursor still reports the requested `page` with empty `items` — an
+	 * empty page N, never page N-1 relabeled.
+	 *
+	 * Continue a cursor-paged read from `cursor`, NOT from `currentPage + 1`: a cursor-only host can't be
+	 * addressed by number, so this is a position label and not always a resumable request parameter.
+	 */
+	currentPage: number;
+	/**
+	 * The page size IN EFFECT, which is not always the one requested — it is whichever of these the read can
+	 * actually vouch for:
+	 * - the size the provider reported for the page it served (numbered-page hosts), else
+	 * - the `itemsPerPage` that was applied to the request (repo-scoped reads, which forward it), else
+	 * - `items.length`, for a read that takes no page size at all: the account-wide PR/issue reads, `listRepos`
+	 *   (cursor-only), and `listIssueTrackerIssuesPage`, whose `itemsPerPage` counts PROJECTS rather than issues.
+	 *
+	 * So it is a description of the page, not an echo of the request: don't derive a total from
+	 * `currentPage * itemsPerPage`, and don't read `items.length < itemsPerPage` as "last page" — `hasMore` /
+	 * `cursor` are the only continuation signals.
+	 */
+	itemsPerPage: number;
+	/**
+	 * A COMPLETENESS assertion, not a mode flag: `true` only when a sweep drained every page of every target
+	 * without truncating or failing (`!truncated && !fetchFailed`). Set exclusively by `sweepPullRequests` /
+	 * `sweepClosedPullRequests` and absent on every paged read, so `allPages !== true` does NOT by itself mean
+	 * "this was a single page".
+	 *
+	 * This is the signal to gate on before caching a sweep as authoritative: unlike `truncated` it is `false`
+	 * for BOTH kinds of incompleteness, so it can't be misread as a benign cap.
+	 */
+	allPages?: boolean;
+	/**
+	 * True when the read stopped before it could confirm it had everything. Deliberately does NOT distinguish
+	 * WHY, and a consumer must not assume it means a provider ceiling — a sweep sets it from three different
+	 * origins:
+	 * - a provider-side ceiling or per-scope backstop propagated from below (e.g. GitHub Search's 1000-result
+	 *   cap): the missing items are NOT reachable, so this really is "complete to the provider's limit";
+	 * - the sweep's OWN `maxPages` cap (default 100) with a usable cursor still in hand: the missing items ARE
+	 *   reachable and were simply not fetched — raise `maxPages` to get them;
+	 * - the provider reporting another page but handing back no usable cursor: not reachable.
+	 *
+	 * Only the second is recoverable, and a sweep exposes no continuation cursor, so treating a truncated sweep
+	 * as a complete set silently drops reachable data in that case. Prefer `allPages` for the cache decision.
+	 */
+	truncated?: boolean;
+}
+
+export interface ProviderResult<T> {
+	items: T[];
+	warnings: ProviderWarning[];
+	/**
+	 * True when `items` is incomplete — distinguishes a failed or truncated flat read from a genuinely empty
+	 * result. Paged results additionally use `page.truncated` when a completed page could not confirm it
+	 * drained everything.
+	 */
+	fetchFailed?: boolean;
+}
+
+export interface ProviderPagedResult<T> extends ProviderResult<T> {
+	page: ProviderPageInfo;
+	hasMore: boolean;
+	/**
+	 * Opaque cursor for cursor-based paging (GraphQL, per-repo/per-project cursors, etc.). For hosts that
+	 * require the previous page's cursor, consumers should pass this value back to the next `cursor` option.
+	 * A retry-only cursor may remain when `hasMore` is false: `hasMore` means automatic forward progress,
+	 * while explicitly reusing such a cursor retries failed work without creating an infinite paging loop.
+	 */
+	cursor?: string;
+}
+
+export interface ProviderSweepResult<T> extends ProviderResult<T> {
+	page: ProviderPageInfo;
+	hasMore: boolean;
+	/**
+	 * Providers whose top-level read failed before returning any usable page. Partial per-scope failures stay
+	 * represented by `warnings` + `fetchFailed` and are intentionally excluded.
+	 */
+	failedProviderIds: IntegrationIds[];
+	/**
+	 * Providers whose read started successfully but could not produce an authoritative complete slice (for
+	 * example, a later page failed, collection metadata reported a partial scope, or a paging backstop was hit).
+	 * Kept separate from
+	 * `failedProviderIds` so consumers can accept healthy sibling providers while preserving an older snapshot
+	 * for a provider whose returned slice has a gap.
+	 */
+	incompleteProviderIds: IntegrationIds[];
+}
+
+export interface ProviderBroadenResult<T> extends ProviderPagedResult<T> {
+	broadenedProviderIds: IntegrationIds[];
+	/** Providers for which no requested org produced a usable issue result. */
+	failedProviderIds: IntegrationIds[];
+	/** Providers with both a usable org result and at least one failed or truncated org slice. */
+	incompleteProviderIds: IntegrationIds[];
+	fanOutCount: number;
+}
+
+export type RepositoryResolutionStatus =
+	| 'resolved'
+	| 'not-found'
+	| 'unauthorized'
+	| 'unsupported-provider'
+	| 'invalid-remote-url'
+	| 'host-mismatch'
+	| 'undetermined';
+
+export interface RepositoryIdentity {
+	providerId: IntegrationIds;
+	domain: string;
+	/** The provider's canonical owner/namespace (follows renames), falling back to the parsed remote when omitted. */
+	owner: string;
+	/** The provider's canonical repo name (follows renames), falling back to the parsed remote when omitted. */
+	name: string;
+	project?: string;
+	/** The original input remote URL, so the caller can key the resolution back to the remote it asked about. */
+	remoteUrl: string;
+	/**
+	 * True when the provider's canonical owner/name differ from what the input remote URL carried — i.e. the
+	 * repo was renamed/moved host-side and the local remote is stale. Case-insensitive, mirroring gkcli's
+	 * `EqualFold` compare so hosts that echo the input casing (e.g. Bitbucket Server/Azure) aren't flagged.
+	 */
+	renamed: boolean;
+}
+
+export interface RepositoryResolution {
+	status: RepositoryResolutionStatus;
+	identity?: RepositoryIdentity;
+	warning?: ProviderWarning;
+}
+
+export interface ResolveRepositoryResult {
+	resolution: RepositoryResolution;
+}
+
+const maxProviderWarningMessageLength = 500;
+
+function providerWarningMessage(ex: unknown): string {
+	const raw = (ex instanceof Error ? ex.message : String(ex)).trim();
+	const carrier = ex as { status?: unknown; response?: { status?: unknown } } | null | undefined;
+	const status =
+		typeof carrier?.status === 'number'
+			? carrier.status
+			: typeof carrier?.response?.status === 'number'
+				? carrier.response.status
+				: undefined;
+
+	// Gateways commonly answer API requests with a complete HTML error page. That payload is neither actionable
+	// nor suitable for a warning DTO consumed by UIs and logs; preserve the status without leaking the document.
+	if (/<(?:!doctype\s+html|html|head|body)\b/i.test(raw)) {
+		return status != null ? `Provider request failed with status ${status}.` : 'Provider request failed.';
+	}
+
+	if (!raw) {
+		return status != null ? `Provider request failed with status ${status}.` : 'Provider request failed.';
+	}
+	return raw.length > maxProviderWarningMessageLength
+		? `${raw.slice(0, maxProviderWarningMessageLength - 3)}...`
+		: raw;
+}
+
+/**
+ * Normalized org/workspace/group shape returned by the provider facade.
+ * `name` is the provider identifier to pass to follow-up reads, while `org` is an optional display label.
+ */
+export interface ProviderOrganization {
+	id: string;
+	providerId: IntegrationIds;
+	name: string;
+	org?: string;
+	url: string;
+}
+
+/** Normalized repository shape returned by the provider facade. */
+export interface ProviderRepositoryShape {
+	id: string;
+	namespace: string;
+	name: string;
+	/** Azure DevOps project; `undefined` for hosts without a project layer. */
+	project?: string;
+	/** Web (browser) URL, when the provider exposes it. */
+	url?: string;
+	/** HTTPS clone URL, when available. */
+	cloneUrlHttps?: string;
+	/** SSH clone URL, when available. */
+	cloneUrlSsh?: string;
+	/** Default branch name, when the provider reports it. */
+	defaultBranch?: string;
+}
+
+/**
+ * Classifies a caught provider exception into a neutral {@link ProviderWarning}. Ordering matters:
+ * `instanceof` is checked most-specific-first so a rate-limit isn't mislabeled as a generic error and
+ * a 404 isn't mislabeled as auth.
+ */
+export function toProviderWarning(
+	providerId: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	ex: unknown,
+): ProviderWarning {
+	let kind: ProviderWarning['kind'];
+	if (ex instanceof AuthenticationError) {
+		kind = 'auth';
+	} else if (ex instanceof RequestRateLimitError) {
+		kind = 'rate-limit';
+	} else if (ex instanceof RequestNotFoundError) {
+		kind = 'not-found';
+	} else {
+		kind = 'other';
+	}
+
+	return {
+		providerId: providerId,
+		domain: domain,
+		connectionId: connectionId,
+		message: providerWarningMessage(ex),
+		kind: kind,
+		isAuth: kind === 'auth',
+	};
+}
+
+/** A stable key for deduplicating warnings accumulated across drained pages / fan-out scopes. */
+function providerWarningKey(warning: ProviderWarning): string {
+	return [warning.providerId, warning.connectionId ?? '', warning.domain ?? '', warning.kind, warning.message].join(
+		' ',
+	);
+}
+
+/** Appends `warning` to `into` only when an equal warning (by provider/connection/domain/kind/message) is absent. */
+export function appendDedupedWarning(into: ProviderWarning[], warning: ProviderWarning): void {
+	const key = providerWarningKey(warning);
+	if (into.some(existing => providerWarningKey(existing) === key)) return;
+
+	into.push(warning);
+}

package/src/plus/integrations/utils/domain.utils.ts

@@ -0,0 +1,26 @@
+/** Extracts the host from a domain expressed as either a URL or a bare host. */
+export function hostFromDomain(domain: string | undefined): string | undefined {
+	const value = domain?.trim();
+	if (!value) return undefined;
+
+	if (/^[a-z][a-z\d+\-.]*:\/\//i.test(value)) {
+		try {
+			return new URL(value).host || undefined;
+		} catch {
+			return undefined;
+		}
+	}
+
+	try {
+		return new URL(`https://${value}`).host || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Whether two URL-or-host domain values identify the same normalized host and port. */
+export function areDomainsOnSameHost(first: string | undefined, second: string | undefined): boolean {
+	const firstHost = hostFromDomain(first);
+	const secondHost = hostFromDomain(second);
+	return firstHost != null && secondHost != null && firstHost === secondHost;
+}

package/src/plus/integrations/utils/integration.utils.ts

@@ -7,20 +7,11 @@ import {
 } from '../constants.js';
 import type { GitHostIntegration } from '../models/gitHostIntegration.js';
 import type { Integration, IntegrationConnectedKey } from '../models/integration.js';
-import { isGitHubDotCom, isGitLabDotCom } from '../providers/models.js';
-
-// These two domain checks live here (rather than in their provider modules) to
-// break a top-level circular import. The provider modules synchronously read
-// `providersMetadata[...]` at module init time, so importing from them while
-// `providers/models.ts` is still loading triggers a TDZ on `providersMetadata`.
-const azureCloudDomainRegex = /^dev\.azure\.com$|\bvisualstudio\.com$/i;
-const bitbucketCloudDomainRegex = /^bitbucket\.org$/i;
-function isAzureCloudDomain(domain: string | undefined): boolean {
-	return domain != null && azureCloudDomainRegex.test(domain);
-}
-function isBitbucketCloudDomain(domain: string | undefined): boolean {
-	return domain != null && bitbucketCloudDomainRegex.test(domain);
-}
+// These domain checks come from `providers/models.ts` (already imported here) rather than the individual
+// provider modules: those read `providersMetadata[...]` synchronously at module init, so importing from them
+// while `providers/models.ts` is still loading triggers a TDZ on `providersMetadata`. Importing the shared
+// predicates keeps one definition of each regex — duplicating them let a fix land in only one place.
+import { isAzureCloudDomain, isBitbucketCloudDomain, isGitHubDotCom, isGitLabDotCom } from '../providers/models.js';
 
 const selfHostedIntegrationIds: GitSelfManagedHostIntegrationId[] = [
 	GitSelfManagedHostIntegrationId.CloudGitHubEnterprise,
@@ -35,8 +26,7 @@ export const supportedIntegrationIds: IntegrationIds[] = [
 	GitCloudHostIntegrationId.Bitbucket,
 	GitCloudHostIntegrationId.AzureDevOps,
 	IssuesCloudHostIntegrationId.Jira,
-	// Note: Trello is metadata-only (no auth provider), so it is intentionally absent — including it
-	// would make reset()'s ensureProvider() throw 'No authentication provider registered'.
+	IssuesCloudHostIntegrationId.Trello,
 	...selfHostedIntegrationIds,
 ] as const;
 
@@ -117,6 +107,20 @@ export function isCloudGitSelfManagedHostIntegrationId(
 	}
 }
 
+/**
+ * Whether a provider's cloud token uses `expiresIn: 0` to mean "never expires" (rather than "already
+ * expired"). GitHub and the cloud self-managed hosts always return 0 for their non-expiring tokens; Trello
+ * is issued with `expiration: never` (identity-service), so its cloud token comes back as 0 too. Callers
+ * must map 0 → a far-future expiry for these, or the session is immediately treated as expired.
+ */
+export function isNonExpiringZeroTokenIntegrationId(id: IntegrationIds): boolean {
+	return (
+		id === GitCloudHostIntegrationId.GitHub ||
+		id === IssuesCloudHostIntegrationId.Trello ||
+		isCloudGitSelfManagedHostIntegrationId(id)
+	);
+}
+
 export function isGitHostIntegration(integration: Integration): integration is GitHostIntegration {
 	return integration.type === 'git';
 }
@@ -136,3 +140,76 @@ export function isGitCloudHostIntegrationId(id: IntegrationIds): id is GitCloudH
 export function isGitSelfManagedHostIntegrationId(id: IntegrationIds): id is GitSelfManagedHostIntegrationId {
 	return selfHostedIntegrationIds.includes(id as GitSelfManagedHostIntegrationId);
 }
+
+/**
+ * Whether this id belongs to a dedicated issue tracker (resource → project) rather than a git host.
+ *
+ * Decided from the id alone, so a read can refuse a mismatched surface — a repo/PR read asked of Jira, or an
+ * issue-tracker project read asked of GitHub — before resolving a connection. The instance-level
+ * {@link isIssuesIntegration} answers the same question once an integration is in hand.
+ */
+export function isIssuesHostIntegrationId(id: IntegrationIds): id is IssuesCloudHostIntegrationId {
+	switch (id) {
+		case IssuesCloudHostIntegrationId.Jira:
+		case IssuesCloudHostIntegrationId.Linear:
+		case IssuesCloudHostIntegrationId.Trello:
+			return true;
+		default:
+			return false;
+	}
+}
+
+/**
+ * Whether a read targeted only by an explicit self-managed `domain` (no `connectionId`) must treat a
+ * session-less core result as a broken target instead of an empty account. Without this, a self-managed host
+ * addressed only by domain — the manual-token/external-auth case `domain` exists to cover — returns an empty
+ * success with no warning and no `fetchFailed`, indistinguishable from "this host has nothing".
+ */
+export function warnOnMissingSessionForDomain(id: IntegrationIds, domain: string | undefined): boolean {
+	return domain != null && isGitSelfManagedHostIntegrationId(id);
+}
+
+/** Maps an integration id to the git-remote provider type used by the remote-URL matcher. */
+export function remoteProviderTypeForIntegration(id: IntegrationIds): RemoteProviderId | undefined {
+	switch (id) {
+		case GitCloudHostIntegrationId.GitHub:
+		case GitSelfManagedHostIntegrationId.CloudGitHubEnterprise:
+			return 'github';
+		case GitCloudHostIntegrationId.GitLab:
+		case GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted:
+			return 'gitlab';
+		case GitCloudHostIntegrationId.Bitbucket:
+			return 'bitbucket';
+		case GitSelfManagedHostIntegrationId.BitbucketServer:
+			return 'bitbucket-server';
+		case GitCloudHostIntegrationId.AzureDevOps:
+		case GitSelfManagedHostIntegrationId.AzureDevOpsServer:
+			return 'azure-devops';
+		default:
+			return undefined;
+	}
+}
+
+/** Normalizes a host remote-config `type` string (e.g. `'GitHub'`) to a git-remote provider type. */
+export function remoteProviderTypeForConfig(type: string): RemoteProviderId | undefined {
+	switch (type.toLowerCase()) {
+		case 'github':
+			return 'github';
+		case 'gitlab':
+			return 'gitlab';
+		case 'bitbucket':
+			return 'bitbucket';
+		case 'bitbucket-server':
+		case 'bitbucketserver':
+			return 'bitbucket-server';
+		case 'azuredevops':
+		case 'azure-devops':
+			return 'azure-devops';
+		case 'gitea':
+			return 'gitea';
+		case 'gerrit':
+			return 'gerrit';
+		default:
+			return undefined;
+	}
+}

package/src/utils/brand.ts

@@ -1,6 +1,4 @@
-// eslint-disable-next-line @typescript-eslint/naming-convention
 declare const __brand: unique symbol;
-// eslint-disable-next-line @typescript-eslint/naming-convention
 declare const __base: unique symbol;
 
 type _Brand<Base, B> = { [__brand]: B; [__base]: Base };

package/src/utils/cancellation.ts

@@ -59,6 +59,40 @@ export function raceWithSignal<T>(promise: Promise<T>, signal: AbortSignal): Pro
 	});
 }
 
+/**
+ * Races a promise against a timeout. If `ms` elapses before the promise settles, the returned promise
+ * rejects with `CancellationError`. If the promise settles first, the timer is cleared. Parallels
+ * `raceWithSignal`, with a timer standing in for the signal.
+ *
+ * When `abortOnTimeout` is provided, it is aborted on timeout — so a caller can link the underlying operation to
+ * it (e.g. via `AbortSignal.any`) and have it torn down instead of orphaned. Abort is best-effort (a truly-stuck
+ * op may ignore it); the returned promise rejects on timeout regardless of whether the underlying op settles.
+ */
+export function raceWithTimeout<T>(promise: Promise<T>, ms: number, abortOnTimeout?: AbortController): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		const timer = setTimeout(() => {
+			const error = new CancellationError(new Error(`Timed out after ${ms}ms`));
+			abortOnTimeout?.abort(error);
+			reject(error);
+		}, ms);
+		// Don't let the timeout timer keep a (Node) process alive on its own — a still-pending promise shouldn't
+		// hold the event loop open just for its backstop (no-op in the browser, where setTimeout returns a number).
+		if (typeof timer !== 'number') {
+			timer.unref();
+		}
+		promise.then(
+			v => {
+				clearTimeout(timer);
+				resolve(v);
+			},
+			(e: unknown) => {
+				clearTimeout(timer);
+				reject(e instanceof Error ? e : new Error(String(e)));
+			},
+		);
+	});
+}
+
 /**
  * Aggregates multiple caller `AbortSignal`s into a single signal that
  * only fires when **all** callers have cancelled (the inverse of `AbortSignal.any()`).
@@ -71,7 +105,8 @@ export function raceWithSignal<T>(promise: Promise<T>, signal: AbortSignal): Pro
 export class AbortAggregate {
 	private readonly controller = new AbortController();
 	private activeCount = 0;
-	private readonly cleanups = new Map<AbortSignal, () => void>();
+	/** One listener-remover per registration (NOT keyed by signal), so adding the same signal twice is safe. */
+	private readonly cleanups = new Set<() => void>();
 
 	/** The aggregate signal — only fires when all callers have cancelled. */
 	get signal(): AbortSignal {
@@ -83,6 +118,8 @@ export class AbortAggregate {
 	 * - If `cancellation` is provided, the caller is auto-removed when it fires.
 	 * - If `cancellation` is `undefined`, the caller is "permanent" — the aggregate
 	 *   can never fire while it's active. Call the returned cleanup on promise settle.
+	 * - The same signal instance may safely be added more than once — each registration is tracked and cleaned up
+	 *   independently, so no listener leaks.
 	 * @returns A cleanup function to unregister the caller.
 	 */
 	add(cancellation?: AbortSignal): () => void {
@@ -101,17 +138,29 @@ export class AbortAggregate {
 			return () => {};
 		}
 
+		// Track this registration's listener removal individually (a Set of removers, NOT keyed by the signal) so
+		// adding the same signal twice can't overwrite the other's cleanup. `settled` keeps both exit paths (abort
+		// vs. manual cleanup) idempotent and preserves the accounting: only `onAbort` decrements `activeCount`.
+		let settled = false;
+		let remove: () => void;
 		const onAbort = () => {
-			this.cleanups.delete(cancellation);
+			if (settled) return;
+
+			settled = true;
+			this.cleanups.delete(remove);
 			this.activeCount--;
 			this.checkAbort();
 		};
+		remove = () => cancellation.removeEventListener('abort', onAbort);
 		cancellation.addEventListener('abort', onAbort, { once: true });
-		this.cleanups.set(cancellation, () => cancellation.removeEventListener('abort', onAbort));
+		this.cleanups.add(remove);
 
 		return () => {
-			this.cleanups.get(cancellation)?.();
-			this.cleanups.delete(cancellation);
+			if (settled) return;
+
+			settled = true;
+			this.cleanups.delete(remove);
+			remove();
 		};
 	}
 
@@ -123,8 +172,8 @@ export class AbortAggregate {
 
 	/** Remove all abort listeners. Call when the cached promise settles. */
 	dispose(): void {
-		for (const cleanup of this.cleanups.values()) {
-			cleanup();
+		for (const remove of this.cleanups) {
+			remove();
 		}
 		this.cleanups.clear();
 	}

package/src/utils/coalescedRun.ts

@@ -0,0 +1,45 @@
+/** Single-flight async runner with one trailing rerun: `run()` while a run is in flight joins the
+ *  SAME promise and marks it dirty; when the run settles (resolve OR reject), one trailing `refire`
+ *  fires so state that changed mid-run is re-processed. `refire` should re-enter the owner's calling
+ *  method (which applies its own gates) — fire-and-forget. `markDirty()` forces the trailing refire
+ *  (e.g. on a repo swap mid-run) without joining. */
+export class CoalescedRun<T> {
+	private _dirty = false;
+	private _inflight: Promise<T> | undefined;
+
+	constructor(
+		private readonly fn: () => Promise<T>,
+		private readonly refire: () => void,
+	) {}
+
+	get running(): boolean {
+		return this._inflight != null;
+	}
+
+	markDirty(): void {
+		if (this._inflight != null) {
+			this._dirty = true;
+		}
+	}
+
+	run(): Promise<T> {
+		if (this._inflight != null) {
+			this._dirty = true;
+			return this._inflight;
+		}
+
+		// Defer `fn` to a microtask so `_inflight` is assigned BEFORE any of fn's code runs — a
+		// synchronous reentrant `run()` from fn's prologue then joins instead of double-running.
+		const promise = Promise.resolve()
+			.then(this.fn)
+			.finally(() => {
+				this._inflight = undefined;
+				if (this._dirty) {
+					this._dirty = false;
+					this.refire();
+				}
+			});
+		this._inflight = promise;
+		return promise;
+	}
+}

package/src/utils/color.ts

@@ -344,15 +344,15 @@ export class Color {
 	static from(value: string | Color): Color {
 		if (value instanceof Color) return value;
 
-		return parseColor(value) || Color.red;
+		return parseColor(value) ?? Color.red;
 	}
 
 	static fromCssVariable(variable: string, css: { getPropertyValue(property: string): string }): Color {
-		return parseColor(getCssVariable(variable, css)) || Color.red;
+		return parseColor(getCssVariable(variable, css)) ?? Color.red;
 	}
 
 	static fromHex(hex: string): Color {
-		return parseHexColor(hex) || Color.red;
+		return parseHexColor(hex) ?? Color.red;
 	}
 
 	static equals(a: Color | null, b: Color | null): boolean {