@valyrianjs/terminal 0.1.2 → 0.2.0

package/src/render.ts

@@ -14,6 +14,25 @@ export interface TerminalRenderContext {
   theme?: TerminalTheme;
 }
 
+function validateRenderContextDimension(name: "cols" | "rows", value: number) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new RangeError(`Invalid render context ${name}: expected an integer >= 1`);
+  }
+  return value;
+}
+
+function validateRenderContext(context: TerminalRenderContext | undefined) {
+  if (typeof context === "undefined") {
+    return undefined;
+  }
+
+  return {
+    cols: validateRenderContextDimension("cols", context.cols),
+    rows: validateRenderContextDimension("rows", context.rows),
+    theme: context.theme
+  };
+}
+
 const VISUAL_STATE_ORDER: TerminalVisualState[] = [
   "disabled", "readonly", "loading", "empty", "muted", "error", "warning", "success", "invalid", "valid", "placeholder", "selection", "selected", "current", "expanded", "collapsed", "checked", "unchecked", "indeterminate", "editing", "submitted", "dragging", "dropTarget", "capturing", "focus", "hover", "pressed"
 ];
@@ -108,6 +127,20 @@ function styleSpan(kind: string, style?: TerminalStyleDefinition): ResolvedStyle
   return typeof style === "undefined" ? { kind } : { kind, style };
 }
 
