chat-layout 1.2.0-1 → 1.2.0-3

package/index.mjs

@@ -2386,63 +2386,65 @@ function measureRichFragmentShift(ctx, font) {
 }
 function materializeRichFragments(ctx, spans, defaultColor, atoms) {
 	const fragments = [];
-	let pendingGapBefore = 0;
-	for (const atom of atoms) {
-		const occupiedWidth = atom.width + atom.extraWidthAfter;
-		if (atom.kind === "space" && !atom.preservesLineEnd && atom.atomicGroupId == null) {
-			pendingGapBefore += occupiedWidth;
-			continue;
-		}
-		const span = spans[atom.itemIndex];
-		const font = span?.font ?? atom.font;
-		const color = span?.color ?? defaultColor;
-		const previous = fragments[fragments.length - 1];
-		if (previous != null && previous.itemIndex === atom.itemIndex && previous.font === font && pendingGapBefore === 0) {
-			previous.text += atom.text;
-			previous.occupiedWidth += occupiedWidth;
-			continue;
-		}
-		fragments.push({
-			itemIndex: atom.itemIndex,
-			text: atom.text,
-			font,
-			color,
-			gapBefore: pendingGapBefore,
-			occupiedWidth,
-			shift: measureRichFragmentShift(ctx, font)
-		});
-		pendingGapBefore = 0;
-	}
+	let pendingGap = {
+		gapBefore: 0,
+		gapAtomCount: 0,
+		gapSpaceCount: 0
+	};
+	for (const atom of atoms) pendingGap = appendRichFragment(ctx, spans, defaultColor, fragments, atom, pendingGap);
 	return fragments;
 }
-function appendRichFragment(ctx, spans, defaultColor, fragments, atom, pendingGapBefore) {
+function appendRichFragment(ctx, spans, defaultColor, fragments, atom, pendingGap) {
 	const occupiedWidth = atom.width + atom.extraWidthAfter;
-	if (atom.kind === "space" && !atom.preservesLineEnd && atom.atomicGroupId == null) return pendingGapBefore + occupiedWidth;
+	if (atom.kind === "space" && !atom.preservesLineEnd && atom.atomicGroupId == null) return {
+		gapBefore: pendingGap.gapBefore + occupiedWidth,
+		gapAtomCount: pendingGap.gapAtomCount + 1,
+		gapSpaceCount: pendingGap.gapSpaceCount + 1
+	};
 	const span = spans[atom.itemIndex];
 	const font = span?.font ?? atom.font;
 	const color = span?.color ?? defaultColor;
 	const previous = fragments[fragments.length - 1];
-	if (previous != null && previous.itemIndex === atom.itemIndex && previous.font === font && pendingGapBefore === 0) {
+	const spaceCount = atom.kind === "space" ? 1 : 0;
+	if (previous != null && previous.itemIndex === atom.itemIndex && previous.font === font && pendingGap.gapBefore === 0) {
 		previous.text += atom.text;
 		previous.occupiedWidth += occupiedWidth;
-		return 0;
+		previous.atomCount += 1;
+		previous.spaceCount += spaceCount;
+		return {
+			gapBefore: 0,
+			gapAtomCount: 0,
+			gapSpaceCount: 0
+		};
 	}
 	fragments.push({
 		itemIndex: atom.itemIndex,
 		text: atom.text,
 		font,
 		color,
-		gapBefore: pendingGapBefore,
+		gapBefore: pendingGap.gapBefore,
+		gapAtomCount: pendingGap.gapAtomCount,
+		gapSpaceCount: pendingGap.gapSpaceCount,
 		occupiedWidth,
+		atomCount: 1,
+		spaceCount,
 		shift: measureRichFragmentShift(ctx, font)
 	});
-	return 0;
+	return {
+		gapBefore: 0,
+		gapAtomCount: 0,
+		gapSpaceCount: 0
+	};
 }
 function materializeRichFragmentsInRange(ctx, spans, defaultColor, prepared, start, end) {
 	const fragments = [];
-	let pendingGapBefore = 0;
+	let pendingGap = {
+		gapBefore: 0,
+		gapAtomCount: 0,
+		gapSpaceCount: 0
+	};
 	forEachAtomInRange(prepared, start, end, (atom) => {
-		pendingGapBefore = appendRichFragment(ctx, spans, defaultColor, fragments, atom, pendingGapBefore);
+		pendingGap = appendRichFragment(ctx, spans, defaultColor, fragments, atom, pendingGap);
 	});
 	return fragments;
 }
@@ -2488,7 +2490,11 @@ function createRichEllipsisFragment(ctx, font, color) {
 		font,
 		color,
 		gapBefore: 0,
+		gapAtomCount: 0,
+		gapSpaceCount: 0,
 		occupiedWidth: measureEllipsisWidth(ctx),
+		atomCount: 1,
+		spaceCount: 0,
 		shift: measureFontShift(ctx)
 	}));
 }
