@effect-tui/react 0.15.2 → 2.0.0

package/src/hosts/text.ts

@@ -1,8 +1,16 @@
 import { type CellBuffer, type Color, displayWidth, type Palette } from "@effect-tui/core"
 import type { ColorMotionValue } from "../motion/color-motion-value.js"
 import type { CommonProps, HostContext, HostInstance, Rect, Size } from "../reconciler/types.js"
-import { isWhitespace, resolveInheritedBgStyle, splitWords, styleIdFromProps, wrapSpans } from "../utils/index.js"
+import {
+	resolveInheritedBgStyle,
+	splitSpansByNewline,
+	spansDisplayWidth,
+	styleIdFromProps,
+	wrapSpansByLine,
+	wrapText,
+} from "../utils/index.js"
 import { BaseHost, getInheritedBg } from "./base.js"
+import { LeafHost } from "./leaf.js"
 
 /** Color prop that can be a static Color or a spring-animated ColorMotionValue */
 export type ColorProp = Color | ColorMotionValue
@@ -49,6 +57,7 @@ export class TextHost extends BaseHost {
 	// Cache wrapped lines between measure() and render()
 	private cachedLines: string[] | null = null
 	private cachedWidth = 0
+	private cachedStyledWrap = false
 	// Cache content to avoid rescanning children each frame
 	private cachedContent: string | null = null
 	// Cache for styled mode
@@ -56,7 +65,6 @@ export class TextHost extends BaseHost {
 	private cachedSpans: StyledSpan[] | null = null
 	private hasSpans = false
 	private explicitSpans: StyledSpan[] | null = null
-	private prepared = false
 
 	constructor(props: TextProps, ctx: HostContext) {
 		super("text", props, ctx)
@@ -94,15 +102,6 @@ export class TextHost extends BaseHost {
 				if (child.content) {
 					spans.push({
 						text: child.content,
-						// Inherit TextHost's styles
-						fg: this.fg,
-						bg: this.bg,
-						bold: this.bold,
-						dimmed: this.dimmed,
-						italic: this.italic,
-						underline: this.underline,
-						strikethrough: this.strikethrough,
-						inverse: this.inverse,
 					})
 				}
 			} else if (child instanceof SpanHost) {
@@ -110,15 +109,15 @@ export class TextHost extends BaseHost {
 				if (content) {
 					spans.push({
 						text: content,
-						// Span's styles, falling back to TextHost's
-						fg: child.fg ?? this.fg,
-						bg: child.bg ?? this.bg,
-						bold: child.bold || this.bold,
-						dimmed: child.dimmed || this.dimmed,
-						italic: child.italic || this.italic,
-						underline: child.underline || this.underline,
-						strikethrough: child.strikethrough || this.strikethrough,
-						inverse: child.inverse || this.inverse,
+						// Span's styles (TextHost applies fallbacks at render time)
+						fg: child.fg,
+						bg: child.bg,
+						bold: child.bold,
+						dimmed: child.dimmed,
+						italic: child.italic,
+						underline: child.underline,
+						strikethrough: child.strikethrough,
+						inverse: child.inverse,
 					})
 				}
 			}
@@ -128,54 +127,51 @@ export class TextHost extends BaseHost {
 	}
 
 	private prepareContent(): void {
-		this.invalidateContent()
 		const useExplicitSpans = this.explicitSpans !== null
 		if (useExplicitSpans) {
 			this.hasSpans = false
 			this.cachedSpans = null
-			this.prepared = true
 			return
 		}
 
 		this.hasSpans = this.checkForSpans()
 		this.cachedSpans = this.hasSpans ? this.collectSpans() : null
-		this.prepared = true
 	}
 
-	private ensurePrepared(): void {
-		if (this.prepared) return
-		this.prepareContent()
-	}
-
-	/** Invalidate content cache when children change */
-	private invalidateContent(): void {
+	/** Reset content-related caches (text/spans/wrap). */
+	private resetContentCaches(): void {
 		this.cachedContent = null
 		this.cachedLines = null
 		this.cachedStyledLines = null
+		this.cachedStyledWrap = false
 		this.cachedSpans = null
-		this.prepared = false
 	}
 
-	protected override prepareSelf(): void {
+	protected override prepareSelf(_layoutDirty: boolean, _renderDirty: boolean): void {
 		this.prepareContent()
 	}
 
+	override invalidateLayout(): void {
+		this.resetContentCaches()
+		super.invalidateLayout()
+	}
+
 	override appendChild(child: HostInstance): void {
+		this.resetContentCaches()
 		super.appendChild(child)
-		this.invalidateContent()
 	}
 
 	override removeChild(child: HostInstance): void {
+		this.resetContentCaches()
 		super.removeChild(child)
-		this.invalidateContent()
 	}
 
 	override insertBefore(child: HostInstance, before: HostInstance): void {
+		this.resetContentCaches()
 		super.insertBefore(child, before)
-		this.invalidateContent()
 	}
 
-	measure(maxW: number, maxH: number): Size {
+	protected measureSelf(maxW: number, maxH: number): Size {
 		const constrained = this.constrainProposal(maxW, maxH)
 		this.ensurePrepared()
 		const useExplicitSpans = this.explicitSpans !== null
@@ -184,18 +180,21 @@ export class TextHost extends BaseHost {
 		if (useExplicitSpans || this.hasSpans) {
 			const spans = useExplicitSpans ? this.explicitSpans! : (this.cachedSpans ?? this.collectSpans())
 			if (this.wrap) {
-				this.cachedStyledLines = wrapSpans(spans, constrained.w)
+				this.cachedStyledLines = wrapSpansByLine(spans, constrained.w)
 				this.cachedWidth = constrained.w
+				this.cachedStyledWrap = true
 				const h = Math.min(this.cachedStyledLines.length, constrained.h)
-				const w = this.cachedStyledLines.reduce(
-					(max, line) => Math.max(max, line.reduce((sum, span) => sum + displayWidth(span.text), 0)),
-					0,
-				)
+				const w = this.cachedStyledLines.reduce((max, line) => Math.max(max, spansDisplayWidth(line)), 0)
 				return this.constrainResult({ w, h })
 			}
-			// Non-wrap styled mode
-			const totalWidth = spans.reduce((sum, span) => sum + displayWidth(span.text), 0)
-			return this.constrainResult({ w: Math.min(totalWidth, constrained.w), h: 1 })
+			// Non-wrap styled mode (preserve explicit newlines)
+			const lines = splitSpansByNewline(spans)
+			this.cachedStyledLines = lines
+			this.cachedWidth = constrained.w
+			this.cachedStyledWrap = false
+			const maxLineWidth = lines.reduce((max, line) => Math.max(max, spansDisplayWidth(line)), 0)
+			const h = Math.min(lines.length, constrained.h)
+			return this.constrainResult({ w: Math.min(maxLineWidth, constrained.w), h })
 		}
 
 		// Simple mode: single style for all content
@@ -205,7 +204,7 @@ export class TextHost extends BaseHost {
 		if (this.wrap) {
 			// Wrap mode: may span multiple lines. Cache result for render()
 			this.cachedLines = rawLines.flatMap((line, idx) =>
-				idx < rawLines.length - 1 ? [...this.wrapText(line, constrained.w), ""] : this.wrapText(line, constrained.w),
+				idx < rawLines.length - 1 ? [...wrapText(line, constrained.w), ""] : wrapText(line, constrained.w),
 			)
 			this.cachedWidth = constrained.w
 			const w = this.cachedLines.reduce((max, line) => Math.max(max, displayWidth(line)), 0)
@@ -220,61 +219,7 @@ export class TextHost extends BaseHost {
 		return this.constrainResult({ w, h })
 	}
 
-	/** Wrap text to fit within maxWidth, preferring word boundaries */
-	private wrapText(text: string, maxWidth: number): string[] {
-		const result: string[] = []
-		for (const rawLine of text.split("\n")) {
-			if (rawLine === "") {
-				result.push("")
-				continue
-			}
-
-			// Split into words (keeping whitespace as separate tokens)
-			const tokens = splitWords(rawLine)
-			let line = ""
-			let lineW = 0
-
-			for (const token of tokens) {
-				const tokenW = displayWidth(token)
-				const isWs = isWhitespace(token)
-
-				if (lineW + tokenW <= maxWidth) {
-					// Token fits on current line
-					line += token
-					lineW += tokenW
-				} else if (isWs) {
-					// Whitespace doesn't fit - just skip it (don't start new line with space)
-					continue
-				} else if (tokenW <= maxWidth) {
-					// Word doesn't fit but is smaller than maxWidth - start new line
-					if (line.trimEnd()) result.push(line.trimEnd())
-					line = token
-					lineW = tokenW
-				} else {
-					// Word is longer than maxWidth - break it character by character
-					if (line.trimEnd()) result.push(line.trimEnd())
-					line = ""
-					lineW = 0
-					for (const ch of token) {
-						const chW = displayWidth(ch)
-						if (lineW + chW > maxWidth && line.length > 0) {
-							result.push(line)
-							line = ch
-							lineW = chW
-						} else {
-							line += ch
-							lineW += chW
-						}
-					}
-				}
-			}
-			// Preserve trailing space for inline flow - only trimEnd when breaking mid-line (done above)
-			if (line) result.push(line)
-		}
-		return result.length > 0 ? result : [""]
-	}
-
-	override layout(rect: Rect): void {
+	protected override layoutSelf(rect: Rect): void {
 		const layoutRect = this.layoutWithConstraints(rect)
 		// Layout children (RawTextHost nodes) at same position
 		for (const child of this.children) {
@@ -283,10 +228,7 @@ export class TextHost extends BaseHost {
 	}
 
 	render(buffer: CellBuffer, palette: Palette): void {
-		if (!this.rect) {
-			this.prepared = false
-			return
-		}
+		if (!this.rect) return
 		this.ensurePrepared()
 
 		// If text has no bg, inherit from parent box for proper highlight rendering
@@ -297,11 +239,11 @@ export class TextHost extends BaseHost {
 		// Styled mode: render with per-span styles
 		if (useExplicitSpans || this.hasSpans) {
 			const lines =
-				this.wrap && this.cachedStyledLines && this.cachedWidth === this.rect.w
+				this.cachedStyledLines && this.cachedWidth === this.rect.w && this.cachedStyledWrap === this.wrap
 					? this.cachedStyledLines
 					: (() => {
 							const spans = useExplicitSpans ? this.explicitSpans! : (this.cachedSpans ?? this.collectSpans())
-							return this.wrap ? wrapSpans(spans, this.rect.w) : [spans]
+							return this.wrap ? wrapSpansByLine(spans, this.rect.w) : splitSpansByNewline(spans)
 						})()
 
 			for (let y = 0; y < Math.min(lines.length, this.rect.h); y++) {
@@ -310,12 +252,12 @@ export class TextHost extends BaseHost {
 					const spanStyleId = styleIdFromProps(palette, {
 						fg: span.fg ?? this.fg,
 						bg: span.bg ?? inheritedBg,
-						bold: span.bold,
-						dimmed: span.dimmed,
-						italic: span.italic,
-						underline: span.underline,
-						strikethrough: span.strikethrough,
-						inverse: span.inverse,
+						bold: span.bold ?? this.bold,
+						dimmed: span.dimmed ?? this.dimmed,
+						italic: span.italic ?? this.italic,
+						underline: span.underline ?? this.underline,
+						strikethrough: span.strikethrough ?? this.strikethrough,
+						inverse: span.inverse ?? this.inverse,
 					})
 					const availableWidth = this.rect.w - (x - this.rect.x)
 					if (availableWidth <= 0) break
@@ -324,7 +266,6 @@ export class TextHost extends BaseHost {
 					x += displayWidth(span.text)
 				}
 			}
-			this.prepared = false
 			return
 		}
 
@@ -349,7 +290,7 @@ export class TextHost extends BaseHost {
 				this.cachedLines && this.cachedWidth === rectW
 					? this.cachedLines
 					: rawLines.flatMap((line, idx) =>
-							idx < rawLines.length - 1 ? [...this.wrapText(line, rectW), ""] : this.wrapText(line, rectW),
+							idx < rawLines.length - 1 ? [...wrapText(line, rectW), ""] : wrapText(line, rectW),
 						)
 			const visibleLines = Math.min(lines.length, this.rect.h)
 			// Explicitly paint background under text lines to clear stale styles (e.g., selection highlights).
@@ -361,7 +302,6 @@ export class TextHost extends BaseHost {
 				const lineWidth = Math.min(displayWidth(lines[i]), this.rect.w)
 				buffer.drawText(this.rect.x, this.rect.y + i, lines[i], styleId, lineWidth)
 			}
-			this.prepared = false
 			return
 		}
 
@@ -375,11 +315,21 @@ export class TextHost extends BaseHost {
 			const lineWidth = Math.min(displayWidth(rawLines[i]), this.rect.w)
 			buffer.drawText(this.rect.x, this.rect.y + i, rawLines[i], styleId, lineWidth)
 		}
-		this.prepared = false
 	}
 
 	override updateProps(props: Record<string, unknown>): void {
 		super.updateProps(props)
+		const prevFg = this.fg
+		const prevBg = this.bg
+		const prevBold = this.bold
+		const prevDimmed = this.dimmed
+		const prevItalic = this.italic
+		const prevUnderline = this.underline
+		const prevStrikethrough = this.strikethrough
+		const prevInverse = this.inverse
+		const prevWrap = this.wrap
+		const prevExplicitSpans = this.explicitSpans
+
 		// Color props support MotionValue/ColorMotionValue - auto-subscribe and animate
 		this.fg = this.resolveSpringProp("fg", props.fg, (v) => {
 			this.fg = v as Color
@@ -395,11 +345,31 @@ export class TextHost extends BaseHost {
 		this.inverse = Boolean(props.inverse)
 		this.wrap = Boolean(props.wrap)
 		this.explicitSpans = "spans" in props ? ((props.spans as StyledSpan[] | undefined) ?? []) : null
+
+		const layoutChanged = prevWrap !== this.wrap || prevExplicitSpans !== this.explicitSpans
+		if (layoutChanged) {
+			this.invalidateLayout()
+			return
+		}
+
+		const renderChanged =
+			prevFg !== this.fg ||
+			prevBg !== this.bg ||
+			prevBold !== this.bold ||
+			prevDimmed !== this.dimmed ||
+			prevItalic !== this.italic ||
+			prevUnderline !== this.underline ||
+			prevStrikethrough !== this.strikethrough ||
+			prevInverse !== this.inverse
+
+		if (renderChanged) {
+			this.invalidateRender()
+		}
 	}
 }
 
 /** Special host for raw text nodes (React text children) */
-export class RawTextHost extends BaseHost {
+export class RawTextHost extends LeafHost {
 	content = ""
 
 	constructor(text: string, ctx: HostContext) {
@@ -407,7 +377,7 @@ export class RawTextHost extends BaseHost {
 		this.content = text
 	}
 
-	measure(maxW: number, _maxH: number): Size {
+	protected measureSelf(maxW: number, _maxH: number): Size {
 		const w = Math.min(displayWidth(this.content), maxW)
 		return { w, h: 1 }
 	}
@@ -424,6 +394,7 @@ export class RawTextHost extends BaseHost {
 
 	updateText(text: string): void {
 		this.content = text
+		this.parent?.invalidateLayout?.()
 	}
 
 	override updateProps(_props: Record<string, unknown>): void {
@@ -469,12 +440,12 @@ export interface SpanProps extends CommonProps {
 export class SpanHost extends BaseHost {
 	fg?: Color
 	bg?: Color
-	bold = false
-	dimmed = false
-	italic = false
-	underline = false
-	strikethrough = false
-	inverse = false
+	bold?: boolean
+	dimmed?: boolean
+	italic?: boolean
+	underline?: boolean
+	strikethrough?: boolean
+	inverse?: boolean
 
 	constructor(props: SpanProps, ctx: HostContext) {
 		super("span", props, ctx)
@@ -489,7 +460,22 @@ export class SpanHost extends BaseHost {
 			.join("")
 	}
 
-	measure(_maxW: number, _maxH: number): Size {
+	override appendChild(child: HostInstance): void {
+		super.appendChild(child)
+		this.parent?.invalidateLayout?.()
+	}
+
+	override removeChild(child: HostInstance): void {
+		super.removeChild(child)
+		this.parent?.invalidateLayout?.()
+	}
+
+	override insertBefore(child: HostInstance, before: HostInstance): void {
+		super.insertBefore(child, before)
+		this.parent?.invalidateLayout?.()
+	}
+
+	protected measureSelf(_maxW: number, _maxH: number): Size {
 		// Span doesn't measure independently - parent TextHost handles layout
 		return { w: 0, h: 0 }
 	}
@@ -505,12 +491,20 @@ export class SpanHost extends BaseHost {
 		// Individual props override textStyle object
 		this.fg = props.fg !== undefined ? (props.fg as Color) : textStyle?.fg
 		this.bg = props.bg !== undefined ? (props.bg as Color) : textStyle?.bg
-		this.bold = props.bold !== undefined ? Boolean(props.bold) : Boolean(textStyle?.bold)
-		this.dimmed = props.dimmed !== undefined ? Boolean(props.dimmed) : Boolean(textStyle?.dimmed)
-		this.italic = props.italic !== undefined ? Boolean(props.italic) : Boolean(textStyle?.italic)
-		this.underline = props.underline !== undefined ? Boolean(props.underline) : Boolean(textStyle?.underline)
-		this.strikethrough =
-			props.strikethrough !== undefined ? Boolean(props.strikethrough) : Boolean(textStyle?.strikethrough)
-		this.inverse = props.inverse !== undefined ? Boolean(props.inverse) : Boolean(textStyle?.inverse)
+		this.bold = props.bold !== undefined ? Boolean(props.bold) : textStyle?.bold
+		this.dimmed = props.dimmed !== undefined ? Boolean(props.dimmed) : textStyle?.dimmed
+		this.italic = props.italic !== undefined ? Boolean(props.italic) : textStyle?.italic
+		this.underline = props.underline !== undefined ? Boolean(props.underline) : textStyle?.underline
+		this.strikethrough = props.strikethrough !== undefined ? Boolean(props.strikethrough) : textStyle?.strikethrough
+		this.inverse = props.inverse !== undefined ? Boolean(props.inverse) : textStyle?.inverse
+		this.invalidateLayout()
+	}
+
+	override invalidateLayout(): void {
+		this.parent?.invalidateLayout?.()
+	}
+
+	override invalidateRender(): void {
+		this.parent?.invalidateRender?.()
 	}
 }

package/src/hosts/vstack.ts

@@ -8,6 +8,6 @@ export interface VStackProps extends FlexContainerProps<"vertical"> {}
  */
 export class VStackHost extends FlexContainerHost<"vertical"> {
 	constructor(props: VStackProps, ctx: HostContext) {
-		super("vertical", "vstack", props as FlexContainerProps<"vertical">, ctx, "leading")
+		super("vertical", "vstack", props as FlexContainerProps<"vertical">, ctx, "left")
 	}
 }

package/src/hosts/zstack.ts

@@ -1,10 +1,11 @@
 import type { CellBuffer, Palette } from "@effect-tui/core"
 import type { CommonProps, HostContext, Rect, Size } from "../reconciler/types.js"
-import { alignedChildRect, type HAlign, type VAlign } from "../utils/index.js"
+import { type HAlign, type VAlign } from "../utils/index.js"
 import { BaseHost } from "./base.js"
+import { layoutAlignedChildren } from "./layout-helpers.js"
 
 export interface ZStackProps extends CommonProps {
-	alignment?: { h?: "leading" | "center" | "trailing"; v?: "top" | "center" | "bottom" }
+	alignment?: { h?: "left" | "center" | "right"; v?: "top" | "center" | "bottom" }
 }
 
 // Overlay children in the same rect, honoring alignment for each child.
@@ -18,7 +19,7 @@ export class ZStackHost extends BaseHost {
 		this.updateProps(props as unknown as Record<string, unknown>)
 	}
 
-	measure(maxW: number, maxH: number): Size {
+	protected measureSelf(maxW: number, maxH: number): Size {
 		// Apply frame constraints to what we propose to children
 		const constrained = this.constrainProposal(maxW, maxH)
 
@@ -42,14 +43,13 @@ export class ZStackHost extends BaseHost {
 		return this.constrainResult(naturalSize)
 	}
 
-	override layout(rect: Rect): void {
+	protected override layoutSelf(rect: Rect): void {
 		const layoutRect = this.layoutWithConstraints(rect)
 
-		for (let i = 0; i < this.children.length; i++) {
-			const child = this.children[i]
-			const size = this.cachedSizes[i] ?? child.measure(layoutRect.w, layoutRect.h)
-			child.layout(alignedChildRect(layoutRect, size, this.alignmentH, this.alignmentV))
-		}
+		layoutAlignedChildren(layoutRect, this.children, this.cachedSizes, () => ({
+			h: this.alignmentH,
+			v: this.alignmentV,
+		}))
 	}
 
 	render(buffer: CellBuffer, palette: Palette): void {
@@ -60,10 +60,15 @@ export class ZStackHost extends BaseHost {
 
 	override updateProps(props: Record<string, unknown>): void {
 		super.updateProps(props)
+		const prevH = this.alignmentH
+		const prevV = this.alignmentV
 		if (props.alignment !== undefined) {
 			const a = props.alignment as ZStackProps["alignment"]
 			if (a?.h) this.alignmentH = a.h
 			if (a?.v) this.alignmentV = a.v
 		}
+		if (prevH !== this.alignmentH || prevV !== this.alignmentV) {
+			this.invalidateLayout()
+		}
 	}
 }

package/src/index.ts

@@ -65,9 +65,9 @@ export { useKeyboard, useMouse, usePaste, useQuit, useScroll, useShortcut, useTi
 export { isKey } from "./shortcuts.js"
 export { useFrameStats } from "./hooks/useFrameStats.js"
 export type { BorderKind, BoxProps } from "./hosts/box.js"
-export type { CanvasProps, DrawContext } from "./hosts/canvas.js"
+export type { CanvasCell, CanvasProps, DrawContext } from "./hosts/canvas.js"
 export type { HStackProps } from "./hosts/hstack.js"
-export type { ScrollProps } from "./hosts/scroll.js"
+export type { ScrollAlign, ScrollAlignX, ScrollAlignY, ScrollAxis, ScrollLayoutChange, ScrollProps } from "./hosts/scroll.js"
 export type { SpacerProps } from "./hosts/spacer.js"
 export type { SpanProps, SpanStyle, TextProps } from "./hosts/text.js"
 export type { VStackProps } from "./hosts/vstack.js"

package/src/internal/dev/hmr.ts

@@ -0,0 +1,101 @@
+import { readFileSync } from "node:fs"
+import { globalValue } from "effect/GlobalValue"
+
+/**
+ * Pipeable combinator that makes an atom persist across hot reloads.
+ *
+ * This is the cleanest way to define HMR-persistent atoms - just pipe it!
+ * Combines globalValue (for persistence) + keepAlive (prevents registry cleanup).
+ */
+export function hmr(key: string): <A,>(self: A) => A {
+	return <A,>(self: A): A => {
+		return globalValue(Symbol.for(`hmr/${key}`), () => {
+			// Apply keepAlive if it's an atom (just sets keepAlive: true)
+			if (typeof self === "object" && self !== null && "keepAlive" in self) {
+				return Object.assign(Object.create(Object.getPrototypeOf(self)), {
+					...self,
+					keepAlive: true,
+				})
+			}
+			return self
+		}) as A
+	}
+}
+
+/**
+ * Wrap any value creation in HMR persistence.
+ */
+export function hmrState<T>(key: string, create: () => T): T {
+	return globalValue(Symbol.for(`hmr/${key}`), create)
+}
+
+// Cache for runtime key extraction
+const keyCache = new Map<string, string>()
+
+/**
+ * Parse stack trace to get file path and line number.
+ * Returns null if parsing fails.
+ */
+function parseStack(stack: string): { file: string; line: number; col: number } | null {
+	// Bun stack format: "    at functionName (file:line:col)" or "    at file:line:col"
+	const lines = stack.split("\n")
+	// Skip first line (Error message) and find caller (skip autoHmr itself)
+	for (let i = 2; i < lines.length; i++) {
+		const match = lines[i].match(/\((.+?):(\d+):(\d+)\)/) || lines[i].match(/at\s+(.+?):(\d+):(\d+)/)
+		if (match) {
+			return { file: match[1], line: parseInt(match[2], 10), col: parseInt(match[3], 10) }
+		}
+	}
+	return null
+}
+
+/**
+ * Extract variable name from source line using regex.
+ * Returns null if extraction fails.
+ */
+function extractVarName(source: string, line: number): string | null {
+	const lines = source.split("\n")
+	if (line < 1 || line > lines.length) return null
+
+	const sourceLine = lines[line - 1]
+	const match = sourceLine.match(/(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=/)
+	return match?.[1] ?? null
+}
+
+/**
+ * Auto-keyed HMR persistence for atoms.
+ *
+ * When used with the HMR plugin (recommended), keys are injected at load time
+ * based on the variable name. Without the plugin, falls back to runtime
+ * stack trace parsing.
+ */
+export function autoHmr<A>(self: A): A {
+	// Get stack trace for caller location
+	const stack = new Error().stack ?? ""
+	const location = parseStack(stack)
+
+	if (!location) {
+		// Fallback: use a hash of the stack trace
+		const fallbackKey = `unknown:${stack.slice(0, 100)}`
+		return hmr(fallbackKey)(self)
+	}
+
+	const cacheKey = `${location.file}:${location.line}:${location.col}`
+
+	// Check cache first
+	let key = keyCache.get(cacheKey)
+	if (!key) {
+		try {
+			// Read source file and extract variable name
+			const source = readFileSync(location.file, "utf-8")
+			const varName = extractVarName(source, location.line)
+			key = `${location.file}:${varName ?? `line${location.line}`}`
+		} catch {
+			// File read failed, use line-based key
+			key = `${location.file}:line${location.line}`
+		}
+		keyCache.set(cacheKey, key)
+	}
+
+	return hmr(key)(self)
+}