ef-agent-panel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Panel

The

EFAgentPanel

captures

ef-edit

CustomEvents dispatched whenever a user makes a meaningful composition edit in the GUI, deduplicates them by element+property via a keyed registry, groups them by selector, and renders a copy-able coding-agent prompt.

当用户在GUI中进行有意义的合成编辑时，

EFAgentPanel

会捕获派发的

ef-edit

CustomEvent事件，通过键控注册表按元素+属性去重，按选择器分组，并渲染可复制的编码Agent提示语。

Event Pipeline

事件流

GUI interaction (canvas drag, inspector change, trim drag, loop toggle)
  └─ component.dispatchEvent(createEditCustomEvent(editEvent))
       └─ [bubbles: true, composed: true]
            └─ EFWorkbench listener → agentPanel.addEdit(event)
                 └─ Map<editChangeKey, EditEvent> registry (deduplicates)
                      └─ groupEditsBySelector() → buildAgentPrompt() → copy button

EFWorkbench

registers

addEventListener('ef-edit', ...)

on itself — because

ef-edit

bubbles and is composed, any component in any slot (timeline, hierarchy, canvas) can dispatch it without special routing.

GUI交互（画布拖拽、检查器修改、裁剪拖拽、循环切换）
  └─ component.dispatchEvent(createEditCustomEvent(editEvent))
       └─ [bubbles: true, composed: true]
            └─ EFWorkbench 监听器 → agentPanel.addEdit(event)
                 └─ Map<editChangeKey, EditEvent> 注册表（去重）
                      └─ groupEditsBySelector() → buildAgentPrompt() → 复制按钮

EFWorkbench

在自身上注册

addEventListener('ef-edit', ...)

——由于

ef-edit

事件会冒泡且已合成，任何插槽（时间轴、层级结构、画布）中的组件都无需特殊路由即可派发该事件。

Key Types (

editEvents.ts

)

核心类型（

editEvents.ts

）

// EditEvent — what the panel accumulates
interface EditEvent {
  operation: EditOperation;
  description: string;   // human sentence
  selector: string;      // CSS path from composition root
  elementHtml: string;   // cleaned outerHTML snippet
  timestamp: number;
}

// Operation union — extend here when adding new interaction types
type EditOperation =
  | { type: "element-property-changed"; elementId; tagName; label; property; oldValue; newValue }
  | { type: "element-moved";   elementId; tagName; label; fromX; fromY; toX; toY }
  | { type: "element-resized"; elementId; tagName; label; x; y; width; height }
  | { type: "element-rotated"; elementId; tagName; label; rotation }

Registry key format — determines deduplication:

Property change:
```
selector::prop:propName
```

Move/resize/rotate:

selector::move

selector::resize

selector::rotate

// EditEvent — 面板累积的事件类型
interface EditEvent {
  operation: EditOperation;
  description: string;   // 自然语言描述
  selector: string;      // 从合成根节点出发的CSS路径
  elementHtml: string;   // 清理后的outerHTML片段
  timestamp: number;
}

// 操作类型联合 — 添加新交互类型时在此扩展
type EditOperation =
  | { type: "element-property-changed"; elementId; tagName; label; property; oldValue; newValue }
  | { type: "element-moved";   elementId; tagName; label; fromX; fromY; toX; toY }
  | { type: "element-resized"; elementId; tagName; label; x; y; width; height }
  | { type: "element-rotated"; elementId; tagName; label; rotation }

注册表键格式——用于判断去重规则：

属性变更：
```
selector::prop:propName
```

移动/缩放/旋转：

selector::move

selector::resize

selector::rotate

Pattern: Adding a New ef-edit Dispatch Point

模式：添加新的ef-edit派发点

import {
  createEditCustomEvent, buildSelectorPath, getElementHtml,
  buildEditDescription, type ElementPropertyChangedOperation,
} from "../../editEvents.js";

const oldValue = element.someProperty;
element.someProperty = newValue;

const op: ElementPropertyChangedOperation = {
  type: "element-property-changed",
  elementId: el.id,
  tagName: el.tagName.toLowerCase(),
  label: el.textContent?.trim().slice(0, 30) || el.id || el.tagName.toLowerCase(),
  property: "attr-name",   // attribute name as used in HTML source
  oldValue,
  newValue,
};
this.dispatchEvent(createEditCustomEvent({
  operation: op,
  description: buildEditDescription(op),
  selector: buildSelectorPath(el),
  elementHtml: getElementHtml(el),
  timestamp: Date.now(),
}));