@@ -2574,13 +2580,17 @@ function layoutRichEndEllipsisFromCursor(ctx, spans, defaultFont, defaultColor,
 	const { prefixCount, width } = selection;
 	const fragments = [];
 	let atomIndex = 0;
-	let pendingGapBefore = 0;
+	let pendingGap = {
+		gapBefore: 0,
+		gapAtomCount: 0,
+		gapSpaceCount: 0
+	};
 	let lastVisibleAtom;
 	let lastAtom;
 	forEachAtomFromCursorToEnd(prepared, start, (atom) => {
 		lastAtom = atom;
 		if (atomIndex < prefixCount) {
-			pendingGapBefore = appendRichFragment(ctx, spans, defaultColor, fragments, atom, pendingGapBefore);
+			pendingGap = appendRichFragment(ctx, spans, defaultColor, fragments, atom, pendingGap);
 			lastVisibleAtom = atom;
 		}
 		atomIndex += 1;
@@ -2749,6 +2759,154 @@ function layoutRichTextWithOverflow(ctx, spans, maxWidth, defaultFont, defaultCo
 	};
 }
 //#endregion
+//#region src/text/justify.ts
+let _justifySupported;
+function isJustifySupported(ctx) {
+	if (_justifySupported !== void 0) return _justifySupported;
+	_justifySupported = typeof ctx.wordSpacing === "string" && typeof ctx.letterSpacing === "string";
+	return _justifySupported;
+}
+function resolveJustifyMode(justify) {
+	if (justify === true) return "inter-word";
+	if (justify === "inter-word" || justify === "inter-character") return justify;
+	return null;
+}
+const HYBRID_WORD_SHARE_CANDIDATES = [
+	.15,
+	.2,
+	.25,
+	.3,
+	.35,
+	.4,
+	.45,
+	.5,
+	.55,
+	.6,
+	.65,
+	.7,
+	.75,
+	.8,
+	.85,
+	1,
+	0
+];
+const PUNCTUATION_OR_SYMBOL_PATTERN = /^[\p{P}\p{S}]$/u;
+const JUSTIFY_SCORE_EPSILON = 1e-9;
+function analyzeLineForJustify(prepared, line) {
+	let wordGapCount = 0;
+	let wordCount = 0;
+	let renderAtomCount = 0;
+	let spaceCount = 0;
+	let nonSpaceCount = 0;
+	let cjkCount = 0;
+	let latinLikeCount = 0;
+	let punctuationCount = 0;
+	let nonSpaceWidth = 0;
+	let insideWord = false;
+	forEachAtomInRange(prepared, line.start, line.end, (atom) => {
+		if (atom.kind === "space" && !atom.preservesLineEnd && atom.atomicGroupId == null) wordGapCount++;
+		renderAtomCount++;
+		if (atom.kind === "space") {
+			spaceCount++;
+			insideWord = false;
+			return;
+		}
+		nonSpaceCount++;
+		nonSpaceWidth += atom.width + atom.extraWidthAfter;
+		if (!insideWord) {
+			wordCount++;
+			insideWord = true;
+		}
+		if (isCJK(atom.text)) {
+			cjkCount++;
+			return;
+		}
+		if (PUNCTUATION_OR_SYMBOL_PATTERN.test(atom.text)) {
+			punctuationCount++;
+			return;
+		}
+		latinLikeCount++;
+	});
+	return {
+		wordGapCount,
+		wordCount,
+		renderAtomCount,
+		letterGapCount: Math.max(renderAtomCount - 1, 0),
+		spaceCount,
+		nonSpaceCount,
+		cjkCount,
+		latinLikeCount,
+		punctuationCount,
+		lineWidth: line.width,
+		nonSpaceWidth
+	};
+}
+function getAverageWordWidth(info) {
+	return info.wordCount > 0 ? info.nonSpaceWidth / info.wordCount : info.lineWidth;
+}
+function getAverageCharWidth(info) {
+	return info.renderAtomCount > 0 ? info.lineWidth / info.renderAtomCount : info.lineWidth;
+}
+function resolvePerGapSpacing(totalSpace, gapCount) {
+	if (totalSpace === 0) return 0;
+	if (gapCount <= 0) return null;
+	return totalSpace / gapCount;
+}
+function exceedsThreshold(perGap, averageWidth, threshold) {
+	if (!Number.isFinite(threshold)) return false;
+	return perGap > threshold * averageWidth;
+}
+function createJustifySpacing(wordSpacingPx, letterSpacingPx) {
+	return {
+		wordSpacing: `${wordSpacingPx}px`,
+		letterSpacing: `${letterSpacingPx}px`,
+		wordSpacingPx,
+		letterSpacingPx
+	};
+}
+function computeJustifySpacing(lineWidth, maxWidth, info, mode, threshold = Number.POSITIVE_INFINITY) {
+	const extraSpace = maxWidth - lineWidth;
+	if (extraSpace <= 0 || mode == null) return null;
+	if (mode === "inter-word" && info.wordGapCount > 0) {
+		const perGap = extraSpace / info.wordGapCount;
+		if (exceedsThreshold(perGap, Math.max(getAverageWordWidth(info), Number.EPSILON), threshold)) return null;
+		return createJustifySpacing(perGap, 0);
+	}
+	if (mode !== "inter-character" || info.renderAtomCount === 0) return null;
+	const avgCharWidth = Math.max(getAverageCharWidth(info), Number.EPSILON);
+	if (info.wordGapCount === 0) {
+		const perGap = resolvePerGapSpacing(extraSpace, info.letterGapCount);
+		if (perGap == null) return null;
+		if (exceedsThreshold(perGap, avgCharWidth, threshold)) return null;
+		return createJustifySpacing(0, perGap);
+	}
+	const avgWordWidth = Math.max(getAverageWordWidth(info), Number.EPSILON);
+	const nonSpaceCount = Math.max(info.nonSpaceCount, 1);
+	const cjkRatio = info.cjkCount / nonSpaceCount;
+	const latinLikeRatio = info.latinLikeCount / nonSpaceCount;
+	const punctuationRatio = info.punctuationCount / nonSpaceCount;
+	const wordPenalty = 1 + cjkRatio;
+	const letterPenalty = 1 + latinLikeRatio + .5 * punctuationRatio;
+	let bestCandidate = null;
+	for (const wordShare of HYBRID_WORD_SHARE_CANDIDATES) {
+		const wordExtraSpace = extraSpace * wordShare;
+		const letterExtraSpace = extraSpace - wordExtraSpace;
+		const wordSpacingPx = resolvePerGapSpacing(wordExtraSpace, info.wordGapCount);
+		const letterSpacingPx = resolvePerGapSpacing(letterExtraSpace, info.letterGapCount);
+		if (wordSpacingPx == null || letterSpacingPx == null) continue;
+		if (exceedsThreshold(wordSpacingPx, avgWordWidth, threshold) || exceedsThreshold(letterSpacingPx, avgCharWidth, threshold)) continue;
+		const wordRatio = wordSpacingPx / avgWordWidth;
+		const letterRatio = letterSpacingPx / avgCharWidth;
+		const score = wordPenalty * wordRatio ** 2 + letterPenalty * letterRatio ** 2;
+		if (bestCandidate == null || score < bestCandidate.score - JUSTIFY_SCORE_EPSILON || Math.abs(score - bestCandidate.score) <= JUSTIFY_SCORE_EPSILON && wordShare > bestCandidate.wordShare) bestCandidate = {
+			spacing: createJustifySpacing(wordSpacingPx, letterSpacingPx),
+			score,
+			wordShare
+		};
+	}
+	return bestCandidate?.spacing ?? null;
+}
+//#endregion
 //#region src/nodes/text.ts
 function resolvePhysicalTextAlign(options) {
 	if (options.physicalAlign != null) return options.physicalAlign;
@@ -2763,6 +2921,26 @@ function normalizeTextMaxWidth(maxWidth) {
 	if (maxWidth == null) return;
 	return Math.max(0, maxWidth);
 }
+const DEFAULT_TEXT_SPACING = {
+	wordSpacing: "0px",
+	letterSpacing: "0px"
+};
+function supportsTextSpacing(g) {
+	return typeof g.wordSpacing === "string" && typeof g.letterSpacing === "string";
+}
+function withTextSpacing(g, spacing, cb) {
+	if (!supportsTextSpacing(g)) return cb();
+	const savedWordSpacing = g.wordSpacing;
+	const savedLetterSpacing = g.letterSpacing;
+	try {
+		g.wordSpacing = spacing.wordSpacing;
+		g.letterSpacing = spacing.letterSpacing;
+		return cb();
+	} finally {
+		g.wordSpacing = savedWordSpacing;
+		g.letterSpacing = savedLetterSpacing;
+	}
+}
 function getTextLayoutContext(ctx) {
 	return ctx;
 }
@@ -2866,7 +3044,9 @@ function drawRichLine(ctx, line, fallbackColor, x, y, lineHeight) {
 			g.font = fragment.font;
 			g.fillStyle = ctx.resolveDynValue(fragment.color ?? fallbackColor);
 			g.textAlign = "left";
-			g.fillText(fragment.text, cursorX, y + (lineHeight + fragment.shift) / 2);
+			withTextSpacing(g, DEFAULT_TEXT_SPACING, () => {
+				g.fillText(fragment.text, cursorX, y + (lineHeight + fragment.shift) / 2);
+			});
 		});
 		cursorX += fragment.occupiedWidth;
 	}
@@ -2945,23 +3125,83 @@ var MultilineText = class {
 			const spans = this.text;
 			const { width, lines } = getRichMultiLineDrawLayout(this, ctx, spans, this.options);
 			const align = resolvePhysicalTextAlign(this.options);
-			const startX = align === "right" ? x + width : align === "center" ? x + width / 2 : x;
-			for (const line of lines) {
-				let cursorX = startX;
-				for (let fi = 0; fi < line.fragments.length; fi++) {
-					const frag = line.fragments[fi];
-					cursorX += frag.gapBefore;
-					ctx.with((g) => {
-						g.font = frag.font;
-						g.fillStyle = ctx.resolveDynValue(frag.color ?? this.options.color);
-						if (align === "right") g.textAlign = "right";
-						else if (align === "center") g.textAlign = "center";
-						else g.textAlign = "left";
-						g.fillText(frag.text, cursorX, y + (this.options.lineHeight + frag.shift) / 2);
-					});
-					cursorX += frag.occupiedWidth;
+			const maxWidth = normalizeTextMaxWidth(ctx.constraints?.maxWidth);
+			const mode = resolveJustifyMode(this.options.justify);
+			const canJustify = mode != null && maxWidth != null && maxWidth > 0 && isJustifySupported(ctx.graphics);
+			const threshold = this.options.justifyGapThreshold ?? 2;
+			if (canJustify) {
+				const prepared = readPreparedInlineLayout(getRichPreparedKey(spans, this.options.font, this.options.whiteSpace ?? "normal", this.options.wordBreak ?? "normal"), createRichSourceItems(spans, this.options.font), this.options.whiteSpace ?? "normal", this.options.wordBreak ?? "normal");
+				let lineIndex = 0;
+				const totalLines = lines.length;
+				walkPreparedLineRanges(prepared, maxWidth, (lineRange) => {
+					if (lineIndex >= totalLines) return false;
+					const line = lines[lineIndex];
+					const isLastLine = lineIndex === totalLines - 1;
+					if (!(isLastLine && shouldUseMultilineOverflowLayout(this.options) && this.options.overflow === "ellipsis") && (!isLastLine || this.options.justifyLastLine === true)) {
+						const info = analyzeLineForJustify(prepared, lineRange);
+						const spacing = computeJustifySpacing(lineRange.width, maxWidth, info, mode, threshold);
+						if (spacing != null) {
+							let cursorX = x;
+							for (let fi = 0; fi < line.fragments.length; fi++) {
+								const frag = line.fragments[fi];
+								const leadingLetterGapCount = fi > 0 ? frag.gapAtomCount + 1 : 0;
+								const internalLetterGapCount = Math.max(frag.atomCount - 1, 0);
+								cursorX += frag.gapBefore + leadingLetterGapCount * spacing.letterSpacingPx + frag.gapSpaceCount * spacing.wordSpacingPx;
+								ctx.with((g) => {
+									g.font = frag.font;
+									g.fillStyle = ctx.resolveDynValue(frag.color ?? this.options.color);
+									g.textAlign = "left";
+									withTextSpacing(g, spacing, () => {
+										g.fillText(frag.text, cursorX, y + (this.options.lineHeight + frag.shift) / 2);
+									});
+								});
+								cursorX += frag.occupiedWidth + internalLetterGapCount * spacing.letterSpacingPx + frag.spaceCount * spacing.wordSpacingPx;
+							}
+							y += this.options.lineHeight;
+							lineIndex++;
+							return;
+						}
+					}
+					let cursorX = align === "right" ? x + width : align === "center" ? x + width / 2 : x;
+					for (let fi = 0; fi < line.fragments.length; fi++) {
+						const frag = line.fragments[fi];
+						cursorX += frag.gapBefore;
+						ctx.with((g) => {
+							g.font = frag.font;
+							g.fillStyle = ctx.resolveDynValue(frag.color ?? this.options.color);
+							if (align === "right") g.textAlign = "right";
+							else if (align === "center") g.textAlign = "center";
+							else g.textAlign = "left";
+							withTextSpacing(g, DEFAULT_TEXT_SPACING, () => {
+								g.fillText(frag.text, cursorX, y + (this.options.lineHeight + frag.shift) / 2);
+							});
+						});
+						cursorX += frag.occupiedWidth;
+					}
+					y += this.options.lineHeight;
+					lineIndex++;
+				});
+			} else {
+				const startX = align === "right" ? x + width : align === "center" ? x + width / 2 : x;
+				for (const line of lines) {
+					let cursorX = startX;
+					for (let fi = 0; fi < line.fragments.length; fi++) {
+						const frag = line.fragments[fi];
+						cursorX += frag.gapBefore;
+						ctx.with((g) => {
+							g.font = frag.font;
+							g.fillStyle = ctx.resolveDynValue(frag.color ?? this.options.color);
+							if (align === "right") g.textAlign = "right";
+							else if (align === "center") g.textAlign = "center";
+							else g.textAlign = "left";
+							withTextSpacing(g, DEFAULT_TEXT_SPACING, () => {
+								g.fillText(frag.text, cursorX, y + (this.options.lineHeight + frag.shift) / 2);
+							});
+						});
+						cursorX += frag.occupiedWidth;
+					}
+					y += this.options.lineHeight;
 				}
-				y += this.options.lineHeight;
 			}
 			return false;
 		}
@@ -2969,30 +3209,76 @@ var MultilineText = class {
 			g.font = this.options.font;
 			g.fillStyle = ctx.resolveDynValue(this.options.color);
 			const { width, lines } = getMultiLineDrawLayout(this, ctx, this.text, this.options);
-			switch (resolvePhysicalTextAlign(this.options)) {
-				case "left":
-					for (const { text, shift } of lines) {
-						g.fillText(text, x, y + (this.options.lineHeight + shift) / 2);
-						y += this.options.lineHeight;
+			const maxWidth = normalizeTextMaxWidth(ctx.constraints?.maxWidth);
+			const mode = resolveJustifyMode(this.options.justify);
+			const canJustify = mode != null && maxWidth != null && maxWidth > 0 && isJustifySupported(g);
+			const threshold = this.options.justifyGapThreshold ?? 2;
+			if (canJustify) {
+				const prepared = readPreparedText(this.text, this.options.font, this.options.whiteSpace ?? "normal", this.options.wordBreak ?? "normal");
+				let lineIndex = 0;
+				const totalLines = lines.length;
+				walkPreparedLineRanges(prepared, maxWidth, (lineRange) => {
+					if (lineIndex >= totalLines) return false;
+					const layout = lines[lineIndex];
+					const isLastLine = lineIndex === totalLines - 1;
+					if (!(isLastLine && shouldUseMultilineOverflowLayout(this.options) && this.options.overflow === "ellipsis") && (!isLastLine || this.options.justifyLastLine === true)) {
+						const info = analyzeLineForJustify(prepared, lineRange);
+						const spacing = computeJustifySpacing(lineRange.width, maxWidth, info, mode, threshold);
+						if (spacing != null) {
+							withTextSpacing(g, spacing, () => {
+								g.textAlign = "left";
+								g.fillText(layout.text, x, y + (this.options.lineHeight + layout.shift) / 2);
+							});
+							y += this.options.lineHeight;
+							lineIndex++;
+							return;
+						}
 					}
-					break;
-				case "right":
-					x += width;
-					g.textAlign = "right";
-					for (const { text, shift } of lines) {
-						g.fillText(text, x, y + (this.options.lineHeight + shift) / 2);
-						y += this.options.lineHeight;
-					}
-					break;
-				case "center":
-					x += width / 2;
-					g.textAlign = "center";
-					for (const { text, shift } of lines) {
-						g.fillText(text, x, y + (this.options.lineHeight + shift) / 2);
-						y += this.options.lineHeight;
-					}
-					break;
-			}
+					withTextSpacing(g, DEFAULT_TEXT_SPACING, () => {
+						switch (resolvePhysicalTextAlign(this.options)) {
+							case "left":
+								g.textAlign = "left";
+								g.fillText(layout.text, x, y + (this.options.lineHeight + layout.shift) / 2);
+								break;
+							case "right":
+								g.textAlign = "right";
+								g.fillText(layout.text, x + width, y + (this.options.lineHeight + layout.shift) / 2);
+								break;
+							case "center":
+								g.textAlign = "center";
+								g.fillText(layout.text, x + width / 2, y + (this.options.lineHeight + layout.shift) / 2);
+								break;
+						}
+					});
+					y += this.options.lineHeight;
+					lineIndex++;
+				});
+			} else withTextSpacing(g, DEFAULT_TEXT_SPACING, () => {
+				switch (resolvePhysicalTextAlign(this.options)) {
+					case "left":
+						for (const { text, shift } of lines) {
+							g.fillText(text, x, y + (this.options.lineHeight + shift) / 2);
+							y += this.options.lineHeight;
+						}
+						break;
+					case "right":
+						x += width;
+						g.textAlign = "right";
+						for (const { text, shift } of lines) {
+							g.fillText(text, x, y + (this.options.lineHeight + shift) / 2);
+							y += this.options.lineHeight;
+						}
+						break;
+					case "center":
+						x += width / 2;
+						g.textAlign = "center";
+						for (const { text, shift } of lines) {
+							g.fillText(text, x, y + (this.options.lineHeight + shift) / 2);
+							y += this.options.lineHeight;
+						}
+						break;
+				}
+			});
 			return false;
 		});
 	}
@@ -3055,7 +3341,9 @@ var Text = class {
 			g.font = this.options.font;
 			g.fillStyle = ctx.resolveDynValue(this.options.color);
 			const layout = getSingleLineLayout(this, ctx, text, this.options);
-			g.fillText(layout.text, x, y + (this.options.lineHeight + layout.shift) / 2);
+			withTextSpacing(g, DEFAULT_TEXT_SPACING, () => {
+				g.fillText(layout.text, x, y + (this.options.lineHeight + layout.shift) / 2);
+			});
 			return false;
 		});
 	}