+const BASE_STYLE_KIND_BY_TAG: Partial<Record<TerminalElementNode["tag"], string>> = {
+  "terminal-button": "button.base",
+  "terminal-input": "input.base",
+  "terminal-editor": "editor.base",
+  "terminal-list": "list.base",
+  "terminal-scroll": "scroll.base",
+  "terminal-log-view": "log.base",
+  "terminal-overlay": "overlay.base"
+};
+
+function baseStyleKindForNode(node: TerminalElementNode) {
+  return BASE_STYLE_KIND_BY_TAG[node.tag];
+}
+
 function nodeStates(node: TerminalElementNode) {
   const declared = Array.isArray(node.props.state) ? node.props.state : typeof node.props.state === "string" ? [node.props.state] : [];
   const states = new Set<TerminalVisualState>();
@@ -127,7 +160,7 @@ function resolveLayoutStyle(baseKind: string, node: TerminalElementNode, context
 }
 
 function resolveNodeLayoutStyle(node: TerminalElementNode, context?: TerminalRenderContext) {
-  return resolveTerminalStyle(node.props.style, context?.theme);
+  return mergeStyleDefinitions(resolveTerminalStyle(baseStyleKindForNode(node), context?.theme), resolveTerminalStyle(node.props.style, context?.theme));
 }
 
 function decoratedControlFrame(content: string[], style: TerminalStyleDefinition | undefined) {
@@ -146,11 +179,17 @@ function fullFrameSpans(kinds: string[], width: number, height: number): Termina
   return spans;
 }
 
-function resolveNodeStyle(node: TerminalElementNode, context?: TerminalRenderContext) {
-  let style = resolveTerminalStyle(node.props.style, context?.theme);
-  const spanKinds: ResolvedStyleSpan[] = typeof node.props.style === "string"
-    ? [styleSpan(node.props.style)]
-    : style ? [styleSpan("#style", style)] : [];
+function resolveNodeStyle(node: TerminalElementNode, context?: TerminalRenderContext, options: { includeBase?: boolean } = {}) {
+  const baseKind = options.includeBase === false ? undefined : baseStyleKindForNode(node);
+  let style = resolveTerminalStyle(baseKind, context?.theme);
+  const spanKinds: ResolvedStyleSpan[] = typeof baseKind === "undefined" ? [] : [styleSpan(baseKind)];
+  const explicitStyle = resolveTerminalStyle(node.props.style, context?.theme);
+  if (typeof node.props.style === "string") {
+    spanKinds.push(styleSpan(node.props.style));
+  } else if (explicitStyle) {
+    spanKinds.push(styleSpan("#style", explicitStyle));
+  }
+  style = mergeStyleDefinitions(style, explicitStyle);
   for (const state of nodeStates(node)) {
     const stateStyle = node.props.styles?.[state];
     if (stateStyle) {
@@ -745,18 +784,69 @@ function renderStandaloneFixedFrame(node: TerminalElementNode, context?: Termina
     : constrainFrame(frame, { width: size });
 }
 
-function overlayGeometry(node: TerminalElementNode) {
+function overlayMarginValue(value: unknown, axisSize: number, label: string) {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+      throw new RangeError(`${label} must be a non-negative finite integer or percentage string`);
+    }
+    return value;
+  }
+
+  if (typeof value === "string") {
+    const match = value.match(/^(\d+(?:\.\d+)?)%$/);
+    if (!match) {
+      throw new RangeError(`${label} must be a non-negative finite integer or percentage string`);
+    }
+
+    const percent = Number(match[1]);
+    if (!Number.isFinite(percent) || percent < 0) {
+      throw new RangeError(`${label} must be a non-negative finite integer or percentage string`);
+    }
+
+    return Math.round(axisSize * percent / 100);
+  }
+
+  throw new RangeError(`${label} must be a non-negative finite integer or percentage string`);
+}
+
+function overlayMargins(margin: unknown, width: number, height: number) {
+  if (typeof margin === "number" || typeof margin === "string") {
+    const x = overlayMarginValue(margin, width, "Overlay margin");
+    const y = overlayMarginValue(margin, height, "Overlay margin");
+    return { x, y };
+  }
+
+  if (margin && typeof margin === "object" && !Array.isArray(margin)) {
+    const axes = margin as { x?: unknown; y?: unknown };
+    return {
+      x: overlayMarginValue(axes.x, width, "Overlay margin x"),
+      y: overlayMarginValue(axes.y, height, "Overlay margin y")
+    };
+  }
+
+  throw new RangeError("Overlay margin is required");
+}
+
+function overlayGeometry(node: TerminalElementNode, width: number, height: number) {
+  const margin = overlayMargins(node.props.margin, width, height);
+  const overlayWidth = width - margin.x * 2;
+  const overlayHeight = height - margin.y * 2;
+
+  if (overlayWidth < 1 || overlayHeight < 1) {
+    throw new RangeError("Overlay margin leaves no renderable area");
+  }
+
   return {
-    x: positiveInteger(node.props.x, "Overlay x"),
-    y: positiveInteger(node.props.y, "Overlay y"),
-    width: positiveInteger(node.props.width, "Overlay width"),
-    height: positiveInteger(node.props.height, "Overlay height")
+    x: margin.x + 1,
+    y: margin.y + 1,
+    width: overlayWidth,
+    height: overlayHeight
   };
 }
 
-function renderOverlayChildFrame(node: TerminalElementNode, context?: TerminalRenderContext) {
-  const geometry = overlayGeometry(node);
-  let frame = constrainFrame(renderBodyFrame(node.children, {}, { cols: geometry.width, rows: geometry.height }), { width: geometry.width, height: geometry.height });
+function renderOverlayChildFrame(node: TerminalElementNode, width: number, height: number, context?: TerminalRenderContext) {
+  const geometry = overlayGeometry(node, width, height);
+  let frame = constrainFrame(renderBodyFrame(node.children, {}, { cols: geometry.width, rows: geometry.height, theme: context?.theme }), { width: geometry.width, height: geometry.height });
   frame = addContainerStyleSpans(frame, node, resolveNodeStyle(node, context));
   if (node.props.id && isFocusable(node)) {
     frame = addFocusableHitbox(frame, node as TerminalFocusNode);
@@ -766,8 +856,10 @@ function renderOverlayChildFrame(node: TerminalElementNode, context?: TerminalRe
 
 function applyDirectOverlays(base: TerminalFrame, overlays: TerminalElementNode[], context?: TerminalRenderContext) {
   let frame = base;
+  const width = Math.max(1, getFrameWidth(base));
+  const height = Math.max(1, getFrameHeight(base));
   for (const overlay of overlays) {
-    const rendered = renderOverlayChildFrame(overlay, context);
+    const rendered = renderOverlayChildFrame(overlay, width, height, context);
     frame = overlayFrame(frame, rendered.frame, rendered.geometry);
   }
   return frame;
@@ -829,8 +921,12 @@ function renderPaneFrame(node: TerminalElementNode, context?: TerminalRenderCont
   return overlays.length ? applyDirectOverlays(frame, overlays, context) : frame;
 }
 
-function renderStandaloneOverlayFrame(node: TerminalElementNode) {
-  const rendered = renderOverlayChildFrame(node);
+function renderStandaloneOverlayFrame(node: TerminalElementNode, context?: TerminalRenderContext) {
+  if (!context) {
+    throw new RangeError("Standalone Overlay requires exact render context dimensions");
+  }
+
+  const rendered = renderOverlayChildFrame(node, context.cols, context.rows, context);
   return rendered.frame;
 }
 
@@ -983,7 +1079,7 @@ function renderElementFrame(node: TerminalElementNode, context?: TerminalRenderC
     case "terminal-fixed":
       return renderStandaloneFixedFrame(node, context);
     case "terminal-overlay":
-      return renderStandaloneOverlayFrame(node);
+      return renderStandaloneOverlayFrame(node, context);
     case "terminal-log-view":
       return renderLogViewFrame(node, context);
     case "terminal-list": {
@@ -1018,7 +1114,7 @@ function renderElementFrame(node: TerminalElementNode, context?: TerminalRenderC
         }
       }
       const frame = createFrame(decorated.lines, [], decorated.cursor, spans);
-      const styled = addFullFrameSpans(frame, resolveNodeStyle(node, context).spanKinds);
+      const styled = addFullFrameSpans(frame, resolveNodeStyle(node, context, { includeBase: false }).spanKinds);
       if (!node.props.id) {
         return styled;
       }
@@ -1039,7 +1135,7 @@ function renderElementFrame(node: TerminalElementNode, context?: TerminalRenderC
     case "terminal-text": {
       const value = typeof node.props.value !== "undefined" ? plainText(node.props.value) : plainText(node.children.map(textContent).join(""));
       const frame = createFrame(value.split("\n"));
-      return addFullFrameSpans(frame, resolveNodeStyle(node, context).spanKinds);
+      return addFullFrameSpans(frame, resolveNodeStyle(node, context, { includeBase: false }).spanKinds);
     }
     case "terminal-input": {
       const value = typeof node.props.value !== "undefined" ? node.props.value : node.props.placeholder || "";
@@ -1058,7 +1154,7 @@ function renderElementFrame(node: TerminalElementNode, context?: TerminalRenderC
         const height = Math.max(1, getFrameHeight(decorated));
         const hitboxes = node.props.id ? [{ id: node.props.id, tag: node.tag, x1: 1, x2: width, y1: 1, y2: height, textStartX, textLength: stringValue.length }] : [];
         const spans = fullFrameSpans(["input.base"], width, height);
-        return addFullFrameSpans(createFrame(decorated.lines, hitboxes, decorated.cursor, spans), resolveNodeStyle(node, context).spanKinds);
+        return addFullFrameSpans(createFrame(decorated.lines, hitboxes, decorated.cursor, spans), resolveNodeStyle(node, context, { includeBase: false }).spanKinds);
       }
 
       const rendered = renderInputLine(stringValue, node.props.__inputState || { cursor: stringValue.length, anchor: stringValue.length }, inputPadding);
@@ -1067,7 +1163,7 @@ function renderElementFrame(node: TerminalElementNode, context?: TerminalRenderC
       const height = Math.max(1, getFrameHeight(decorated));
       const hitboxes = node.props.id ? [{ id: node.props.id, tag: node.tag, x1: 1, x2: width, y1: 1, y2: height, textStartX, textLength: stringValue.length }] : [];
       const spans = [...fullFrameSpans(["input.base", "input.focus"], width, height), ...decorated.spans];
-      return addFullFrameSpans(createFrame(decorated.lines, hitboxes, decorated.cursor, spans), resolveNodeStyle(node, context).spanKinds);
+      return addFullFrameSpans(createFrame(decorated.lines, hitboxes, decorated.cursor, spans), resolveNodeStyle(node, context, { includeBase: false }).spanKinds);
     }
     case "terminal-editor":
       return addFullFrameSpans(renderEditorFrame(node), resolveNodeStyle(node, context).spanKinds);
@@ -1080,7 +1176,7 @@ function renderElementFrame(node: TerminalElementNode, context?: TerminalRenderC
       const hitboxes = node.props.id ? [{ id: node.props.id, tag: node.tag, x1: 1, x2: width, y1: 1, y2: height }] : [];
       const kinds = ["button.base", ...nodeStates(node).map((state) => `button.${state}`)];
       const spans = fullFrameSpans(kinds, width, height);
-      return addFullFrameSpans(createFrame(decorated.lines, hitboxes, decorated.cursor, spans), resolveNodeStyle(node, context).spanKinds);
+      return addFullFrameSpans(createFrame(decorated.lines, hitboxes, decorated.cursor, spans), resolveNodeStyle(node, context, { includeBase: false }).spanKinds);
     }
     default:
       return mergeVertical(node.children.map((child) => renderTerminalFrame(child, context)));
@@ -1098,9 +1194,10 @@ export function renderTerminalNode(node: TerminalNode, context?: TerminalRenderC
   return renderTerminalFrame(node, context).lines.join("\n");
 }
 
-export function renderTerminal(input: any): string {
+export function renderTerminal(input: any, context?: TerminalRenderContext): string {
+  const renderContext = validateRenderContext(context);
   return renderValyrianTerminal(input)
-    .map((node) => renderTerminalNode(node))
+    .map((node) => renderTerminalNode(node, renderContext))
     .filter(Boolean)
     .join("\n")
     .trimEnd();

package/src/runtime.ts

@@ -61,9 +61,6 @@ function hasEventListener(node: DomNode, eventName: string) {
 }
 
 function resolveDispatchEventName(node: DomNode, eventName: string) {
-  if (eventName === "press" && !hasEventListener(node, "press") && hasEventListener(node, "click")) {
-    return "click";
-  }
   if (eventName === "change" && !hasEventListener(node, "change") && hasEventListener(node, "input")) {
     return "input";
   }
@@ -158,9 +155,6 @@ function normalizeValyrianInput(input: any): any {
   const tag = typeof input.tag === "string" ? input.tag : wrapComponent(input.tag);
   if (typeof tag === "string" && isTerminalTag(tag)) {
     const terminalProps = { ...props };
-    if (tag === "terminal-button" && typeof props.action === "function" && typeof props.onpress !== "function" && typeof props.onclick !== "function") {
-      props.onclick = props.action;
-    }
     if (typeof props.style === "object") {
       Reflect.deleteProperty(props, "style");
     }

package/src/session.ts

@@ -24,6 +24,7 @@ import type {
   TerminalCaptureEventPayload,
   TerminalClipboardAdapter,
   TerminalFocusNode,
+  TerminalHitbox,
   TerminalListChangeEventPayload,
   TerminalListPressEventPayload,
   TerminalMountOptions,
@@ -71,6 +72,7 @@ const KNOWN_TERMINAL_KEY_SEQUENCES = [
 ];
 const ESCAPE = "\u001b";
 const CSI_PREFIX = "\u001b[";
+const DOUBLE_PRESS_INTERVAL_MS = 500;
 
 function isBracketedPasteStartPrefix(value: string) {
   return value.length > 0 && value.length < BRACKETED_PASTE_START.length && BRACKETED_PASTE_START.startsWith(value);
@@ -198,6 +200,7 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
   let pendingPasteChunk = "";
   let pendingKeyChunk = "";
   let pendingEscapeFlush: ReturnType<typeof setTimeout> | null = null;
+  let lastPrimaryPress: { id: string; tag: string; row: number | null; at: number } | null = null;
   let destroyed = false;
   let autoProjectionEnabled = false;
   let suppressAutoProjection = false;
@@ -492,6 +495,57 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
     }
   }
 
+
+  function dispatchListPressEvent(node: TerminalFocusNode, type: TerminalListPressEventPayload["type"], index: number) {
+    const id = node.props.id;
+    if (!id) {
+      return false;
+    }
+    const items = Array.isArray(node.props.items) ? node.props.items : [];
+    if (typeof items[index] === "undefined") {
+      return false;
+    }
+    const payload: TerminalListPressEventPayload = { type, id, index, value: items[index] };
+    return dispatchNodeEvent(node, type, payload);
+  }
+
+  function dispatchButtonPressEvent(node: TerminalFocusNode, type: "press" | "doublepress" | "contextpress") {
+    const id = String(node.props.id || "");
+    if (!id) {
+      return false;
+    }
+    return dispatchNodeEvent(node, type, { type, id });
+  }
+
+  function dispatchListPointerPressEvent(node: TerminalFocusNode, type: "doublepress" | "contextpress", row: number) {
+    const items = Array.isArray(node.props.items) ? node.props.items : [];
+    const index = Math.max(0, Math.min(items.length - 1, row - 1));
+    return dispatchListPressEvent(node, type, index);
+  }
+
+  function dispatchInputContextPressEvent(node: TerminalFocusNode, hitbox: TerminalHitbox, x: number | null, y: number | null) {
+    const id = String(node.props.id || "");
+    if (!id) {
+      return false;
+    }
+    const value = stripTerminalControls(node.props.value ?? "");
+    const current = normalizeInputState(inputStateById.get(id), value.length);
+    const cursor = typeof x === "number" ? cursorFromHitbox(hitbox, x) : current.cursor;
+    return dispatchNodeEvent(node, "contextpress", { type: "contextpress", id, value, cursor, x, y });
+  }
+
+  function dispatchScrollContextPressEvent(node: TerminalFocusNode, row: number, x: number | null, y: number | null) {
+    if (!node.props.id) {
+      return false;
+    }
+    const lines = visibleScrollLines(node);
+    const index = Math.max(0, Math.min(lines.length - 1, row - 1));
+    if (typeof lines[index] === "undefined") {
+      return false;
+    }
+    return dispatchNodeEvent(node, "contextpress", { type: "contextpress", id: node.props.id, row: index + 1, value: lines[index], x, y });
+  }
+
   function emitMouseRowEvent(node: TerminalFocusNode, type: TerminalRowPointerEventPayload["type"], row: number, x: number | null = null, y: number | null = null) {
     if (!node.props.id) {
       return;
@@ -621,10 +675,8 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
     if (!id) {
       return currentOutput;
     }
-    const items = Array.isArray(node.props.items) ? node.props.items : [];
     const currentIndex = listIndexById.get(id) || 0;
-    const payload: TerminalListPressEventPayload = { type: "press", id, index: currentIndex, value: items[currentIndex] };
-    dispatchNodeEvent(node, "press", payload);
+    dispatchListPressEvent(node, "press", currentIndex);
     return rerender();
   }
 
@@ -821,8 +873,7 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
         return currentOutput;
       case "button.press":
         if (node?.tag === "terminal-button") {
-          const id = String(node.props.id || "");
-          dispatchNodeEvent(node, "press", { type: "press", id });
+          dispatchButtonPressEvent(node, "press");
           return rerender();
         }
         return currentOutput;
@@ -946,7 +997,7 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
       if (id) {
         focusedId = node.props.id || focusedId;
       }
-      dispatchNodeEvent(node, "press", { type: "press", id: String(node.props.id || "") });
+      dispatchButtonPressEvent(node, "press");
       return rerender();
     },
     clickAt(x: number, y: number) {
@@ -1100,6 +1151,77 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
     }
   }
 
+
+  function isPrimaryMouseButton(button: number) {
+    return button < 64 && (button & 3) === 0;
+  }
+
+  function isContextMouseButton(button: number) {
+    return button < 64 && (button & 3) === 2;
+  }
+
+  function isDoublePrimaryPress(hitbox: { id: string; tag: string }, row: number | null) {
+    const now = Date.now();
+    const isDouble = Boolean(
+      lastPrimaryPress
+        && lastPrimaryPress.id === hitbox.id
+        && lastPrimaryPress.tag === hitbox.tag
+        && lastPrimaryPress.row === row
+        && now - lastPrimaryPress.at <= DOUBLE_PRESS_INTERVAL_MS
+    );
+    lastPrimaryPress = { id: hitbox.id, tag: hitbox.tag, row, at: now };
+    return isDouble;
+  }
+
+  function doublePressAt(hitbox: { id: string; tag: string; y1: number }, x: number, y: number) {
+    const node = findFocusableById(currentTree, hitbox.id);
+    if (!node) {
+      return currentOutput;
+    }
+    focusedId = hitbox.id;
+    setSemanticHoverFromHitbox(hitbox.id, x, y);
+    if (node.tag === "terminal-button") {
+      dispatchButtonPressEvent(node, "doublepress");
+      return rerender();
+    }
+    if (node.tag === "terminal-list") {
+      dispatchListPointerPressEvent(node, "doublepress", sourceRowFromHitbox(node, hitbox, y));
+      return rerender();
+    }
+    return currentOutput;
+  }
+
+  function contextPressAt(x: number, y: number) {
+    const hitbox = resolvePointerTarget(currentHitboxes, x, y);
+    if (!hitbox) {
+      clearSemanticHover(undefined, x, y);
+      return currentOutput;
+    }
+    const node = findFocusableById(currentTree, hitbox.id);
+    if (!node) {
+      return currentOutput;
+    }
+    focusedId = hitbox.id;
+    setSemanticHoverFromHitbox(hitbox.id, x, y);
+    if (node.tag === "terminal-button") {
+      dispatchButtonPressEvent(node, "contextpress");
+      return rerender();
+    }
+    if (node.tag === "terminal-list") {
+      dispatchListPointerPressEvent(node, "contextpress", sourceRowFromHitbox(node, hitbox, y));
+      return rerender();
+    }
+    if (node.tag === "terminal-input") {
+      dispatchInputContextPressEvent(node, hitbox, x, y);
+      return rerender();
+    }
+    if (node.tag === "terminal-scroll") {
+      dispatchScrollContextPressEvent(node, sourceRowFromHitbox(node, hitbox, y), x, y);
+      return rerender();
+    }
+    return currentOutput;
+  }
+
   function processInputStream(value: string) {
     if (!value) {
       return;
@@ -1161,6 +1283,11 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
     if (parsed.type === "mouse") {
       if (parsed.action === "press") {
         const hitbox = resolvePointerTarget(currentHitboxes, parsed.x, parsed.y);
+        if (isContextMouseButton(parsed.button)) {
+          lastPrimaryPress = null;
+          contextPressAt(parsed.x, parsed.y);
+          return;
+        }
         if (hitbox?.tag === "terminal-input") {
           mouseSelectionId = hitbox.id;
         }
@@ -1168,7 +1295,28 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
         if (hitbox && node && shouldPointerCapture(node)) {
           setPointerCapture(hitbox.id, "press", sourceRowFromHitbox(node, hitbox, parsed.y), parsed.x, parsed.y);
         }
+        const isPrimaryPress = isPrimaryMouseButton(parsed.button);
+        const isDoublePressEligible = Boolean(
+          hitbox
+            && node
+            && (hitbox.tag === "terminal-button" || hitbox.tag === "terminal-list")
+        );
+        const primaryPressRow = hitbox && node && hitbox.tag === "terminal-list"
+          ? sourceRowFromHitbox(node, hitbox, parsed.y)
+          : null;
+        const shouldDispatchDoublePress = Boolean(
+          isPrimaryPress
+            && isDoublePressEligible
+            && hitbox
+            && isDoublePrimaryPress(hitbox, primaryPressRow)
+        );
+        if (isPrimaryPress && !isDoublePressEligible) {
+          lastPrimaryPress = null;
+        }
         session.clickAt(parsed.x, parsed.y);
+        if (hitbox && shouldDispatchDoublePress) {
+          doublePressAt(hitbox, parsed.x, parsed.y);
+        }
       } else if (parsed.action === "drag") {
         if (mouseSelectionId) {
           setCursorFromHitbox(mouseSelectionId, parsed.x, true);

package/src/types.ts

@@ -287,7 +287,7 @@ export interface TerminalEditorCancelEventPayload extends TerminalValueEventPayl
 }
 
 export interface TerminalButtonPressEventPayload extends TerminalEventPayloadBase {
-  type: "press" | "click";
+  type: "press" | "doublepress" | "contextpress";
 }
 
 export interface TerminalListChangeEventPayload<T = any> extends TerminalValueEventPayloadBase<T> {
@@ -296,7 +296,7 @@ export interface TerminalListChangeEventPayload<T = any> extends TerminalValueEv
 }
 
 export interface TerminalListPressEventPayload<T = any> extends TerminalValueEventPayloadBase<T> {
-  type: "press";
+  type: "press" | "doublepress" | "contextpress";
   index: number;
 }
 
@@ -307,6 +307,16 @@ export type TerminalChangeEventPayload =
 
 export type TerminalPressEventPayload = TerminalButtonPressEventPayload | TerminalListPressEventPayload<any>;
 
+export interface TerminalInputContextPressEventPayload extends TerminalValueEventPayloadBase<string>, TerminalPointerCoordinates {
+  type: "contextpress";
+  cursor: number;
+}
+
+export interface TerminalScrollContextPressEventPayload extends TerminalRowPointerEventPayloadBase {
+  type: "contextpress";
+  value: string;
+}
+
 export type TerminalMouseEventType = "hover" | "rowenter" | "rowleave";
 
 export type TerminalPointerSource = "press" | "drag" | "release";
@@ -347,6 +357,7 @@ export interface TerminalInputProps extends TerminalFocusableProps, TerminalStyl
   onchange?(event: TerminalInputChangeEventPayload): void;
   oninput?(event: TerminalInputChangeEventPayload): void;
   onsubmit?(event: TerminalInputSubmitEventPayload): void;
+  oncontextpress?(event: TerminalInputContextPressEventPayload): void;
 }
 
 export interface TerminalEditorProps extends TerminalFocusableProps, TerminalStyleProps {
@@ -362,18 +373,20 @@ export interface TerminalEditorProps extends TerminalFocusableProps, TerminalSty
 export interface TerminalButtonProps extends TerminalFocusableProps, TerminalStyleProps {
   label?: string;
   onpress?(event: TerminalButtonPressEventPayload): void;
-  onclick?(event: TerminalButtonPressEventPayload): void;
-  action?(event: TerminalButtonPressEventPayload): void;
+  ondoublepress?(event: TerminalButtonPressEventPayload): void;
+  oncontextpress?(event: TerminalButtonPressEventPayload): void;
 }
 
 export interface TerminalListProps<T = any> extends TerminalFocusableProps, TerminalPointerCaptureProps, TerminalStyleProps {
-  items?: T[];
+  items?: readonly T[];
   virtualized?: boolean;
   itemHeight?: 1;
   overscan?: number;
   renderItem?(item: T, index: number): string;
   onchange?(event: TerminalListChangeEventPayload<T>): void;
   onpress?(event: TerminalListPressEventPayload<T>): void;
+  ondoublepress?(event: TerminalListPressEventPayload<T>): void;
+  oncontextpress?(event: TerminalListPressEventPayload<T>): void;
   onhover?(event: TerminalListPointerEventPayload<T>): void;
   onrowenter?(event: TerminalListPointerEventPayload<T>): void;
   onrowleave?(event: TerminalListPointerEventPayload<T>): void;
@@ -386,6 +399,7 @@ export interface TerminalScrollViewProps extends TerminalLayoutProps, TerminalPo
   onhover?(event: TerminalScrollPointerEventPayload): void;
   onrowenter?(event: TerminalScrollPointerEventPayload): void;
   onrowleave?(event: TerminalScrollPointerEventPayload): void;
+  oncontextpress?(event: TerminalScrollContextPressEventPayload): void;
   oncapturestart?(event: TerminalCaptureEventPayload): void;
   oncaptureend?(event: TerminalCaptureEventPayload): void;
 }
@@ -438,11 +452,15 @@ export interface TerminalFixedProps {
   size: number;
 }
 
+export type TerminalOverlayMarginValue = number | `${number}%`;
+
+export interface TerminalOverlayMarginAxes {
+  x: TerminalOverlayMarginValue;
+  y: TerminalOverlayMarginValue;
+}
+
 export interface TerminalOverlayProps extends TerminalFocusableProps, TerminalStyleProps {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
+  margin: TerminalOverlayMarginValue | TerminalOverlayMarginAxes;
   trapFocus?: boolean;
 }