Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(editor): an entity the agent just touched says so, once

yhhea6c4bc89f91
diff --git a/desktop/src/outliner/OutlinerRow.tsx b/desktop/src/outliner/OutlinerRow.tsx
index bda8991a6..e1cdd0274 100644
--- a/desktop/src/outliner/OutlinerRow.tsx
+++ b/desktop/src/outliner/OutlinerRow.tsx
@@ -39,6 +39,8 @@ export interface OutlinerRowProps {
selected: boolean;
/** The built-in agent changed this entity in the open conversation. */
agentTouched?: boolean;
+ /** …and it happened just now, rather than at some point in the conversation. */
+ agentFresh?: boolean;
/** The pointer is over a transcript row that names this entity. */
agentPeeked?: boolean;
/** Keyboard-focus row (shows a focus ring; distinct from selection). */
@@ -105,6 +107,7 @@ function OutlinerRowInner(props: OutlinerRowProps) {
`${dropPos === 'before' ? ' drop-before' : ''}` +
`${dropPos === 'after' ? ' drop-after' : ''}` +
`${props.agentTouched ? ' agent-touched' : ''}` +
+ `${props.agentFresh ? ' agent-fresh' : ''}` +
`${props.agentPeeked ? ' agent-peek' : ''}`
}
style={{ paddingLeft: depth * 14 }}
diff --git a/desktop/src/outliner/agentFresh.ts b/desktop/src/outliner/agentFresh.ts
new file mode 100644
index 000000000..67b4b679a
--- /dev/null
+++ b/desktop/src/outliner/agentFresh.ts
@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file agentFresh.ts
+ * @brief Which rows the agent touched JUST NOW, as opposed to at some point.
+ *
+ * The dot beside a touched row is a standing fact — the agent has been here,
+ * and it stays until the checkpoint is acknowledged. A standing mark cannot
+ * also carry "this happened a second ago": a row created while you were reading
+ * another part of the tree arrives looking exactly like one from four turns
+ * back. So arrival gets its own moment and then stops being special.
+ *
+ * The membership test is pure and separately tested; the hook is the thin part
+ * that owns a timer.
+ */
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * The ids in `next` that were not in `prev`.
+ *
+ * Additions only. A row LEAVING the set (the checkpoint was acknowledged, so
+ * every dot clears at once) is not an event anyone needs flagged — and treating
+ * it as one would flash the whole tree on the click that was meant to calm it.
+ */
+export function newlyAdded(prev: ReadonlySet<number>, next: ReadonlySet<number>): number[] {
+ const out: number[] = [];
+ for (const id of next) if (!prev.has(id)) out.push(id);
+ return out;
+}
+
+/** How long a row stays fresh. Matches the `ag-settle` animation in agent.css —
+ * the class has to outlive the animation, or it stops mid-way. */
+const FRESH_MS = 900;
+
+/**
+ * The subset of `touched` that arrived since the last change.
+ *
+ * Empty on first render however much is already touched: reopening the panel is
+ * not the agent doing something, and a tree that lights up on mount teaches
+ * people to ignore the light.
+ */
+export function useAgentFresh(touched: ReadonlySet<number>): ReadonlySet<number> {
+ const seen = useRef<ReadonlySet<number> | null>(null);
+ const [fresh, setFresh] = useState<ReadonlySet<number>>(() => new Set());
+
+ useEffect(() => {
+ const prev = seen.current;
+ seen.current = touched;
+ // First run: adopt the set without announcing any of it.
+ if (prev === null) return;
+ const added = newlyAdded(prev, touched);
+ if (added.length === 0) return;
+ setFresh((f) => new Set([...f, ...added]));
+ const id = setTimeout(() => {
+ // Only this burst expires — a later one keeps its own moment, which is why
+ // the timer removes rather than clearing.
+ setFresh((f) => {
+ const next = new Set(f);
+ for (const e of added) next.delete(e);
+ return next;
+ });
+ }, FRESH_MS);
+ return () => clearTimeout(id);
+ }, [touched]);
+
+ return fresh;
+}
diff --git a/desktop/src/panels/Outliner.tsx b/desktop/src/panels/Outliner.tsx
index bc1b27939..c7195dc62 100644
--- a/desktop/src/panels/Outliner.tsx
+++ b/desktop/src/panels/Outliner.tsx
@@ -28,6 +28,7 @@ import { createFromSource, type EntitySource } from '@/engine/entitySources';
import { CreatePopover } from '@/components/CreatePopover';
import { Segmented } from '@/components/Segmented';
import { IconButton } from '@/components/IconButton';
+import { useAgentFresh } from '@/outliner/agentFresh';
// Must match .row height in outliner.css — the fixed row size the virtual list windows by.
const ROW_H = 24;
@@ -172,6 +173,12 @@ export function Outliner() {
const agentPeeked = useAgent((s) => s.peeked);
const agentAcked = useAgent((s) => s.checkpointDone);
const agentTouched = useMemo(() => touchedEntities(agentTurns, agentAcked), [agentTurns, agentAcked]);
+ // The ones that JUST joined that set. The dot beside a touched row is a
+ // standing fact — "the agent has been here" — and a standing mark cannot also
+ // say "this happened just now": a row that appears while you are reading
+ // elsewhere in the tree arrives with no more emphasis than one from four
+ // turns ago. So the arrival gets its own moment, and then stops.
+ const agentFresh = useAgentFresh(agentTouched);
const activeColumns = useMemo(() => OUTLINER_COLUMNS.filter((c) => !hiddenColumns.has(c.id)), [hiddenColumns]);
const columnCtx = useMemo<OutlinerColumnContext>(
() => ({
@@ -665,6 +672,7 @@ export function Outliner() {
cursored={cursor === it.key}
highlight={highlight}
agentTouched={it.kind === 'entity' && agentTouched.has(it.id)}
+ agentFresh={it.kind === 'entity' && agentFresh.has(it.id)}
agentPeeked={it.kind === 'entity' && agentPeeked.includes(it.id)}
renaming={renaming === it.key}
dropPos={drop?.key === it.key ? drop.pos : undefined}
diff --git a/desktop/src/theme/agent.css b/desktop/src/theme/agent.css
index 5a8e56f90..702806d09 100644
--- a/desktop/src/theme/agent.css
+++ b/desktop/src/theme/agent.css
@@ -584,6 +584,10 @@
@media (prefers-reduced-motion: reduce) {
.ag-spin, .ag-skel, .ag-dots i { animation: none; }
+ /* The dot still lands — it just does not travel. Removing the animation
+ entirely would take the arrival with it, and the arrival is the message. */
+ .row.agent-fresh .rname::after { animation: none; }
+ .row.agent-fresh .rname::before { display: none; }
}
/* ── The checkpoint a finished turn leaves behind ────────────────────────────
@@ -652,6 +656,34 @@
}
.row.agent-peek { box-shadow: inset 2px 0 0 var(--nebula); }
+/* The moment the dot lands, as distinct from the fact that it is there.
+ The dot's OWN channel, deliberately: the prototype flashed the row's
+ background, and the line above is the reason not to — even for a second, a
+ tint on a row that is also selected reads as neither. So the arrival is the
+ dot arriving: it grows in, and a ring leaves from under it. */
+.row.agent-fresh .rname::after { animation: ag-land 0.9s var(--e-out); }
+.row.agent-fresh .rname { position: relative; }
+.row.agent-fresh .rname::before {
+ content: '';
+ position: absolute;
+ right: -12px; top: 50%;
+ width: 4px; height: 4px;
+ margin-top: -2px;
+ border-radius: 50%;
+ box-shadow: 0 0 0 0 var(--nebula);
+ animation: ag-land-ring 0.9s var(--e-out);
+ pointer-events: none;
+}
+@keyframes ag-land {
+ 0% { transform: scale(0.2); opacity: 0; }
+ 45% { transform: scale(1.35); opacity: 1; }
+ 100% { transform: scale(1); opacity: 1; }
+}
+@keyframes ag-land-ring {
+ 0% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--nebula) 55%, transparent); }
+ 100% { box-shadow: 0 0 0 7px transparent; }
+}
+
/* ── The rail button ────────────────────────────────────────────────────────
A dot, because the rail is visible with the drawer closed and "it is still
working" / "it is waiting on me" have to be legible from across the window.
diff --git a/desktop/tests/agent-fresh.test.ts b/desktop/tests/agent-fresh.test.ts
new file mode 100644
index 000000000..aee99e8d8
--- /dev/null
+++ b/desktop/tests/agent-fresh.test.ts
@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Which outliner rows the agent touched JUST NOW. The dot is a standing
+ * fact and cannot also say "a second ago", so arrival is its own signal —
+ * and arrival means ADDITIONS, never the set emptying.
+ */
+import { describe, it, expect } from 'vitest';
+import { newlyAdded } from '../src/outliner/agentFresh';
+
+const set = (...ids: number[]): ReadonlySet<number> => new Set(ids);
+
+describe('newlyAdded', () => {
+ it('reports what joined', () => {
+ expect(newlyAdded(set(1, 2), set(1, 2, 7)).sort()).toEqual([7]);
+ });
+
+ it('says nothing when the set did not grow', () => {
+ expect(newlyAdded(set(1, 2), set(1, 2))).toEqual([]);
+ });
+
+ it('ignores what LEFT — acknowledging a checkpoint clears every dot at once, and flashing the whole tree on the click meant to calm it is backwards', () => {
+ expect(newlyAdded(set(1, 2, 3), set(2))).toEqual([]);
+ });
+
+ it('reports additions even when others left in the same change', () => {
+ expect(newlyAdded(set(1, 2), set(2, 9)).sort()).toEqual([9]);
+ });
+
+ it('treats everything as new against an empty start', () => {
+ expect(newlyAdded(set(), set(4, 5)).sort()).toEqual([4, 5]);
+ });
+});