@agent-native/core 0.85.6 → 0.86.0

package/dist/client/visual-style-controls.js

@@ -0,0 +1,150 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState, } from "react";
+import { cn } from "./utils.js";
+function clampNumber(value, min, max) {
+    let next = value;
+    if (typeof min === "number")
+        next = Math.max(min, next);
+    if (typeof max === "number")
+        next = Math.min(max, next);
+    return next;
+}
+function formatNumber(value, unit) {
+    const rounded = Number.isInteger(value) ? value : Number(value.toFixed(2));
+    return unit ? `${rounded}${unit}` : String(rounded);
+}
+function parseDraftNumber(value, fallback) {
+    const match = value.trim().match(/-?\d+(?:\.\d+)?/);
+    if (!match)
+        return fallback;
+    const next = Number(match[0]);
+    return Number.isFinite(next) ? next : fallback;
+}
+export function VisualInspectorPanel({ title, subtitle, children, className, headerAction, }) {
+    return (_jsxs("aside", { className: cn("w-64 overflow-hidden rounded-xl border border-border bg-card/95 text-card-foreground shadow-2xl shadow-black/35 backdrop-blur", className), children: [_jsxs("div", { className: "flex min-h-10 items-start justify-between gap-2 border-b border-border/70 px-3 py-2.5", children: [_jsxs("div", { className: "min-w-0", children: [_jsx("div", { className: "truncate text-[11px] font-semibold uppercase tracking-wide text-muted-foreground", children: title }), subtitle && (_jsx("div", { className: "mt-0.5 truncate text-[12px] text-foreground", children: subtitle }))] }), headerAction] }), _jsx("div", { className: "max-h-[min(680px,calc(100vh-7rem))] overflow-y-auto p-2", children: children })] }));
+}
+export function VisualInspectorSection({ title, children, className, }) {
+    return (_jsxs("section", { className: cn("rounded-lg px-1.5 py-2", className), children: [_jsx("div", { className: "mb-2 px-1 text-[10px] font-semibold uppercase tracking-wide text-muted-foreground/75", children: title }), _jsx("div", { className: "space-y-2", children: children })] }));
+}
+export function VisualControlRow({ label, children, className, }) {
+    return (_jsxs("div", { className: cn("grid gap-1", className), children: [_jsx("span", { className: "text-[11px] text-muted-foreground", children: label }), children] }));
+}
+export function VisualSwatchControl({ options, value, onChange, columns = 8, className, }) {
+    return (_jsx("div", { className: cn("grid gap-1.5", className), style: { gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))` }, children: options.map((option) => {
+            const swatch = option.color ?? option.value;
+            const isTransparent = swatch === "transparent";
+            return (_jsx("button", { type: "button", title: option.label, "aria-label": option.label, onClick: () => onChange(option.value), className: cn("size-5 cursor-pointer rounded-md border border-border/70 transition-all hover:scale-105 hover:border-foreground/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", value === option.value &&
+                    "border-foreground/70 ring-2 ring-foreground/40 ring-offset-1 ring-offset-card"), style: {
+                    background: isTransparent
+                        ? "linear-gradient(45deg, hsl(var(--muted)) 25%, transparent 25%), linear-gradient(-45deg, hsl(var(--muted)) 25%, transparent 25%), linear-gradient(45deg, transparent 75%, hsl(var(--muted)) 75%), linear-gradient(-45deg, transparent 75%, hsl(var(--muted)) 75%)"
+                        : swatch,
+                    backgroundPosition: isTransparent
+                        ? "0 0, 0 4px, 4px -4px, -4px 0"
+                        : undefined,
+                    backgroundSize: isTransparent ? "8px 8px" : undefined,
+                } }, `${option.value}-${option.label}`));
+        }) }));
+}
+export function VisualSegmentedControl({ options, value, onChange, className, }) {
+    return (_jsx("div", { className: cn("flex min-h-7 overflow-hidden rounded-md border border-border bg-background/60", className), children: options.map((option) => (_jsx("button", { type: "button", onClick: () => onChange(option.value), className: cn("min-w-0 flex-1 cursor-pointer px-2 text-[11px] font-medium text-muted-foreground transition-colors hover:bg-accent/70 hover:text-foreground", value === option.value && "bg-accent text-foreground"), children: _jsx("span", { className: "truncate", children: option.label }) }, option.value))) }));
+}
+export function VisualToggleControl({ checked, onChange, label, }) {
+    return (_jsx("button", { type: "button", "aria-pressed": checked, "aria-label": label, onClick: () => onChange(!checked), className: cn("relative h-5 w-9 cursor-pointer rounded-full border border-border transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", checked ? "bg-primary/35" : "bg-muted"), children: _jsx("span", { className: cn("absolute top-1/2 size-3.5 -translate-y-1/2 rounded-full bg-foreground shadow transition-transform", checked ? "translate-x-[18px]" : "translate-x-[3px]") }) }));
+}
+export function VisualSliderControl({ value, onChange, min = 0, max = 100, step = 1, unit, }) {
+    const safeValue = clampNumber(Number.isFinite(value) ? value : min, min, max);
+    return (_jsxs("div", { className: "flex h-7 items-center gap-2", children: [_jsx("input", { type: "range", min: min, max: max, step: step, value: safeValue, onChange: (event) => onChange(Number(event.currentTarget.value)), className: "min-w-0 flex-1 cursor-pointer accent-foreground" }), _jsx("span", { className: "w-9 text-right text-[11px] tabular-nums text-muted-foreground", children: formatNumber(safeValue, unit) })] }));
+}
+export function VisualScrubInput({ label, value, onChange, min, max, step = 1, unit, disabled = false, }) {
+    const id = useId();
+    const [draft, setDraft] = useState(() => formatNumber(value, unit));
+    const [focused, setFocused] = useState(false);
+    const dragRef = useRef(null);
+    useEffect(() => {
+        if (!focused)
+            setDraft(formatNumber(value, unit));
+    }, [focused, unit, value]);
+    const commit = (nextDraft = draft) => {
+        const parsed = parseDraftNumber(nextDraft, value);
+        const next = clampNumber(parsed, min, max);
+        onChange(next);
+        setDraft(formatNumber(next, unit));
+    };
+    const setNext = (next) => {
+        const clamped = clampNumber(next, min, max);
+        onChange(clamped);
+        setDraft(formatNumber(clamped, unit));
+    };
+    const onKeyDown = (event) => {
+        if (event.key === "Enter") {
+            event.preventDefault();
+            commit();
+            event.currentTarget.blur();
+            return;
+        }
+        if (event.key === "Escape") {
+            event.preventDefault();
+            setDraft(formatNumber(value, unit));
+            event.currentTarget.blur();
+            return;
+        }
+        if (event.key === "ArrowUp" || event.key === "ArrowDown") {
+            event.preventDefault();
+            const mult = event.shiftKey || event.metaKey ? 10 : event.altKey ? 0.1 : 1;
+            const direction = event.key === "ArrowUp" ? 1 : -1;
+            const base = parseDraftNumber(draft, value);
+            setNext(base + direction * step * mult);
+        }
+    };
+    const onPointerDown = (event) => {
+        if (disabled || event.button !== 0)
+            return;
+        event.preventDefault();
+        dragRef.current = {
+            pointerId: event.pointerId,
+            prevX: event.clientX,
+            dragged: false,
+        };
+        event.currentTarget.setPointerCapture(event.pointerId);
+    };
+    const onPointerMove = (event) => {
+        const drag = dragRef.current;
+        if (!drag || drag.pointerId !== event.pointerId)
+            return;
+        const delta = event.clientX - drag.prevX;
+        if (delta === 0)
+            return;
+        drag.prevX = event.clientX;
+        drag.dragged = true;
+        const mult = event.shiftKey || event.metaKey ? 10 : event.altKey ? 0.1 : 1;
+        setNext(value + delta * step * mult);
+    };
+    const onPointerUp = (event) => {
+        const drag = dragRef.current;
+        if (!drag || drag.pointerId !== event.pointerId)
+            return;
+        event.currentTarget.releasePointerCapture(event.pointerId);
+        dragRef.current = null;
+        if (!drag.dragged) {
+            document.getElementById(id)?.focus();
+        }
+    };
+    return (_jsxs("div", { className: "flex items-center gap-1.5", children: [_jsx("label", { htmlFor: id, onPointerDown: onPointerDown, onPointerMove: onPointerMove, onPointerUp: onPointerUp, className: cn("flex w-8 shrink-0 cursor-ew-resize select-none items-center justify-center rounded border border-transparent px-1 text-[10px] font-semibold text-muted-foreground hover:border-border hover:bg-accent/60", disabled && "cursor-not-allowed opacity-50"), children: label }), _jsx("input", { id: id, value: draft, disabled: disabled, onFocus: () => setFocused(true), onBlur: () => {
+                    setFocused(false);
+                    commit();
+                }, onChange: (event) => setDraft(event.currentTarget.value), onKeyDown: onKeyDown, className: "h-7 min-w-0 flex-1 rounded-md border border-input bg-background/70 px-2 text-right text-[11px] tabular-nums text-foreground outline-none transition-colors focus:border-ring focus:ring-1 focus:ring-ring disabled:opacity-50" })] }));
+}
+export function VisualTweakControl({ tweak, value, onChange, className, }) {
+    if (tweak.type === "toggle") {
+        return (_jsxs("div", { className: cn("flex h-7 items-center justify-between gap-2", className), children: [_jsx("span", { className: "truncate text-[11px] text-muted-foreground", children: tweak.label }), _jsx(VisualToggleControl, { checked: Boolean(value), onChange: onChange, label: tweak.label })] }));
+    }
+    const numericValue = typeof value === "number"
+        ? value
+        : typeof value === "string"
+            ? Number(value)
+            : Number(tweak.defaultValue);
+    return (_jsxs(VisualControlRow, { label: tweak.label, className: className, children: [(tweak.type === "color-swatch" ||
+                tweak.type === "color-swatches") && (_jsx(VisualSwatchControl, { options: tweak.options ?? [], value: String(value), onChange: onChange })), tweak.type === "segment" && (_jsx(VisualSegmentedControl, { options: tweak.options ?? [], value: String(value), onChange: onChange })), tweak.type === "slider" && (_jsx(VisualSliderControl, { min: tweak.min ?? 0, max: tweak.max ?? 100, step: tweak.step ?? 1, unit: tweak.unit ??
+                    (tweak.cssVar?.toLowerCase().includes("radius") ? "px" : undefined), value: Number.isFinite(numericValue) ? numericValue : 0, onChange: onChange }))] }));
+}
+//# sourceMappingURL=visual-style-controls.js.map

package/dist/client/visual-style-controls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-style-controls.js","sourceRoot":"","sources":["../../src/client/visual-style-controls.tsx"],"names":[],"mappings":"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","sourcesContent":["import {\n  useEffect,\n  useId,\n  useRef,\n  useState,\n  type KeyboardEvent,\n  type PointerEvent,\n  type ReactNode,\n} from \"react\";\n\nimport { cn } from \"./utils.js\";\n\nexport type VisualControlValue = string | number | boolean;\n\nexport interface VisualControlOption {\n  label: string;\n  value: string;\n  color?: string;\n}\n\nexport interface VisualTweakDefinition {\n  id: string;\n  label: string;\n  type: \"color-swatch\" | \"color-swatches\" | \"segment\" | \"slider\" | \"toggle\";\n  options?: VisualControlOption[];\n  min?: number;\n  max?: number;\n  step?: number;\n  defaultValue: VisualControlValue;\n  cssVar?: string;\n  unit?: string;\n}\n\nfunction clampNumber(value: number, min?: number, max?: number) {\n  let next = value;\n  if (typeof min === \"number\") next = Math.max(min, next);\n  if (typeof max === \"number\") next = Math.min(max, next);\n  return next;\n}\n\nfunction formatNumber(value: number, unit?: string) {\n  const rounded = Number.isInteger(value) ? value : Number(value.toFixed(2));\n  return unit ? `${rounded}${unit}` : String(rounded);\n}\n\nfunction parseDraftNumber(value: string, fallback: number) {\n  const match = value.trim().match(/-?\\d+(?:\\.\\d+)?/);\n  if (!match) return fallback;\n  const next = Number(match[0]);\n  return Number.isFinite(next) ? next : fallback;\n}\n\nexport function VisualInspectorPanel({\n  title,\n  subtitle,\n  children,\n  className,\n  headerAction,\n}: {\n  title: ReactNode;\n  subtitle?: ReactNode;\n  children: ReactNode;\n  className?: string;\n  headerAction?: ReactNode;\n}) {\n  return (\n    <aside\n      className={cn(\n        \"w-64 overflow-hidden rounded-xl border border-border bg-card/95 text-card-foreground shadow-2xl shadow-black/35 backdrop-blur\",\n        className,\n      )}\n    >\n      <div className=\"flex min-h-10 items-start justify-between gap-2 border-b border-border/70 px-3 py-2.5\">\n        <div className=\"min-w-0\">\n          <div className=\"truncate text-[11px] font-semibold uppercase tracking-wide text-muted-foreground\">\n            {title}\n          </div>\n          {subtitle && (\n            <div className=\"mt-0.5 truncate text-[12px] text-foreground\">\n              {subtitle}\n            </div>\n          )}\n        </div>\n        {headerAction}\n      </div>\n      <div className=\"max-h-[min(680px,calc(100vh-7rem))] overflow-y-auto p-2\">\n        {children}\n      </div>\n    </aside>\n  );\n}\n\nexport function VisualInspectorSection({\n  title,\n  children,\n  className,\n}: {\n  title: ReactNode;\n  children: ReactNode;\n  className?: string;\n}) {\n  return (\n    <section className={cn(\"rounded-lg px-1.5 py-2\", className)}>\n      <div className=\"mb-2 px-1 text-[10px] font-semibold uppercase tracking-wide text-muted-foreground/75\">\n        {title}\n      </div>\n      <div className=\"space-y-2\">{children}</div>\n    </section>\n  );\n}\n\nexport function VisualControlRow({\n  label,\n  children,\n  className,\n}: {\n  label: ReactNode;\n  children: ReactNode;\n  className?: string;\n}) {\n  return (\n    <div className={cn(\"grid gap-1\", className)}>\n      <span className=\"text-[11px] text-muted-foreground\">{label}</span>\n      {children}\n    </div>\n  );\n}\n\nexport function VisualSwatchControl({\n  options,\n  value,\n  onChange,\n  columns = 8,\n  className,\n}: {\n  options: VisualControlOption[];\n  value: string;\n  onChange: (value: string) => void;\n  columns?: number;\n  className?: string;\n}) {\n  return (\n    <div\n      className={cn(\"grid gap-1.5\", className)}\n      style={{ gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))` }}\n    >\n      {options.map((option) => {\n        const swatch = option.color ?? option.value;\n        const isTransparent = swatch === \"transparent\";\n        return (\n          <button\n            key={`${option.value}-${option.label}`}\n            type=\"button\"\n            title={option.label}\n            aria-label={option.label}\n            onClick={() => onChange(option.value)}\n            className={cn(\n              \"size-5 cursor-pointer rounded-md border border-border/70 transition-all hover:scale-105 hover:border-foreground/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring\",\n              value === option.value &&\n                \"border-foreground/70 ring-2 ring-foreground/40 ring-offset-1 ring-offset-card\",\n            )}\n            style={{\n              background: isTransparent\n                ? \"linear-gradient(45deg, hsl(var(--muted)) 25%, transparent 25%), linear-gradient(-45deg, hsl(var(--muted)) 25%, transparent 25%), linear-gradient(45deg, transparent 75%, hsl(var(--muted)) 75%), linear-gradient(-45deg, transparent 75%, hsl(var(--muted)) 75%)\"\n                : swatch,\n              backgroundPosition: isTransparent\n                ? \"0 0, 0 4px, 4px -4px, -4px 0\"\n                : undefined,\n              backgroundSize: isTransparent ? \"8px 8px\" : undefined,\n            }}\n          />\n        );\n      })}\n    </div>\n  );\n}\n\nexport function VisualSegmentedControl({\n  options,\n  value,\n  onChange,\n  className,\n}: {\n  options: VisualControlOption[];\n  value: string;\n  onChange: (value: string) => void;\n  className?: string;\n}) {\n  return (\n    <div\n      className={cn(\n        \"flex min-h-7 overflow-hidden rounded-md border border-border bg-background/60\",\n        className,\n      )}\n    >\n      {options.map((option) => (\n        <button\n          key={option.value}\n          type=\"button\"\n          onClick={() => onChange(option.value)}\n          className={cn(\n            \"min-w-0 flex-1 cursor-pointer px-2 text-[11px] font-medium text-muted-foreground transition-colors hover:bg-accent/70 hover:text-foreground\",\n            value === option.value && \"bg-accent text-foreground\",\n          )}\n        >\n          <span className=\"truncate\">{option.label}</span>\n        </button>\n      ))}\n    </div>\n  );\n}\n\nexport function VisualToggleControl({\n  checked,\n  onChange,\n  label,\n}: {\n  checked: boolean;\n  onChange: (checked: boolean) => void;\n  label?: string;\n}) {\n  return (\n    <button\n      type=\"button\"\n      aria-pressed={checked}\n      aria-label={label}\n      onClick={() => onChange(!checked)}\n      className={cn(\n        \"relative h-5 w-9 cursor-pointer rounded-full border border-border transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring\",\n        checked ? \"bg-primary/35\" : \"bg-muted\",\n      )}\n    >\n      <span\n        className={cn(\n          \"absolute top-1/2 size-3.5 -translate-y-1/2 rounded-full bg-foreground shadow transition-transform\",\n          checked ? \"translate-x-[18px]\" : \"translate-x-[3px]\",\n        )}\n      />\n    </button>\n  );\n}\n\nexport function VisualSliderControl({\n  value,\n  onChange,\n  min = 0,\n  max = 100,\n  step = 1,\n  unit,\n}: {\n  value: number;\n  onChange: (value: number) => void;\n  min?: number;\n  max?: number;\n  step?: number;\n  unit?: string;\n}) {\n  const safeValue = clampNumber(Number.isFinite(value) ? value : min, min, max);\n  return (\n    <div className=\"flex h-7 items-center gap-2\">\n      <input\n        type=\"range\"\n        min={min}\n        max={max}\n        step={step}\n        value={safeValue}\n        onChange={(event) => onChange(Number(event.currentTarget.value))}\n        className=\"min-w-0 flex-1 cursor-pointer accent-foreground\"\n      />\n      <span className=\"w-9 text-right text-[11px] tabular-nums text-muted-foreground\">\n        {formatNumber(safeValue, unit)}\n      </span>\n    </div>\n  );\n}\n\nexport function VisualScrubInput({\n  label,\n  value,\n  onChange,\n  min,\n  max,\n  step = 1,\n  unit,\n  disabled = false,\n}: {\n  label: string;\n  value: number;\n  onChange: (value: number) => void;\n  min?: number;\n  max?: number;\n  step?: number;\n  unit?: string;\n  disabled?: boolean;\n}) {\n  const id = useId();\n  const [draft, setDraft] = useState(() => formatNumber(value, unit));\n  const [focused, setFocused] = useState(false);\n  const dragRef = useRef<{\n    pointerId: number;\n    prevX: number;\n    dragged: boolean;\n  } | null>(null);\n\n  useEffect(() => {\n    if (!focused) setDraft(formatNumber(value, unit));\n  }, [focused, unit, value]);\n\n  const commit = (nextDraft = draft) => {\n    const parsed = parseDraftNumber(nextDraft, value);\n    const next = clampNumber(parsed, min, max);\n    onChange(next);\n    setDraft(formatNumber(next, unit));\n  };\n\n  const setNext = (next: number) => {\n    const clamped = clampNumber(next, min, max);\n    onChange(clamped);\n    setDraft(formatNumber(clamped, unit));\n  };\n\n  const onKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {\n    if (event.key === \"Enter\") {\n      event.preventDefault();\n      commit();\n      event.currentTarget.blur();\n      return;\n    }\n    if (event.key === \"Escape\") {\n      event.preventDefault();\n      setDraft(formatNumber(value, unit));\n      event.currentTarget.blur();\n      return;\n    }\n    if (event.key === \"ArrowUp\" || event.key === \"ArrowDown\") {\n      event.preventDefault();\n      const mult =\n        event.shiftKey || event.metaKey ? 10 : event.altKey ? 0.1 : 1;\n      const direction = event.key === \"ArrowUp\" ? 1 : -1;\n      const base = parseDraftNumber(draft, value);\n      setNext(base + direction * step * mult);\n    }\n  };\n\n  const onPointerDown = (event: PointerEvent<HTMLLabelElement>) => {\n    if (disabled || event.button !== 0) return;\n    event.preventDefault();\n    dragRef.current = {\n      pointerId: event.pointerId,\n      prevX: event.clientX,\n      dragged: false,\n    };\n    event.currentTarget.setPointerCapture(event.pointerId);\n  };\n\n  const onPointerMove = (event: PointerEvent<HTMLLabelElement>) => {\n    const drag = dragRef.current;\n    if (!drag || drag.pointerId !== event.pointerId) return;\n    const delta = event.clientX - drag.prevX;\n    if (delta === 0) return;\n    drag.prevX = event.clientX;\n    drag.dragged = true;\n    const mult = event.shiftKey || event.metaKey ? 10 : event.altKey ? 0.1 : 1;\n    setNext(value + delta * step * mult);\n  };\n\n  const onPointerUp = (event: PointerEvent<HTMLLabelElement>) => {\n    const drag = dragRef.current;\n    if (!drag || drag.pointerId !== event.pointerId) return;\n    event.currentTarget.releasePointerCapture(event.pointerId);\n    dragRef.current = null;\n    if (!drag.dragged) {\n      document.getElementById(id)?.focus();\n    }\n  };\n\n  return (\n    <div className=\"flex items-center gap-1.5\">\n      <label\n        htmlFor={id}\n        onPointerDown={onPointerDown}\n        onPointerMove={onPointerMove}\n        onPointerUp={onPointerUp}\n        className={cn(\n          \"flex w-8 shrink-0 cursor-ew-resize select-none items-center justify-center rounded border border-transparent px-1 text-[10px] font-semibold text-muted-foreground hover:border-border hover:bg-accent/60\",\n          disabled && \"cursor-not-allowed opacity-50\",\n        )}\n      >\n        {label}\n      </label>\n      <input\n        id={id}\n        value={draft}\n        disabled={disabled}\n        onFocus={() => setFocused(true)}\n        onBlur={() => {\n          setFocused(false);\n          commit();\n        }}\n        onChange={(event) => setDraft(event.currentTarget.value)}\n        onKeyDown={onKeyDown}\n        className=\"h-7 min-w-0 flex-1 rounded-md border border-input bg-background/70 px-2 text-right text-[11px] tabular-nums text-foreground outline-none transition-colors focus:border-ring focus:ring-1 focus:ring-ring disabled:opacity-50\"\n      />\n    </div>\n  );\n}\n\nexport function VisualTweakControl({\n  tweak,\n  value,\n  onChange,\n  className,\n}: {\n  tweak: VisualTweakDefinition;\n  value: VisualControlValue;\n  onChange: (value: VisualControlValue) => void;\n  className?: string;\n}) {\n  if (tweak.type === \"toggle\") {\n    return (\n      <div\n        className={cn(\"flex h-7 items-center justify-between gap-2\", className)}\n      >\n        <span className=\"truncate text-[11px] text-muted-foreground\">\n          {tweak.label}\n        </span>\n        <VisualToggleControl\n          checked={Boolean(value)}\n          onChange={onChange}\n          label={tweak.label}\n        />\n      </div>\n    );\n  }\n\n  const numericValue =\n    typeof value === \"number\"\n      ? value\n      : typeof value === \"string\"\n        ? Number(value)\n        : Number(tweak.defaultValue);\n\n  return (\n    <VisualControlRow label={tweak.label} className={className}>\n      {((tweak.type as string) === \"color-swatch\" ||\n        (tweak.type as string) === \"color-swatches\") && (\n        <VisualSwatchControl\n          options={tweak.options ?? []}\n          value={String(value)}\n          onChange={onChange}\n        />\n      )}\n      {tweak.type === \"segment\" && (\n        <VisualSegmentedControl\n          options={tweak.options ?? []}\n          value={String(value)}\n          onChange={onChange}\n        />\n      )}\n      {tweak.type === \"slider\" && (\n        <VisualSliderControl\n          min={tweak.min ?? 0}\n          max={tweak.max ?? 100}\n          step={tweak.step ?? 1}\n          unit={\n            tweak.unit ??\n            (tweak.cssVar?.toLowerCase().includes(\"radius\") ? \"px\" : undefined)\n          }\n          value={Number.isFinite(numericValue) ? numericValue : 0}\n          onChange={onChange}\n        />\n      )}\n    </VisualControlRow>\n  );\n}\n"]}

package/dist/collab/agent-presence.d.ts

@@ -5,26 +5,72 @@
  * collaborator — it "enters" a document, its edits are visible with
  * durable presence, and it "leaves" when done. Actions call these
  * instead of hand-rolling HTTP awareness calls.
+ *
+ * Presence lingers after the agent finishes editing (default 6s) so viewers
+ * get a moment to see who just changed what — the same way a human
+ * collaborator's cursor doesn't vanish the instant they stop typing. Recent
+ * edits are attributed in the awareness state (`recentEdits`, `lastEditAt`)
+ * so clients can render fading highlights over the edited regions.
+ *
+ * On serverless hosts the linger timer may never fire after the response is
+ * sent; the 30s awareness expiry then removes the entry, so presence degrades
+ * to "up to 30s" instead of leaking.
  */
+import { type RecentEdit } from "./recent-edits.js";
+/** How long agent presence lingers after leave/last edit before clearing. */
+export declare const AGENT_PRESENCE_LINGER_MS = 6000;
 /**
  * Mark the agent as present on a document.
  *
  * Sets an awareness entry for the agent and starts a heartbeat that
- * keeps it alive. If the agent is already present on this doc, just
- * refreshes `lastSeen` without creating a second interval.
+ * keeps it alive. If the agent is already present on this doc (including
+ * lingering after a previous edit), refreshes state without creating a
+ * second interval.
  */
 export declare function agentEnterDocument(docId: string, metadata?: Record<string, unknown>): void;
+export interface AgentLeaveOptions {
+    /**
+     * How long presence lingers before the awareness entry clears.
+     * Defaults to {@link AGENT_PRESENCE_LINGER_MS}. Pass 0 to clear
+     * immediately (e.g. when an operation failed before editing anything).
+     */
+    lingerMs?: number;
+}
 /**
- * Remove the agent's presence from a document.
+ * Release the agent's presence on a document.
  *
- * Clears the awareness entry and stops the heartbeat.
+ * Decrements the reference count; when it reaches zero the awareness entry
+ * lingers for `lingerMs` (default 6s) and is then removed. Viewers see the
+ * agent avatar/highlights for a beat after the edit completes instead of an
+ * instant disappearance.
  */
-export declare function agentLeaveDocument(docId: string): void;
+export declare function agentLeaveDocument(docId: string, options?: AgentLeaveOptions): void;
 /**
  * Update the agent's awareness state to include selection info
  * (e.g., which track, panel, or element the agent is working on).
  */
 export declare function agentUpdateSelection(docId: string, selection: Record<string, unknown>): void;
+export interface AgentTouchOptions {
+    /** Region descriptor + label recorded in the agent's recentEdits ring. */
+    edit?: Omit<RecentEdit, "at"> & {
+        at?: number;
+    };
+    /** Extra awareness fields to merge (e.g. `selection`). */
+    metadata?: Record<string, unknown>;
+    /** Linger before auto-clearing when no enter/leave pair is active. */
+    lingerMs?: number;
+}
+/**
+ * Record an agent edit on a document without requiring an explicit
+ * enter/leave pair. Used by the collab write paths so ANY agent edit
+ * produces visible presence + lingering attribution automatically.
+ *
+ * - Upserts the agent awareness entry (identity preserved/merged).
+ * - Appends to the `recentEdits` ring and bumps `lastEditAt`.
+ * - When no explicit operation is in flight (refcount 0), (re)schedules a
+ *   linger removal so presence fades out on its own.
+ */
+export declare function agentTouchDocument(docId: string, options?: AgentTouchOptions): void;
 /**
  * Apply search-and-replace edits incrementally so each one appears
  * as a separate poll event to connected clients.

package/dist/collab/agent-presence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-presence.d.ts","sourceRoot":"","sources":["../../src/collab/agent-presence.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,IAAI,CAuCN;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAgBtD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,IAAI,CA0BN;AAED;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,EAC/C,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;GAKG;AACH,wBAAsB,8BAA8B,CAClD,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,KAAK,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC,EACF,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,OAAO,CAAC,IAAI,CAAC,CAiCf"}
+{"version":3,"file":"agent-presence.d.ts","sourceRoot":"","sources":["../../src/collab/agent-presence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AASH,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAKtE,6EAA6E;AAC7E,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAoH9C;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,IAAI,CAUN;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,iBAAiB,GAC1B,IAAI,CASN;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,IAAI,CAGN;AAED,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,IAAI,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,iBAAiB,GAC1B,IAAI,CAoBN;AAED;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,EAC/C,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;GAKG;AACH,wBAAsB,8BAA8B,CAClD,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,KAAK,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC,EACF,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,OAAO,CAAC,IAAI,CAAC,CAiCf"}

package/dist/collab/agent-presence.js

@@ -5,41 +5,70 @@
  * collaborator — it "enters" a document, its edits are visible with
  * durable presence, and it "leaves" when done. Actions call these
  * instead of hand-rolling HTTP awareness calls.
+ *
+ * Presence lingers after the agent finishes editing (default 6s) so viewers
+ * get a moment to see who just changed what — the same way a human
+ * collaborator's cursor doesn't vanish the instant they stop typing. Recent
+ * edits are attributed in the awareness state (`recentEdits`, `lastEditAt`)
+ * so clients can render fading highlights over the edited regions.
+ *
+ * On serverless hosts the linger timer may never fire after the response is
+ * sent; the 30s awareness expiry then removes the entry, so presence degrades
+ * to "up to 30s" instead of leaking.
  */
 import { AGENT_CLIENT_ID, DEFAULT_AGENT_IDENTITY } from "./agent-identity.js";
-import { getDocAwareness } from "./awareness.js";
+import { deleteAwarenessRow, upsertAwarenessRow } from "./awareness-store.js";
+import { emitAwarenessChange, getDocAwareness, } from "./awareness.js";
+import { appendRecentEdit } from "./recent-edits.js";
 import { searchAndReplace } from "./ydoc-manager.js";
 const HEARTBEAT_INTERVAL = 10_000; // 10 seconds
+/** How long agent presence lingers after leave/last edit before clearing. */
+export const AGENT_PRESENCE_LINGER_MS = 6_000;
 // docId → heartbeat interval handle
 const _heartbeats = new Map();
 // docId → reference count (how many concurrent operations are using this doc)
 const _refCounts = new Map();
-/**
- * Mark the agent as present on a document.
- *
- * Sets an awareness entry for the agent and starts a heartbeat that
- * keeps it alive. If the agent is already present on this doc, just
- * refreshes `lastSeen` without creating a second interval.
- */
-export function agentEnterDocument(docId, metadata) {
+// docId → pending linger-removal timer
+const _lingerTimers = new Map();
+function cancelLinger(docId) {
+    const timer = _lingerTimers.get(docId);
+    if (timer) {
+        clearTimeout(timer);
+        _lingerTimers.delete(docId);
+    }
+}
+function removeAgentPresence(docId) {
+    cancelLinger(docId);
     const map = getDocAwareness(docId);
-    const state = JSON.stringify({
-        user: {
-            name: DEFAULT_AGENT_IDENTITY.name,
-            email: DEFAULT_AGENT_IDENTITY.email,
-            color: DEFAULT_AGENT_IDENTITY.color,
-        },
-        ...metadata,
-    });
-    const entry = {
-        clientId: AGENT_CLIENT_ID,
-        state,
-        lastSeen: Date.now(),
-    };
-    map.set(AGENT_CLIENT_ID, entry);
-    // Increment reference count
-    _refCounts.set(docId, (_refCounts.get(docId) ?? 0) + 1);
-    // Don't create another interval if one already exists
+    map.delete(AGENT_CLIENT_ID);
+    emitAwarenessChange(docId, currentAwarenessStates(map));
+    // Cross-instance removal (serverless) — best-effort, never blocks.
+    void deleteAwarenessRow(docId, AGENT_CLIENT_ID);
+    const interval = _heartbeats.get(docId);
+    if (interval) {
+        clearInterval(interval);
+        _heartbeats.delete(docId);
+    }
+}
+function scheduleLingerRemoval(docId, lingerMs) {
+    cancelLinger(docId);
+    if (lingerMs <= 0) {
+        removeAgentPresence(docId);
+        return;
+    }
+    const timer = setTimeout(() => {
+        _lingerTimers.delete(docId);
+        // A new operation may have re-entered while we waited.
+        if ((_refCounts.get(docId) ?? 0) > 0)
+            return;
+        removeAgentPresence(docId);
+    }, lingerMs);
+    if (typeof timer === "object" && "unref" in timer) {
+        timer.unref();
+    }
+    _lingerTimers.set(docId, timer);
+}
+function ensureHeartbeat(docId) {
     if (_heartbeats.has(docId))
         return;
     const interval = setInterval(() => {
@@ -47,6 +76,9 @@ export function agentEnterDocument(docId, metadata) {
         const existing = m.get(AGENT_CLIENT_ID);
         if (existing) {
             existing.lastSeen = Date.now();
+            // Keep the SQL mirror fresh too, or remote-instance pollers would see
+            // the agent expire mid-operation (store throttles unchanged writes).
+            void upsertAwarenessRow(docId, AGENT_CLIENT_ID, existing.state, existing.lastSeen);
         }
     }, HEARTBEAT_INTERVAL);
     // Don't block Node from exiting if this is the only timer left
@@ -55,54 +87,108 @@ export function agentEnterDocument(docId, metadata) {
     }
     _heartbeats.set(docId, interval);
 }
+function currentAwarenessStates(map) {
+    return Array.from(map, ([clientId, entry]) => ({
+        clientId,
+        state: entry.state,
+    }));
+}
+function readAgentState(docId) {
+    const existing = getDocAwareness(docId).get(AGENT_CLIENT_ID);
+    if (existing) {
+        try {
+            return JSON.parse(existing.state);
+        }
+        catch {
+            // Invalid state — fall through to defaults
+        }
+    }
+    return {
+        user: {
+            name: DEFAULT_AGENT_IDENTITY.name,
+            email: DEFAULT_AGENT_IDENTITY.email,
+            color: DEFAULT_AGENT_IDENTITY.color,
+        },
+    };
+}
+function writeAgentState(docId, state) {
+    const entry = {
+        clientId: AGENT_CLIENT_ID,
+        state: JSON.stringify(state),
+        lastSeen: Date.now(),
+    };
+    const map = getDocAwareness(docId);
+    map.set(AGENT_CLIENT_ID, entry);
+    emitAwarenessChange(docId, currentAwarenessStates(map));
+    // Mirror to SQL so pollers on other instances see the agent — an action
+    // often runs in a different serverless invocation than the poll route.
+    void upsertAwarenessRow(docId, AGENT_CLIENT_ID, entry.state, entry.lastSeen);
+}
+/**
+ * Mark the agent as present on a document.
+ *
+ * Sets an awareness entry for the agent and starts a heartbeat that
+ * keeps it alive. If the agent is already present on this doc (including
+ * lingering after a previous edit), refreshes state without creating a
+ * second interval.
+ */
+export function agentEnterDocument(docId, metadata) {
+    cancelLinger(docId);
+    const state = { ...readAgentState(docId), ...metadata };
+    writeAgentState(docId, state);
+    // Increment reference count
+    _refCounts.set(docId, (_refCounts.get(docId) ?? 0) + 1);
+    ensureHeartbeat(docId);
+}
 /**
- * Remove the agent's presence from a document.
+ * Release the agent's presence on a document.
  *
- * Clears the awareness entry and stops the heartbeat.
+ * Decrements the reference count; when it reaches zero the awareness entry
+ * lingers for `lingerMs` (default 6s) and is then removed. Viewers see the
+ * agent avatar/highlights for a beat after the edit completes instead of an
+ * instant disappearance.
  */
-export function agentLeaveDocument(docId) {
+export function agentLeaveDocument(docId, options) {
     const count = (_refCounts.get(docId) ?? 1) - 1;
     if (count > 0) {
         _refCounts.set(docId, count);
         return;
     }
     _refCounts.delete(docId);
-    const map = getDocAwareness(docId);
-    map.delete(AGENT_CLIENT_ID);
-    const interval = _heartbeats.get(docId);
-    if (interval) {
-        clearInterval(interval);
-        _heartbeats.delete(docId);
-    }
+    scheduleLingerRemoval(docId, options?.lingerMs ?? AGENT_PRESENCE_LINGER_MS);
 }
 /**
  * Update the agent's awareness state to include selection info
  * (e.g., which track, panel, or element the agent is working on).
  */
 export function agentUpdateSelection(docId, selection) {
-    const map = getDocAwareness(docId);
-    const existing = map.get(AGENT_CLIENT_ID);
-    let parsed = {
-        user: {
-            name: DEFAULT_AGENT_IDENTITY.name,
-            email: DEFAULT_AGENT_IDENTITY.email,
-            color: DEFAULT_AGENT_IDENTITY.color,
-        },
-    };
-    if (existing) {
-        try {
-            parsed = JSON.parse(existing.state);
-        }
-        catch {
-            // Invalid state — use defaults
-        }
+    const state = { ...readAgentState(docId), ...selection };
+    writeAgentState(docId, state);
+}
+/**
+ * Record an agent edit on a document without requiring an explicit
+ * enter/leave pair. Used by the collab write paths so ANY agent edit
+ * produces visible presence + lingering attribution automatically.
+ *
+ * - Upserts the agent awareness entry (identity preserved/merged).
+ * - Appends to the `recentEdits` ring and bumps `lastEditAt`.
+ * - When no explicit operation is in flight (refcount 0), (re)schedules a
+ *   linger removal so presence fades out on its own.
+ */
+export function agentTouchDocument(docId, options) {
+    cancelLinger(docId);
+    const state = { ...readAgentState(docId), ...(options?.metadata ?? {}) };
+    const now = Date.now();
+    if (options?.edit) {
+        const { at, ...rest } = options.edit;
+        state.recentEdits = appendRecentEdit(state.recentEdits, { ...rest, at: at ?? now });
+    }
+    state.lastEditAt = now;
+    writeAgentState(docId, state);
+    ensureHeartbeat(docId);
+    if ((_refCounts.get(docId) ?? 0) === 0) {
+        scheduleLingerRemoval(docId, options?.lingerMs ?? AGENT_PRESENCE_LINGER_MS);
     }
-    const state = JSON.stringify({ ...parsed, ...selection });
-    map.set(AGENT_CLIENT_ID, {
-        clientId: AGENT_CLIENT_ID,
-        state,
-        lastSeen: Date.now(),
-    });
 }
 /**
  * Apply search-and-replace edits incrementally so each one appears

package/dist/collab/agent-presence.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-presence.js","sourceRoot":"","sources":["../../src/collab/agent-presence.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Server-side agent presence lifecycle for collaborative editing.\n *\n * Provides enter/leave semantics so the agent behaves like a real\n * collaborator — it \"enters\" a document, its edits are visible with\n * durable presence, and it \"leaves\" when done. Actions call these\n * instead of hand-rolling HTTP awareness calls.\n */\n\nimport { AGENT_CLIENT_ID, DEFAULT_AGENT_IDENTITY } from \"./agent-identity.js\";\nimport { getDocAwareness, type AwarenessEntry } from \"./awareness.js\";\nimport { searchAndReplace } from \"./ydoc-manager.js\";\n\nconst HEARTBEAT_INTERVAL = 10_000; // 10 seconds\n\n// docId → heartbeat interval handle\nconst _heartbeats = new Map<string, NodeJS.Timeout>();\n// docId → reference count (how many concurrent operations are using this doc)\nconst _refCounts = new Map<string, number>();\n\n/**\n * Mark the agent as present on a document.\n *\n * Sets an awareness entry for the agent and starts a heartbeat that\n * keeps it alive. If the agent is already present on this doc, just\n * refreshes `lastSeen` without creating a second interval.\n */\nexport function agentEnterDocument(\n  docId: string,\n  metadata?: Record<string, unknown>,\n): void {\n  const map = getDocAwareness(docId);\n\n  const state = JSON.stringify({\n    user: {\n      name: DEFAULT_AGENT_IDENTITY.name,\n      email: DEFAULT_AGENT_IDENTITY.email,\n      color: DEFAULT_AGENT_IDENTITY.color,\n    },\n    ...metadata,\n  });\n\n  const entry: AwarenessEntry = {\n    clientId: AGENT_CLIENT_ID,\n    state,\n    lastSeen: Date.now(),\n  };\n  map.set(AGENT_CLIENT_ID, entry);\n\n  // Increment reference count\n  _refCounts.set(docId, (_refCounts.get(docId) ?? 0) + 1);\n\n  // Don't create another interval if one already exists\n  if (_heartbeats.has(docId)) return;\n\n  const interval = setInterval(() => {\n    const m = getDocAwareness(docId);\n    const existing = m.get(AGENT_CLIENT_ID);\n    if (existing) {\n      existing.lastSeen = Date.now();\n    }\n  }, HEARTBEAT_INTERVAL);\n\n  // Don't block Node from exiting if this is the only timer left\n  if (typeof interval === \"object\" && \"unref\" in interval) {\n    interval.unref();\n  }\n\n  _heartbeats.set(docId, interval);\n}\n\n/**\n * Remove the agent's presence from a document.\n *\n * Clears the awareness entry and stops the heartbeat.\n */\nexport function agentLeaveDocument(docId: string): void {\n  const count = (_refCounts.get(docId) ?? 1) - 1;\n  if (count > 0) {\n    _refCounts.set(docId, count);\n    return;\n  }\n  _refCounts.delete(docId);\n\n  const map = getDocAwareness(docId);\n  map.delete(AGENT_CLIENT_ID);\n\n  const interval = _heartbeats.get(docId);\n  if (interval) {\n    clearInterval(interval);\n    _heartbeats.delete(docId);\n  }\n}\n\n/**\n * Update the agent's awareness state to include selection info\n * (e.g., which track, panel, or element the agent is working on).\n */\nexport function agentUpdateSelection(\n  docId: string,\n  selection: Record<string, unknown>,\n): void {\n  const map = getDocAwareness(docId);\n  const existing = map.get(AGENT_CLIENT_ID);\n\n  let parsed: Record<string, unknown> = {\n    user: {\n      name: DEFAULT_AGENT_IDENTITY.name,\n      email: DEFAULT_AGENT_IDENTITY.email,\n      color: DEFAULT_AGENT_IDENTITY.color,\n    },\n  };\n\n  if (existing) {\n    try {\n      parsed = JSON.parse(existing.state) as Record<string, unknown>;\n    } catch {\n      // Invalid state — use defaults\n    }\n  }\n\n  const state = JSON.stringify({ ...parsed, ...selection });\n  map.set(AGENT_CLIENT_ID, {\n    clientId: AGENT_CLIENT_ID,\n    state,\n    lastSeen: Date.now(),\n  });\n}\n\n/**\n * Apply search-and-replace edits incrementally so each one appears\n * as a separate poll event to connected clients.\n *\n * Enters the document before editing and leaves in a finally block.\n */\nexport async function agentApplyEditsIncrementally(\n  docId: string,\n  edits: Array<{ find: string; replace: string }>,\n  options?: { delayMs?: number },\n): Promise<void> {\n  const delayMs = options?.delayMs ?? 150;\n  agentEnterDocument(docId);\n\n  try {\n    for (const edit of edits) {\n      await searchAndReplace(docId, edit.find, edit.replace, \"agent\");\n      if (delayMs > 0) {\n        await new Promise((r) => setTimeout(r, delayMs));\n      }\n    }\n  } finally {\n    agentLeaveDocument(docId);\n  }\n}\n\n/**\n * Apply structured data patches incrementally so each one appears\n * as a separate poll event to connected clients.\n *\n * Enters the document before patching and leaves in a finally block.\n */\nexport async function agentApplyPatchesIncrementally(\n  docId: string,\n  fieldName: string,\n  patches: Array<{\n    op: string;\n    path: string;\n    value?: unknown;\n    index?: number;\n    from?: number;\n    to?: number;\n  }>,\n  options?: { delayMs?: number },\n): Promise<void> {\n  const delayMs = options?.delayMs ?? 150;\n  agentEnterDocument(docId);\n\n  try {\n    // Resolve applyPatchOps dynamically so a build that strips it (or a partial\n    // upgrade) fails loudly here rather than at module load time.\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    let applyPatchOps: any;\n    try {\n      const mod = await import(\"./ydoc-manager.js\");\n      applyPatchOps = (mod as Record<string, unknown>).applyPatchOps;\n    } catch {\n      throw new Error(\n        \"applyPatchOps is not available yet — Phase 1 must complete first\",\n      );\n    }\n\n    if (typeof applyPatchOps !== \"function\") {\n      throw new Error(\n        \"applyPatchOps is not available yet — Phase 1 must complete first\",\n      );\n    }\n\n    for (const patch of patches) {\n      await applyPatchOps(docId, [patch], fieldName, \"agent\");\n      if (delayMs > 0) {\n        await new Promise((r) => setTimeout(r, delayMs));\n      }\n    }\n  } finally {\n    agentLeaveDocument(docId);\n  }\n}\n"]}
+{"version":3,"file":"agent-presence.js","sourceRoot":"","sources":["../../src/collab/agent-presence.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Server-side agent presence lifecycle for collaborative editing.\n *\n * Provides enter/leave semantics so the agent behaves like a real\n * collaborator — it \"enters\" a document, its edits are visible with\n * durable presence, and it \"leaves\" when done. Actions call these\n * instead of hand-rolling HTTP awareness calls.\n *\n * Presence lingers after the agent finishes editing (default 6s) so viewers\n * get a moment to see who just changed what — the same way a human\n * collaborator's cursor doesn't vanish the instant they stop typing. Recent\n * edits are attributed in the awareness state (`recentEdits`, `lastEditAt`)\n * so clients can render fading highlights over the edited regions.\n *\n * On serverless hosts the linger timer may never fire after the response is\n * sent; the 30s awareness expiry then removes the entry, so presence degrades\n * to \"up to 30s\" instead of leaking.\n */\n\nimport { AGENT_CLIENT_ID, DEFAULT_AGENT_IDENTITY } from \"./agent-identity.js\";\nimport { deleteAwarenessRow, upsertAwarenessRow } from \"./awareness-store.js\";\nimport {\n  emitAwarenessChange,\n  getDocAwareness,\n  type AwarenessEntry,\n} from \"./awareness.js\";\nimport { appendRecentEdit, type RecentEdit } from \"./recent-edits.js\";\nimport { searchAndReplace } from \"./ydoc-manager.js\";\n\nconst HEARTBEAT_INTERVAL = 10_000; // 10 seconds\n\n/** How long agent presence lingers after leave/last edit before clearing. */\nexport const AGENT_PRESENCE_LINGER_MS = 6_000;\n\n// docId → heartbeat interval handle\nconst _heartbeats = new Map<string, NodeJS.Timeout>();\n// docId → reference count (how many concurrent operations are using this doc)\nconst _refCounts = new Map<string, number>();\n// docId → pending linger-removal timer\nconst _lingerTimers = new Map<string, NodeJS.Timeout>();\n\nfunction cancelLinger(docId: string): void {\n  const timer = _lingerTimers.get(docId);\n  if (timer) {\n    clearTimeout(timer);\n    _lingerTimers.delete(docId);\n  }\n}\n\nfunction removeAgentPresence(docId: string): void {\n  cancelLinger(docId);\n  const map = getDocAwareness(docId);\n  map.delete(AGENT_CLIENT_ID);\n  emitAwarenessChange(docId, currentAwarenessStates(map));\n  // Cross-instance removal (serverless) — best-effort, never blocks.\n  void deleteAwarenessRow(docId, AGENT_CLIENT_ID);\n\n  const interval = _heartbeats.get(docId);\n  if (interval) {\n    clearInterval(interval);\n    _heartbeats.delete(docId);\n  }\n}\n\nfunction scheduleLingerRemoval(docId: string, lingerMs: number): void {\n  cancelLinger(docId);\n  if (lingerMs <= 0) {\n    removeAgentPresence(docId);\n    return;\n  }\n  const timer = setTimeout(() => {\n    _lingerTimers.delete(docId);\n    // A new operation may have re-entered while we waited.\n    if ((_refCounts.get(docId) ?? 0) > 0) return;\n    removeAgentPresence(docId);\n  }, lingerMs);\n  if (typeof timer === \"object\" && \"unref\" in timer) {\n    timer.unref();\n  }\n  _lingerTimers.set(docId, timer);\n}\n\nfunction ensureHeartbeat(docId: string): void {\n  if (_heartbeats.has(docId)) return;\n\n  const interval = setInterval(() => {\n    const m = getDocAwareness(docId);\n    const existing = m.get(AGENT_CLIENT_ID);\n    if (existing) {\n      existing.lastSeen = Date.now();\n      // Keep the SQL mirror fresh too, or remote-instance pollers would see\n      // the agent expire mid-operation (store throttles unchanged writes).\n      void upsertAwarenessRow(\n        docId,\n        AGENT_CLIENT_ID,\n        existing.state,\n        existing.lastSeen,\n      );\n    }\n  }, HEARTBEAT_INTERVAL);\n\n  // Don't block Node from exiting if this is the only timer left\n  if (typeof interval === \"object\" && \"unref\" in interval) {\n    interval.unref();\n  }\n\n  _heartbeats.set(docId, interval);\n}\n\nfunction currentAwarenessStates(map: Map<number, AwarenessEntry>) {\n  return Array.from(map, ([clientId, entry]) => ({\n    clientId,\n    state: entry.state,\n  }));\n}\n\nfunction readAgentState(docId: string): Record<string, unknown> {\n  const existing = getDocAwareness(docId).get(AGENT_CLIENT_ID);\n  if (existing) {\n    try {\n      return JSON.parse(existing.state) as Record<string, unknown>;\n    } catch {\n      // Invalid state — fall through to defaults\n    }\n  }\n  return {\n    user: {\n      name: DEFAULT_AGENT_IDENTITY.name,\n      email: DEFAULT_AGENT_IDENTITY.email,\n      color: DEFAULT_AGENT_IDENTITY.color,\n    },\n  };\n}\n\nfunction writeAgentState(docId: string, state: Record<string, unknown>): void {\n  const entry: AwarenessEntry = {\n    clientId: AGENT_CLIENT_ID,\n    state: JSON.stringify(state),\n    lastSeen: Date.now(),\n  };\n  const map = getDocAwareness(docId);\n  map.set(AGENT_CLIENT_ID, entry);\n  emitAwarenessChange(docId, currentAwarenessStates(map));\n  // Mirror to SQL so pollers on other instances see the agent — an action\n  // often runs in a different serverless invocation than the poll route.\n  void upsertAwarenessRow(docId, AGENT_CLIENT_ID, entry.state, entry.lastSeen);\n}\n\n/**\n * Mark the agent as present on a document.\n *\n * Sets an awareness entry for the agent and starts a heartbeat that\n * keeps it alive. If the agent is already present on this doc (including\n * lingering after a previous edit), refreshes state without creating a\n * second interval.\n */\nexport function agentEnterDocument(\n  docId: string,\n  metadata?: Record<string, unknown>,\n): void {\n  cancelLinger(docId);\n\n  const state = { ...readAgentState(docId), ...metadata };\n  writeAgentState(docId, state);\n\n  // Increment reference count\n  _refCounts.set(docId, (_refCounts.get(docId) ?? 0) + 1);\n\n  ensureHeartbeat(docId);\n}\n\nexport interface AgentLeaveOptions {\n  /**\n   * How long presence lingers before the awareness entry clears.\n   * Defaults to {@link AGENT_PRESENCE_LINGER_MS}. Pass 0 to clear\n   * immediately (e.g. when an operation failed before editing anything).\n   */\n  lingerMs?: number;\n}\n\n/**\n * Release the agent's presence on a document.\n *\n * Decrements the reference count; when it reaches zero the awareness entry\n * lingers for `lingerMs` (default 6s) and is then removed. Viewers see the\n * agent avatar/highlights for a beat after the edit completes instead of an\n * instant disappearance.\n */\nexport function agentLeaveDocument(\n  docId: string,\n  options?: AgentLeaveOptions,\n): void {\n  const count = (_refCounts.get(docId) ?? 1) - 1;\n  if (count > 0) {\n    _refCounts.set(docId, count);\n    return;\n  }\n  _refCounts.delete(docId);\n\n  scheduleLingerRemoval(docId, options?.lingerMs ?? AGENT_PRESENCE_LINGER_MS);\n}\n\n/**\n * Update the agent's awareness state to include selection info\n * (e.g., which track, panel, or element the agent is working on).\n */\nexport function agentUpdateSelection(\n  docId: string,\n  selection: Record<string, unknown>,\n): void {\n  const state = { ...readAgentState(docId), ...selection };\n  writeAgentState(docId, state);\n}\n\nexport interface AgentTouchOptions {\n  /** Region descriptor + label recorded in the agent's recentEdits ring. */\n  edit?: Omit<RecentEdit, \"at\"> & { at?: number };\n  /** Extra awareness fields to merge (e.g. `selection`). */\n  metadata?: Record<string, unknown>;\n  /** Linger before auto-clearing when no enter/leave pair is active. */\n  lingerMs?: number;\n}\n\n/**\n * Record an agent edit on a document without requiring an explicit\n * enter/leave pair. Used by the collab write paths so ANY agent edit\n * produces visible presence + lingering attribution automatically.\n *\n * - Upserts the agent awareness entry (identity preserved/merged).\n * - Appends to the `recentEdits` ring and bumps `lastEditAt`.\n * - When no explicit operation is in flight (refcount 0), (re)schedules a\n *   linger removal so presence fades out on its own.\n */\nexport function agentTouchDocument(\n  docId: string,\n  options?: AgentTouchOptions,\n): void {\n  cancelLinger(docId);\n\n  const state = { ...readAgentState(docId), ...(options?.metadata ?? {}) };\n  const now = Date.now();\n  if (options?.edit) {\n    const { at, ...rest } = options.edit;\n    state.recentEdits = appendRecentEdit(\n      state.recentEdits as RecentEdit[] | undefined,\n      { ...rest, at: at ?? now },\n    );\n  }\n  state.lastEditAt = now;\n  writeAgentState(docId, state);\n\n  ensureHeartbeat(docId);\n\n  if ((_refCounts.get(docId) ?? 0) === 0) {\n    scheduleLingerRemoval(docId, options?.lingerMs ?? AGENT_PRESENCE_LINGER_MS);\n  }\n}\n\n/**\n * Apply search-and-replace edits incrementally so each one appears\n * as a separate poll event to connected clients.\n *\n * Enters the document before editing and leaves in a finally block.\n */\nexport async function agentApplyEditsIncrementally(\n  docId: string,\n  edits: Array<{ find: string; replace: string }>,\n  options?: { delayMs?: number },\n): Promise<void> {\n  const delayMs = options?.delayMs ?? 150;\n  agentEnterDocument(docId);\n\n  try {\n    for (const edit of edits) {\n      await searchAndReplace(docId, edit.find, edit.replace, \"agent\");\n      if (delayMs > 0) {\n        await new Promise((r) => setTimeout(r, delayMs));\n      }\n    }\n  } finally {\n    agentLeaveDocument(docId);\n  }\n}\n\n/**\n * Apply structured data patches incrementally so each one appears\n * as a separate poll event to connected clients.\n *\n * Enters the document before patching and leaves in a finally block.\n */\nexport async function agentApplyPatchesIncrementally(\n  docId: string,\n  fieldName: string,\n  patches: Array<{\n    op: string;\n    path: string;\n    value?: unknown;\n    index?: number;\n    from?: number;\n    to?: number;\n  }>,\n  options?: { delayMs?: number },\n): Promise<void> {\n  const delayMs = options?.delayMs ?? 150;\n  agentEnterDocument(docId);\n\n  try {\n    // Resolve applyPatchOps dynamically so a build that strips it (or a partial\n    // upgrade) fails loudly here rather than at module load time.\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    let applyPatchOps: any;\n    try {\n      const mod = await import(\"./ydoc-manager.js\");\n      applyPatchOps = (mod as Record<string, unknown>).applyPatchOps;\n    } catch {\n      throw new Error(\n        \"applyPatchOps is not available yet — Phase 1 must complete first\",\n      );\n    }\n\n    if (typeof applyPatchOps !== \"function\") {\n      throw new Error(\n        \"applyPatchOps is not available yet — Phase 1 must complete first\",\n      );\n    }\n\n    for (const patch of patches) {\n      await applyPatchOps(docId, [patch], fieldName, \"agent\");\n      if (delayMs > 0) {\n        await new Promise((r) => setTimeout(r, delayMs));\n      }\n    }\n  } finally {\n    agentLeaveDocument(docId);\n  }\n}\n"]}