buildPropertyEditEvent(element, property, oldValue, newValue)

EFInspector.ts

is a shorter form for simple property edits.

import {
  createEditCustomEvent, buildSelectorPath, getElementHtml,
  buildEditDescription, type ElementPropertyChangedOperation,
} from "../../editEvents.js";

const oldValue = element.someProperty;
element.someProperty = newValue;

const op: ElementPropertyChangedOperation = {
  type: "element-property-changed",
  elementId: el.id,
  tagName: el.tagName.toLowerCase(),
  label: el.textContent?.trim().slice(0, 30) || el.id || el.tagName.toLowerCase(),
  property: "attr-name",   // HTML源码中使用的属性名
  oldValue,
  newValue,
};
this.dispatchEvent(createEditCustomEvent({
  operation: op,
  description: buildEditDescription(op),
  selector: buildSelectorPath(el),
  elementHtml: getElementHtml(el),
  timestamp: Date.now(),
}));

EFInspector.ts

中的

buildPropertyEditEvent(element, property, oldValue, newValue)

是简单属性编辑的简化写法。

Finding Current Dispatch Points

查找现有派发点

bash

undefined

bash

undefined

Every call site that produces an ef-edit event

所有生成ef-edit事件的调用位置

rg 'createEditCustomEvent' elements/packages/elements/src/

Track subclasses that override render() — each must bind @trim-change-end

追踪重写render()的子类——每个都必须绑定@trim-change-end

rg 'override render' elements/packages/elements/src/gui/timeline/tracks/

Registered element schemas

已注册的元素Schema

rg 'SCHEMA_REGISTRY' elements/packages/elements/src/gui/elementPropertySchema.ts

undefined

rg 'SCHEMA_REGISTRY' elements/packages/elements/src/gui/elementPropertySchema.ts

undefined

What is NOT Wired (intentional)

未接入的功能（有意设计）

Playback controls (play/pause/seek), pan-zoom/zoom level, and toolbar settings are display-only state — they should not produce

ef-edit

events. Hierarchy reorder (

hierarchy-reorder

from

EFHierarchy

) would require a new

ElementReorderedOperation

type; not yet implemented.

播放控制（播放/暂停/跳转）、平移缩放/缩放级别、工具栏设置均为仅显示状态——它们不应生成

ef-edit

事件。层级重排序（来自

EFHierarchy

的

hierarchy-reorder

）需要新增

ElementReorderedOperation

类型，目前尚未实现。

Shadow DOM Event Routing Gotcha

Shadow DOM事件路由陷阱

trim-change-end

bubbles with

composed: true

from

EFTrimHandles

TrackItem.render()

binds

@trim-change-end

on the

ef-trim-handles

element. EFVideoTrack
overrides
render()
entirely and provides its own
ef-trim-handles
binding. Any future track subclass that overrides

render()

and includes

ef-trim-handles

must bind both

@trim-change

and

@trim-change-end

— the base

TrackItem.render()

handlers are not inherited when

render()

is overridden.

trim-change-end

事件从

EFTrimHandles

以

composed: true

的方式冒泡。

TrackItem.render()

在

ef-trim-handles

元素上绑定

@trim-change-end

。EFVideoTrack
完全重写了
render()
并提供了自己的
ef-trim-handles
绑定。任何未来重写

render()

且包含

ef-trim-handles

的轨道子类都必须同时绑定**

@trim-change

和

@trim-change-end

**——当

render()

被重写时，基类

TrackItem.render()

的处理器不会被继承。

Element Property Schema (

elementPropertySchema.ts

)

元素属性Schema（

elementPropertySchema.ts

）

Static descriptors drive the inspector UI. Register new element types at the bottom via

SCHEMA_REGISTRY

. Use the factory functions:

timeDescriptor(attr, label, opts)

— time values (stored as

${ms}ms

attributes)

enumDescriptor(attr, label, options, condition?)

```
boolDescriptor(attr, label, condition?)
```
```
numberDescriptor(attr, label, opts)
```
```
stringDescriptor(attr, label)
```

Elements with no registry entry are invisible to the inspector. Check

elementPropertySchema.test.ts

for the test pattern.

静态描述器驱动检查器UI。在文件底部通过

SCHEMA_REGISTRY

注册新元素类型，可使用以下工厂函数：

timeDescriptor(attr, label, opts)