@@ -3337,6 +3625,24 @@ function subscribeListState(list, owner, listener) {
 		token
 	});
 }
+function isObjectIdentityCandidate(value) {
+	return typeof value === "object" && value !== null || typeof value === "function";
+}
+function assertUniqueItemReferences(items, existingItems) {
+	const seen = /* @__PURE__ */ new Set();
+	if (existingItems != null) {
+		for (const item of existingItems) if (isObjectIdentityCandidate(item)) seen.add(item);
+	}
+	for (const item of items) {
+		if (!isObjectIdentityCandidate(item)) continue;
+		if (seen.has(item)) throw new Error("ListState items must use unique object references.");
+		seen.add(item);
+	}
+}
+function normalizeUpdateAnimation(animation) {
+	if (animation == null) return;
+	return Number.isFinite(animation.duration) ? { duration: animation.duration } : {};
+}
 var ListState = class {
 	#items;
 	/** Pixel offset from the anchored item edge. */
@@ -3349,14 +3655,18 @@ var ListState = class {
 	}
 	/** Replaces the full item collection while preserving scroll state. */
 	set items(value) {
-		this.#items = [...value];
+		const nextItems = [...value];
+		assertUniqueItemReferences(nextItems);
+		this.#items = nextItems;
 		emitListStateChange(this, { type: "set" });
 	}
 	/**
 	* @param items Initial list items.
 	*/
 	constructor(items = []) {
-		this.#items = [...items];
+		const nextItems = [...items];
+		assertUniqueItemReferences(nextItems);
+		this.#items = nextItems;
 	}
 	/** Prepends one or more items. */
 	unshift(...items) {
@@ -3365,6 +3675,7 @@ var ListState = class {
 	/** Prepends an array of items. */
 	unshiftAll(items) {
 		if (items.length === 0) return;
+		assertUniqueItemReferences(items, this.#items);
 		if (this.position != null) this.position += items.length;
 		this.#items = items.concat(this.#items);
 		emitListStateChange(this, {
@@ -3379,6 +3690,7 @@ var ListState = class {
 	/** Appends an array of items. */
 	pushAll(items) {
 		if (items.length === 0) return;
+		assertUniqueItemReferences(items, this.#items);
 		this.#items.push(...items);
 		emitListStateChange(this, {
 			type: "push",
@@ -3386,19 +3698,21 @@ var ListState = class {
 		});
 	}
 	/**
-	* Replaces an existing item by index.
+	* Updates an existing item by object identity.
 	*/
-	replace(index, item, animation) {
-		const normalizedIndex = Number.isFinite(index) ? Math.trunc(index) : NaN;
-		if (!Number.isInteger(normalizedIndex) || normalizedIndex < 0 || normalizedIndex >= this.#items.length) throw new RangeError(`replace() index ${index} is out of range for list length ${this.#items.length}.`);
-		const prevItem = this.#items[normalizedIndex];
-		this.#items[normalizedIndex] = item;
+	update(targetItem, nextItem, animation) {
+		if (!isObjectIdentityCandidate(targetItem) || !isObjectIdentityCandidate(nextItem)) throw new TypeError("update() only supports object items.");
+		if (targetItem === nextItem) throw new Error("update() requires nextItem to be a new object reference.");
+		const index = this.#items.indexOf(targetItem);
+		if (index < 0) throw new Error("update() targetItem is not present in the list.");
+		if (this.#items.includes(nextItem)) throw new Error("update() nextItem is already present in the list.");
+		const prevItem = this.#items[index];
+		this.#items[index] = nextItem;
 		emitListStateChange(this, {
-			type: "replace",
-			index: normalizedIndex,
+			type: "update",
 			prevItem,
-			nextItem: item,
-			animation: animation != null && Number.isFinite(animation.duration) ? { duration: animation.duration } : animation == null ? void 0 : {}
+			nextItem,
+			animation: normalizeUpdateAnimation(animation)
 		});
 	}
 	/**
@@ -3412,7 +3726,9 @@ var ListState = class {
 	* Replaces all items and clears scroll state.
 	*/
 	reset(items = []) {
-		this.#items = [...items];
+		const nextItems = [...items];
+		assertUniqueItemReferences(nextItems);
+		this.#items = nextItems;
 		this.offset = 0;
 		this.position = void 0;
 		emitListStateChange(this, { type: "reset" });
@@ -3520,7 +3836,8 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 	static JUMP_DURATION_PER_ITEM = 28;
 	#controlledState;
 	#jumpAnimation;
-	#replacementAnimations = /* @__PURE__ */ new Map();
+	#replacementAnimations = /* @__PURE__ */ new WeakMap();
+	#activeReplacementItems = /* @__PURE__ */ new Set();
 	#nextReplacementLayerKey = 0;
 	constructor(graphics, options) {
 		super(graphics, options);
@@ -3683,14 +4000,14 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 	}
 	_getItemHeight(index) {
 		const now = getNow();
-		const replacement = this.#readReplacementAnimation(index, now);
-		if (replacement != null) return this.#sampleReplacementHeight(replacement, now);
 		const item = this.items[index];
+		const replacement = this.#readReplacementAnimation(item, now);
+		if (replacement != null) return this.#sampleReplacementHeight(replacement, now);
 		const node = this.options.renderItem(item);
 		return this.measureRootNode(node).height;
 	}
-	_resolveItem(item, index, now) {
-		const replacement = this.#readReplacementAnimation(index, now);
+	_resolveItem(item, _index, now) {
+		const replacement = this.#readReplacementAnimation(item, now);
 		if (replacement == null) {
 			const node = this.options.renderItem(item);
 			return {
@@ -3762,24 +4079,26 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 	#isLayerComplete(layer, now) {
 		return getProgress(layer.startTime, layer.duration, now) >= 1 && Math.abs(layer.toAlpha - this.#sampleLayerAlpha(layer, now)) <= ALPHA_EPSILON;
 	}
-	#readReplacementAnimation(index, now) {
-		const animation = this.#replacementAnimations.get(index);
+	#readReplacementAnimation(item, now) {
+		const animation = this.#replacementAnimations.get(item);
 		if (animation == null) return;
 		const currentLayer = animation.layers.find((layer) => layer.key === animation.currentLayerKey);
 		if (currentLayer == null) {
-			this.#replacementAnimations.delete(index);
+			this.#replacementAnimations.delete(item);
+			this.#activeReplacementItems.delete(item);
 			return;
 		}
 		animation.layers = animation.layers.filter((layer) => layer.key === animation.currentLayerKey || !this.#isLayerComplete(layer, now));
 		if (getProgress(animation.startTime, animation.duration, now) >= 1 && this.#isLayerComplete(currentLayer, now) && animation.layers.length === 1) {
-			this.#replacementAnimations.delete(index);
+			this.#replacementAnimations.delete(item);
+			this.#activeReplacementItems.delete(item);
 			return;
 		}
 		return animation;
 	}
 	#prepareReplacementAnimations(now) {
 		let keepAnimating = false;
-		for (const index of [...this.#replacementAnimations.keys()]) if (this.#readReplacementAnimation(index, now) != null) keepAnimating = true;
+		for (const item of [...this.#activeReplacementItems]) if (this.#readReplacementAnimation(item, now) != null) keepAnimating = true;
 		return keepAnimating;
 	}
 	#drawReplacementLayers(layers, slotHeight, y) {
@@ -3805,38 +4124,34 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 	}
 	#handleListStateChange(change) {
 		switch (change.type) {
-			case "replace":
-				this.#handleReplace(change.index, change.prevItem, change.nextItem, change.animation?.duration);
+			case "update":
+				this.#handleUpdate(change.prevItem, change.nextItem, change.animation?.duration);
 				break;
-			case "unshift": {
-				if (change.count <= 0 || this.#replacementAnimations.size === 0) return;
-				const shifted = /* @__PURE__ */ new Map();
-				for (const [index, animation] of this.#replacementAnimations) shifted.set(index + change.count, animation);
-				this.#replacementAnimations = shifted;
-				break;
-			}
+			case "unshift":
 			case "push": break;
 			case "reset":
 			case "set":
-				this.#replacementAnimations.clear();
+				this.#replacementAnimations = /* @__PURE__ */ new WeakMap();
+				this.#activeReplacementItems.clear();
 				break;
 		}
 	}
-	#handleReplace(index, prevItem, nextItem, duration) {
-		const normalizedDuration = Number.isFinite(duration) ? Math.max(0, duration) : 0;
+	#handleUpdate(prevItem, nextItem, duration) {
+		const normalizedDuration = Math.max(0, typeof duration === "number" && Number.isFinite(duration) ? duration : 0);
 		if (normalizedDuration <= 0) {
-			this.#replacementAnimations.delete(index);
+			this.#replacementAnimations.delete(prevItem);
+			this.#activeReplacementItems.delete(prevItem);
 			return;
 		}
 		const now = getNow();
 		const nextNode = this.options.renderItem(nextItem);
 		const nextHeight = this.measureRootNode(nextNode).height;
-		const animation = this.#readReplacementAnimation(index, now);
+		const animation = this.#readReplacementAnimation(prevItem, now);
 		if (animation == null) {
 			const prevNode = this.options.renderItem(prevItem);
 			const outgoing = this.#createReplacementLayer(prevNode, 1, 0, now, normalizedDuration);
 			const incoming = this.#createReplacementLayer(nextNode, 0, 1, now, normalizedDuration);
-			this.#replacementAnimations.set(index, {
+			this.#replacementAnimations.set(nextItem, {
 				currentLayerKey: incoming.key,
 				layers: [outgoing, incoming],
 				fromHeight: this.measureRootNode(prevNode).height,
@@ -3844,6 +4159,8 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 				startTime: now,
 				duration: normalizedDuration
 			});
+			this.#activeReplacementItems.delete(prevItem);
+			this.#activeReplacementItems.add(nextItem);
 			return;
 		}
 		const currentLayer = animation.layers.find((layer) => layer.key === animation.currentLayerKey);
@@ -3853,7 +4170,8 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 		if (currentAlpha > ALPHA_EPSILON) layers.push(this.#createReplacementLayer(currentNode, currentAlpha, 0, now, normalizedDuration));
 		const incoming = this.#createReplacementLayer(nextNode, 0, 1, now, normalizedDuration);
 		layers.push(incoming);
-		this.#replacementAnimations.set(index, {
+		this.#replacementAnimations.delete(prevItem);
+		this.#replacementAnimations.set(nextItem, {
 			currentLayerKey: incoming.key,
 			layers,
 			fromHeight: this.#sampleReplacementHeight(animation, now),
@@ -3861,6 +4179,8 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 			startTime: now,
 			duration: normalizedDuration
 		});
+		this.#activeReplacementItems.delete(prevItem);
+		this.#activeReplacementItems.add(nextItem);
 	}
 };
 //#endregion