@effect-tui/react 0.1.3 → 0.1.5

package/src/reconciler/host-config.ts

@@ -2,6 +2,7 @@ import Reconciler from "react-reconciler"
 import { createContext } from "react"
 import type { HostInstance, HostContext } from "./types.js"
 import { createHostInstance, createTextInstance, type RawTextHost, type BaseHost } from "../hosts/index.js"
+import { noopMethods } from "./noop-methods.js"
 
 // ============================================================================
 // Type Definitions
@@ -11,6 +12,10 @@ import { createHostInstance, createTextInstance, type RawTextHost, type BaseHost
 export interface Container {
 	root: HostInstance | null
 	ctx: HostContext
+	/** @internal Static content root node (for Static component) */
+	staticRoot?: HostInstance | null
+	/** @internal Flag indicating static content needs flushing */
+	staticDirty?: boolean
 }
 
 /** Props passed to host instances */
@@ -47,209 +52,183 @@ let currentUpdatePriority = NoEventPriority
 // each method while avoiding type compatibility issues with the reconciler.
 
 const hostConfig = {
-  supportsMutation: true,
-  supportsPersistence: false,
-  supportsHydration: false,
-
-  createInstance(type: Type, props: Props, rootContainer: Container) {
-    return createHostInstance(type, props, rootContainer.ctx)
-  },
-
-  appendChild(parent: Instance, child: Instance) {
-    parent.appendChild(child)
-  },
-
-  removeChild(parent: Instance, child: Instance) {
-    parent.removeChild(child)
-    child.destroy()
-  },
-
-  insertBefore(parent: Instance, child: Instance, beforeChild: Instance) {
-    parent.insertBefore(child, beforeChild)
-  },
-
-  insertInContainerBefore(container: Container, child: Instance, beforeChild: Instance) {
-    if (container.root) {
-      container.root.insertBefore(child, beforeChild)
-    }
-  },
-
-  removeChildFromContainer(container: Container, child: Instance) {
-    if (container.root) {
-      container.root.removeChild(child)
-      child.destroy()
-    }
-  },
-
-  prepareForCommit() {
-    return null
-  },
-
-  resetAfterCommit(container: Container) {
-    container.ctx.requestRender()
-  },
-
-  getRootHostContext(): ReconcilerHostContext {
-    return { isInsideText: false }
-  },
-
-  getChildHostContext(parentHostContext: ReconcilerHostContext, type: Type): ReconcilerHostContext {
-    const isInsideText = type === "text" || parentHostContext.isInsideText
-    return { ...parentHostContext, isInsideText }
-  },
-
-  shouldSetTextContent() {
-    return false
-  },
-
-  createTextInstance(text: string, rootContainer: Container, hostContext: ReconcilerHostContext): TextInstance {
-    // Raw text nodes are only valid inside <text> elements
-    if (!hostContext.isInsideText) {
-      console.warn("Text nodes should be inside <text> elements")
-    }
-    return createTextInstance(text, rootContainer.ctx)
-  },
-
-  scheduleTimeout: setTimeout,
-  cancelTimeout: clearTimeout,
-  noTimeout: -1,
-
-  shouldAttemptEagerTransition() {
-    return false
-  },
-
-  finalizeInitialChildren(instance: Instance, _type: Type, props: Props) {
-    instance.updateProps(props)
-    return false
-  },
-
-  commitMount() {
-    // Could handle focus here
-  },
-
-  commitUpdate(
-		instance: Instance,
-		_updatePayload: unknown,
-		_type: Type,
-		_oldProps: Props,
-		newProps: Props | { pendingProps?: Props; memoizedProps?: Props },
-	) {
-		// Handle case where newProps might be a Fiber node (react-reconciler API varies)
-		const props =
-			(newProps as { pendingProps?: Props }).pendingProps ??
-			(newProps as { memoizedProps?: Props }).memoizedProps ??
-			(newProps as Props)
-		instance.updateProps(props)
-	},
+	supportsMutation: true,
+	supportsPersistence: false,
+	supportsHydration: false,
 
-  commitTextUpdate(textInstance: TextInstance, _oldText: string, newText: string) {
-    textInstance.updateText(newText)
-  },
+	createInstance(type: Type, props: Props, rootContainer: Container) {
+		const instance = createHostInstance(type, props, rootContainer.ctx)
 
-  appendChildToContainer(container: Container, child: Instance) {
-    // The first child becomes the root
-    container.root = child
-    child.parent = null
-  },
+		// Track static content (from <Static> component)
+		if (props.__static) {
+			instance.__static = true
+			rootContainer.staticRoot = instance
+			rootContainer.staticDirty = true
+		}
 
-  appendInitialChild(parent: Instance, child: Instance) {
-    parent.appendChild(child)
-  },
+		return instance
+	},
 
-  hideInstance() {
-    // Could implement visibility
-  },
+	appendChild(parent: Instance, child: Instance) {
+		parent.appendChild(child)
+	},
 
-  unhideInstance() {
-    // Could implement visibility
-  },
+	removeChild(parent: Instance, child: Instance) {
+		parent.removeChild(child)
+		child.destroy()
+	},
 
-  hideTextInstance() {},
+	insertBefore(parent: Instance, child: Instance, beforeChild: Instance) {
+		parent.insertBefore(child, beforeChild)
+	},
 
-  unhideTextInstance() {},
+	insertInContainerBefore(container: Container, child: Instance, _beforeChild: Instance) {
+		// Static content is stored separately in staticRoot, not inserted into the tree
+		if (child.__static) {
+			return
+		}
+		// For non-static children at container level, they become the root
+		// (Our container model only supports one root - multiple root children aren't supported)
+		container.root = child
+		child.parent = null
+	},
 
-  clearContainer(container: Container) {
-    container.root = null
-  },
+	removeChildFromContainer(container: Container, child: Instance) {
+		if (container.root) {
+			container.root.removeChild(child)
+			child.destroy()
+		}
+		// Clear static root if we're removing it
+		if (container.staticRoot === child) {
+			container.staticRoot = null
+		}
+	},
 
-  setCurrentUpdatePriority(newPriority: number) {
-    currentUpdatePriority = newPriority
-  },
+	prepareForCommit() {
+		return null
+	},
 
-  getCurrentUpdatePriority: () => currentUpdatePriority,
+	resetAfterCommit(container: Container) {
+		// If static content is dirty, flush immediately (bypassing throttle)
+		if (container.staticDirty && container.ctx.requestImmediateRender) {
+			container.ctx.requestImmediateRender()
+		} else {
+			container.ctx.requestRender()
+		}
+	},
 
-  resolveUpdatePriority() {
-    if (currentUpdatePriority !== NoEventPriority) {
-      return currentUpdatePriority
-    }
-    return DefaultEventPriority
-  },
+	getRootHostContext(): ReconcilerHostContext {
+		return { isInsideText: false }
+	},
 
-  maySuspendCommit() {
-    return false
-  },
+	getChildHostContext(parentHostContext: ReconcilerHostContext, type: Type): ReconcilerHostContext {
+		const isInsideText = type === "text" || parentHostContext.isInsideText
+		return { ...parentHostContext, isInsideText }
+	},
 
-  NotPendingTransition: null,
+	shouldSetTextContent() {
+		return false
+	},
 
-  HostTransitionContext: createContext(null),
+	createTextInstance(text: string, rootContainer: Container, hostContext: ReconcilerHostContext): TextInstance {
+		// Raw text nodes are only valid inside <text> elements
+		if (!hostContext.isInsideText) {
+			console.warn("Text nodes should be inside <text> elements")
+		}
+		return createTextInstance(text, rootContainer.ctx)
+	},
 
-  resetFormInstance() {},
+	scheduleTimeout: setTimeout,
+	cancelTimeout: clearTimeout,
+	noTimeout: -1,
 
-  requestPostPaintCallback() {},
+	shouldAttemptEagerTransition() {
+		return false
+	},
 
-  trackSchedulerEvent() {},
+	finalizeInitialChildren(instance: Instance, _type: Type, props: Props) {
+		instance.updateProps(props)
+		return false
+	},
 
-  resolveEventType() {
-    return null
-  },
+	commitMount() {
+		// Could handle focus here
+	},
 
-  resolveEventTimeStamp() {
-    return -1.1
-  },
+	commitUpdate(
+		instance: Instance,
+		_updatePayload: unknown,
+		_type: Type,
+		_oldProps: Props,
+		newProps: Props | { pendingProps?: Props; memoizedProps?: Props },
+		container: Container,
+	) {
+		// Handle case where newProps might be a Fiber node (react-reconciler API varies)
+		const props =
+			(newProps as { pendingProps?: Props }).pendingProps ??
+			(newProps as { memoizedProps?: Props }).memoizedProps ??
+			(newProps as Props)
+		instance.updateProps(props)
 
-  preloadInstance() {
-    return true
-  },
+		// Mark static content as needing flush
+		if (instance.__static) {
+			container.staticDirty = true
+		}
+	},
 
-  startSuspendingCommit() {},
+	commitTextUpdate(textInstance: TextInstance, _oldText: string, newText: string) {
+		textInstance.updateText(newText)
+	},
 
-  suspendInstance() {},
+	appendChildToContainer(container: Container, child: Instance) {
+		// Static content is stored separately - don't let it become the main root
+		if (!child.__static) {
+			container.root = child
+		}
+		child.parent = null
+	},
 
-  waitForCommitToBeReady() {
-    return null
-  },
+	appendInitialChild(parent: Instance, child: Instance) {
+		parent.appendChild(child)
+	},
 
-  detachDeletedInstance(instance: Instance) {
-    if (!instance.parent) {
-      instance.destroy()
-    }
-  },
+	// Spread noop methods required by react-reconciler but unused in this renderer
+	...noopMethods,
 
-  getPublicInstance(instance: Instance) {
-    return instance
-  },
+	clearContainer(container: Container) {
+		container.root = null
+		container.staticRoot = null
+		container.staticDirty = false
+	},
 
-  preparePortalMount() {},
+	setCurrentUpdatePriority(newPriority: number) {
+		currentUpdatePriority = newPriority
+	},
 
-  isPrimaryRenderer: true,
+	getCurrentUpdatePriority: () => currentUpdatePriority,
 
-  getInstanceFromNode() {
-    return null
-  },
+	resolveUpdatePriority() {
+		if (currentUpdatePriority !== NoEventPriority) {
+			return currentUpdatePriority
+		}
+		return DefaultEventPriority
+	},
 
-  beforeActiveInstanceBlur() {},
+	NotPendingTransition: null,
 
-  afterActiveInstanceBlur() {},
+	HostTransitionContext: createContext(null),
 
-  prepareScopeUpdate() {},
+	detachDeletedInstance(instance: Instance) {
+		if (!instance.parent) {
+			instance.destroy()
+		}
+	},
 
-  getInstanceFromScope() {
-    return null
-  },
+	getPublicInstance(instance: Instance) {
+		return instance
+	},
 
-  prepareUpdate() {
-    return true
-  },
+	isPrimaryRenderer: true,
 }
 
 // Cast to any at the boundary - the config is internally typed but
@@ -264,14 +243,13 @@ export const reconciler = Reconciler(hostConfig as any)
 
 type ReconcilerWithOptionalMethods = typeof reconciler & {
 	flushPassiveEffects?: () => void
-	flushSync?: <T>(fn?: () => T) => T
+	flushSyncFromReconciler?: <T>(fn?: () => T) => T
 	batchedUpdates?: <T>(fn: () => T) => T
-	discreteUpdates?: <T>(fn: () => T) => T
 }
 
 const r = reconciler as ReconcilerWithOptionalMethods
 
 export const flushPassiveEffects = r.flushPassiveEffects?.bind(r) ?? (() => {})
-export const flushSync = r.flushSync?.bind(r) ?? (<T>(fn?: () => T) => fn?.())
+// react-reconciler 0.33.0 renamed flushSync to flushSyncFromReconciler
+export const flushSync = r.flushSyncFromReconciler?.bind(r) ?? (<T>(fn?: () => T) => fn?.())
 export const batchedUpdates = r.batchedUpdates?.bind(r) ?? (<T>(fn: () => T) => fn())
-export const discreteUpdates = r.discreteUpdates?.bind(r) ?? (<T>(fn: () => T) => fn())

package/src/reconciler/noop-methods.ts

@@ -0,0 +1,55 @@
+/**
+ * No-op methods required by react-reconciler that we don't use.
+ * Extracted to reduce clutter in host-config.ts.
+ */
+
+/** Empty function stub */
+const noop = () => {}
+
+/** Stub methods that must be implemented but are unused in this renderer */
+export const noopMethods = {
+	// Visibility (could implement later)
+	hideInstance: noop,
+	unhideInstance: noop,
+	hideTextInstance: noop,
+	unhideTextInstance: noop,
+
+	// Form handling (not applicable to TUI)
+	resetFormInstance: noop,
+
+	// Post-paint callbacks (not applicable)
+	requestPostPaintCallback: noop,
+
+	// Scheduler events (not applicable)
+	trackSchedulerEvent: noop,
+
+	// Event types (not applicable)
+	resolveEventType: () => null,
+	resolveEventTimeStamp: () => -1.1,
+
+	// Instance preloading (always ready)
+	preloadInstance: () => true,
+
+	// Suspense commit handling (not using Suspense)
+	startSuspendingCommit: noop,
+	suspendInstance: noop,
+	waitForCommitToBeReady: () => null,
+	maySuspendCommit: () => false,
+
+	// Portal mounting (not using portals)
+	preparePortalMount: noop,
+
+	// Instance from node lookup (not applicable)
+	getInstanceFromNode: () => null,
+
+	// Active instance blur (not applicable)
+	beforeActiveInstanceBlur: noop,
+	afterActiveInstanceBlur: noop,
+
+	// Scope updates (not using scopes)
+	prepareScopeUpdate: noop,
+	getInstanceFromScope: () => null,
+
+	// Update preparation (always update)
+	prepareUpdate: () => true,
+} as const

package/src/reconciler/types.ts

@@ -1,66 +1,132 @@
-import type { CellBuffer, Palette } from "@effect-tui/core"
+import type { CellBuffer, Palette, Size, Rect } from "@effect-tui/core"
 
-export interface Rect {
-  x: number
-  y: number
-  w: number
-  h: number
-}
-
-export interface Size {
-  w: number
-  h: number
-}
+// Re-export for backwards compatibility
+export type { Size, Rect }
 
 export interface HostInstance {
-  /** Unique identifier */
-  id: string
-  /** Component type name */
-  type: string
+	/** Unique identifier */
+	id: string
+	/** Component type name */
+	type: string
 
-  /** Parent in tree */
-  parent: HostInstance | null
-  /** Children in tree */
-  children: HostInstance[]
+	/** Parent in tree */
+	parent: HostInstance | null
+	/** Children in tree */
+	children: HostInstance[]
 
-  /** Computed layout rect (set during layout phase) */
-  rect: Rect | null
+	/** Computed layout rect (set during layout phase) */
+	rect: Rect | null
 
-  /** Measure natural size given constraints */
-  measure(maxW: number, maxH: number): Size
+	/** @internal Marks this node as static content (for Static component) */
+	__static?: boolean
 
-  /** Assign final rect and layout children */
-  layout(rect: Rect): void
+	/** Measure natural size given constraints */
+	measure(maxW: number, maxH: number): Size
 
-  /** Render to buffer */
-  render(buffer: CellBuffer, palette: Palette): void
+	/** Assign final rect and layout children */
+	layout(rect: Rect): void
 
-  /** Update props from React */
-  updateProps(props: Record<string, unknown>): void
+	/** Render to buffer */
+	render(buffer: CellBuffer, palette: Palette): void
 
-  /** Cleanup on unmount */
-  destroy(): void
+	/** Update props from React */
+	updateProps(props: Record<string, unknown>): void
 
-  /** Add child */
-  appendChild(child: HostInstance): void
+	/** Cleanup on unmount */
+	destroy(): void
 
-  /** Remove child */
-  removeChild(child: HostInstance): void
+	/** Add child */
+	appendChild(child: HostInstance): void
 
-  /** Insert child before another */
-  insertBefore(child: HostInstance, before: HostInstance): void
+	/** Remove child */
+	removeChild(child: HostInstance): void
+
+	/** Insert child before another */
+	insertBefore(child: HostInstance, before: HostInstance): void
 }
 
 export interface HostContext {
-  requestRender(): void
+	requestRender(): void
+	/** @internal Trigger immediate render (bypasses throttling) for static content */
+	requestImmediateRender?(): void
 }
 
-/** Props common to all host components */
+/**
+ * Props common to all host components.
+ *
+ * ## Frame Constraints (SwiftUI-style)
+ *
+ * Frame constraints control how a view negotiates size with its parent and children.
+ * They work like SwiftUI's `.frame()` modifier:
+ *
+ * ```tsx
+ * // Fixed size - view reports exactly this size to parent,
+ * // and proposes this size to children
+ * <vstack height={10} width={20}>
+ *
+ * // Min/max constraints - clamp the natural size
+ * <vstack minHeight={5} maxHeight={20}>
+ * ```
+ *
+ * ### How Layout Works (Two Phases)
+ *
+ * 1. **Measure phase**: Parent proposes a size → child returns its required size
+ * 2. **Layout phase**: Parent assigns final rect to child
+ *
+ * Frame constraints affect BOTH phases:
+ * - `constrainProposal()`: Modifies what we propose to children during measure
+ * - `constrainResult()`: Modifies what we report back to parent after measure
+ *
+ * ### Example: Popover at Bottom
+ *
+ * ```tsx
+ * <vstack height={termHeight}>  // Full screen
+ *   <spacer />                   // Takes remaining space
+ *   <vstack height={10}>         // Fixed 10 rows - key constraint!
+ *     <scroll>...</scroll>       // Greedy, but constrained by parent
+ *   </vstack>
+ * </vstack>
+ * ```
+ *
+ * Without `height={10}`, the inner vstack would report the scroll's greedy size.
+ * With the constraint, it reports exactly 10, so spacer gets the rest.
+ */
 export interface CommonProps {
-  /** Flex grow factor */
-  flexGrow?: number
-  /** Flex shrink factor */
-  flexShrink?: number
-  /** Index signature for Record<string, unknown> compatibility */
-  [key: string]: unknown
+	/** Flex grow factor - how much extra space this view takes (default: 0) */
+	flexGrow?: number
+	/** Flex shrink factor - how much this view shrinks when space is tight (default: 1) */
+	flexShrink?: number
+
+	// ─────────────────────────────────────────────────────────────
+	// Frame constraints (like SwiftUI's .frame modifier)
+	// ─────────────────────────────────────────────────────────────
+
+	/**
+	 * Fixed width constraint.
+	 * - Proposes this width to children (they measure within this constraint)
+	 * - Reports this width to parent (regardless of children's natural size)
+	 */
+	width?: number
+
+	/**
+	 * Fixed height constraint.
+	 * - Proposes this height to children (they measure within this constraint)
+	 * - Reports this height to parent (regardless of children's natural size)
+	 */
+	height?: number
+
+	/** Minimum width - natural size won't go below this */
+	minWidth?: number
+
+	/** Maximum width - natural size won't exceed this */
+	maxWidth?: number
+
+	/** Minimum height - natural size won't go below this */
+	minHeight?: number
+
+	/** Maximum height - natural size won't exceed this */
+	maxHeight?: number
+
+	/** Index signature for Record<string, unknown> compatibility */
+	[key: string]: unknown
 }

package/src/remote/Procedures.ts

@@ -0,0 +1,52 @@
+// RPC procedure definitions for remote session control
+import { Rpc, RpcGroup } from "@effect/rpc"
+import { Schema } from "effect"
+
+// Screenshot - returns the current screen as ANSI string
+const Screenshot = Rpc.make("Screenshot", {
+	success: Schema.String,
+})
+
+// SendKey - fires a key event into the TUI
+const SendKey = Rpc.make("SendKey", {
+	payload: {
+		name: Schema.String,
+		text: Schema.optional(Schema.String),
+		ctrl: Schema.optional(Schema.Boolean),
+		shift: Schema.optional(Schema.Boolean),
+		meta: Schema.optional(Schema.Boolean),
+	},
+})
+
+// Paste - sends text as a paste event
+const Paste = Rpc.make("Paste", {
+	payload: {
+		text: Schema.String,
+	},
+})
+
+// Resize - simulate terminal resize
+const Resize = Rpc.make("Resize", {
+	payload: {
+		width: Schema.Number,
+		height: Schema.Number,
+	},
+})
+
+// Info - get session info
+const Info = Rpc.make("Info", {
+	success: Schema.Struct({
+		pid: Schema.Number,
+		width: Schema.Number,
+		height: Schema.Number,
+	}),
+})
+
+// Group all RPCs together
+export class TuiRpcs extends RpcGroup.make(
+	Screenshot,
+	SendKey,
+	Paste,
+	Resize,
+	Info,
+) {}