— 时间值（存储为

${ms}ms

属性）

enumDescriptor(attr, label, options, condition?)

```
boolDescriptor(attr, label, condition?)
```
```
numberDescriptor(attr, label, opts)
```
```
stringDescriptor(attr, label)
```

没有注册表条目的元素对检查器不可见。可参考

elementPropertySchema.test.ts

中的测试模式。

Testing ef-edit Events

测试ef-edit事件

Unit tests (Node/vitest): use for

editEvents.ts

helpers —

editChangeKey

rollUpEdits

groupEditsBySelector

buildAgentPrompt

Browser tests (Chromium/vitest): required for any test involving DOM events or shadow DOM.

For trim ef-edit, dispatch

trim-change-end

directly on the

ef-trim-handles

host element — do not try to simulate full pointer events through shadow DOM layers, as pointer capture mechanics are unreliable in test environments:

const trimHandles = track.shadowRoot?.querySelector("ef-trim-handles");
trimHandles?.dispatchEvent(new CustomEvent("trim-change-end", {
  detail: { elementId: video.id, type: "start" },
  bubbles: true, composed: true,
}));

For loop ef-edit, click the loop button via

shadowRoot.querySelector("button[title='Loop']").click()

Listen at

document

level —

ef-edit

bubbles: true, composed: true

, so it propagates from any component to

document

单元测试（Node/vitest）：用于测试

editEvents.ts

中的辅助函数——

editChangeKey

、

rollUpEdits

、

groupEditsBySelector

、

buildAgentPrompt

。

浏览器测试（Chromium/vitest）：任何涉及DOM事件或Shadow DOM的测试都需要使用该方式。

对于裁剪ef-edit事件，直接在

ef-trim-handles

宿主元素上派发

trim-change-end

——不要尝试通过Shadow DOM层模拟完整的指针事件，因为测试环境中的指针捕获机制不可靠：

const trimHandles = track.shadowRoot?.querySelector("ef-trim-handles");
trimHandles?.dispatchEvent(new CustomEvent("trim-change-end", {
  detail: { elementId: video.id, type: "start" },
  bubbles: true, composed: true,
}));

对于循环ef-edit事件，通过

shadowRoot.querySelector("button[title='Loop']").click()

点击循环按钮。

在

document

级别监听——

ef-edit

事件的

bubbles: true, composed: true

，因此它会从任何组件传播到

document

。

ef-agent-panel

Original

Translation

Agent Panel

Agent Panel

Event Pipeline

事件流

Key Types (
`editEvents.ts`
)

核心类型（
`editEvents.ts`
）

Pattern: Adding a New ef-edit Dispatch Point

模式：添加新的ef-edit派发点

Finding Current Dispatch Points

查找现有派发点

Every call site that produces an ef-edit event

所有生成ef-edit事件的调用位置

Track subclasses that override render() — each must bind @trim-change-end

追踪重写render()的子类——每个都必须绑定@trim-change-end

Registered element schemas

已注册的元素Schema

What is NOT Wired (intentional)

未接入的功能（有意设计）

Shadow DOM Event Routing Gotcha

Shadow DOM事件路由陷阱

Element Property Schema (
`elementPropertySchema.ts`
)

元素属性Schema（
`elementPropertySchema.ts`
）

Testing ef-edit Events

测试ef-edit事件

ef-agent-panel

Original

Translation

Agent Panel

Agent Panel

Event Pipeline

事件流

Key Types (editEvents.ts)

核心类型（editEvents.ts）

Pattern: Adding a New ef-edit Dispatch Point

模式：添加新的ef-edit派发点

Finding Current Dispatch Points

查找现有派发点

Every call site that produces an ef-edit event

所有生成ef-edit事件的调用位置

Track subclasses that override render() — each must bind @trim-change-end

追踪重写render()的子类——每个都必须绑定@trim-change-end

Registered element schemas

已注册的元素Schema

What is NOT Wired (intentional)

未接入的功能（有意设计）

Shadow DOM Event Routing Gotcha

Shadow DOM事件路由陷阱

Element Property Schema (elementPropertySchema.ts)

元素属性Schema（elementPropertySchema.ts）

Testing ef-edit Events

测试ef-edit事件

Key Types (
`editEvents.ts`
)

核心类型（
`editEvents.ts`
）

Element Property Schema (
`elementPropertySchema.ts`
)

元素属性Schema（
`elementPropertySchema.ts`
）