[facontidavide]

Three small changes, each of which needs a 2.0 once 1.0.0 is tagged.

1. timestamp_ns on every builtin struct (source break)

Four builtin structs named their timestamp member timestamp; the other sixteen use timestamp_ns.

Struct	Before	After
sdk::ImageAnnotations	timestamp	timestamp_ns
sdk::FrameTransform	timestamp	timestamp_ns
sdk::SceneEntity	timestamp	timestamp_ns
sdk::SceneEntityDeletion	timestamp	timestamp_ns

The field-table name changes with the member, so a script reads timestamp_ns on these types too. The wire format is unchanged: the proto field is still timestamp.

Consumers: PlotJuggler and pj-official-plugins must rename their uses when they move to the next SDK pre-release. User scripts that read .timestamp on these four types must change as well.

2. Dialog tree events tolerate other top-level keys

DialogPluginTyped dispatched a tree event only when its key was the sole top-level key of the event. That check is compiled into each plugin, so a later host could never have added a key to the envelope without every existing plugin dropping the event.

Now a valid tree key claims the event and other keys are ignored, which is already the rule beside a file-picker result. Two tree keys, or a malformed tree payload, still fail closed. No host emits tree events yet, so nothing running changes.

docs/dialog-sdk-reference.md rule 3 is updated to match.

3. PJ_widget_value_t names its padding

The 4 bytes of alignment padding after kind become uint32_t flags. No bit is defined. Size (96), alignment (8) and every offset are unchanged, and the layout sentinels now pin flags at offset 12.

A host built against 1.0 or later writes 0. A host built earlier leaves those bytes unset, and the header says so: a widget may read a bit only once a later SDK defines one together with a way to tell that the host sets it.

Verification

• ./build.sh --debug && ./test.sh: 107/107 under ASAN. Pre-commit clean. check_feature_floors.py passes (158 surfaces).
• The two new tree-dispatch tests replace a test that asserted the opposite result on the same payload; I did not separately run them against the old code.
• Not run: ./test_sdk_install.sh (no packaging change).

🤖 Generated with Claude Code