com.wallstop-studios.dxmessaging 3.1.0 → 3.2.1

package/CHANGELOG.md

@@ -7,6 +7,332 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.2.1]
+
+### Changed
+
+- Removed the dead typed `MessageHandler.Handle*` callback methods and internalized the
+  three global callbacks still used by the message bus. These methods were nominally
+  public plumbing rather than supported registration APIs; bus dispatch and token
+  registration behavior are unchanged.
+- Refreshed the README banner (`docs/images/DxMessaging-banner.svg`): added
+  vertical separation between the tagline and the badge row, replaced the badges
+  with **Simple**, **MIT**, and the synced version, and re-drew the right panel
+  as one bus spine dispatching three aligned, color-coded message dots along
+  routes to labeled **Untargeted**, **Targeted**, and **Broadcast** destinations.
+- Simplified banner sync (`scripts/sync-banner-version.js`) to track only the
+  package version; the auto-derived test-count badge and its file-walking logic
+  were removed, along with the now-unneeded test-source triggers in the CI banner
+  gate and the pre-commit hook.
+
+### Added
+
+- Added a **Diagnostics Tooling Exerciser** sample scene that deterministically
+  drives Message Monitor, Flow Graph, Inspector diagnostics, and Project
+  Settings with untargeted, targeted, broadcast, exact-source broadcast,
+  broadcast-without-source, and `RegisterGlobalAcceptAll` routes.
+- Project Settings now exposes the **Ignored Base-Call Types** list under
+  Inspector Checks, so project-level base-call suppressions can be reviewed and
+  edited from the same settings page as the overlay toggles.
+- Flow Graph now includes visible trace-id lanes and visible trace route-kind
+  lanes over visible trace paths, reporting path-membership breadth or
+  route-kind delivery breadth plus message, target, and context details without
+  changing export schema v5.
+- Message Monitor now includes visible message-type and context lanes over the
+  current filter, reporting entry counts, distinct context/message breadth,
+  entry share, context lists, message lists, and row-level Filter shortcuts,
+  including exact quoted context shortcuts, without changing JSON export.
+- Message Monitor filtering now supports typed `type:`, `message:`,
+  `context:`, and `stack:` facets over captured entry fields while preserving
+  existing plain text matching, supports quoted typed values with spaces, and
+  displays the active typed or plain filter with a Clear action.
+
+## [3.2.0]
+
+### Added
+
+- Three per-kind **marginal registration** benchmark scenarios
+  (`UntargetedRegistration_Marginal`, `TargetedRegistration_Marginal`,
+  `BroadcastRegistration_Marginal`) that measure the GC-allocation cost of an additional
+  same-type registration on an already-warm bus -- the surface the registration
+  allocation reductions target -- so the published performance tables now show per-kind
+  registration cost (allocation count + bytes), not just dispatch throughput. Each
+  registers 1000 more handlers of one warmed message type using distinct, pre-built
+  handler delegates, so the measured window captures only the registration machinery
+  (never the handler delegate, and never a same-handler refcount bump). They are
+  wall-clock (zero-throughput) rows whose allocation columns populate on the
+  profiler-bearing in-editor PlayMode/Mono leg and read `n/a` on the published Standalone
+  IL2CPP Release leg (which strips the profiler), exactly like the existing
+  registration-flood rows.
+- Benchmarks now report the total allocated BYTES per measurement batch (`gcAllocatedBytes`)
+  alongside the existing managed-allocation CALL count (`gcAllocations`). Bytes are
+  measured from a before/after delta of the live Unity
+  `ProfilerRecorder(ProfilerCategory.Memory, "GC Allocated In Frame").CurrentValue`
+  -- a within-frame `GC.Alloc`-hook byte accumulator that SUMS allocation-hook bytes
+  rather than measuring a heap-size difference, so it is exact (verified: 100 x
+  `byte[10000]` reads 1,003,200 bytes, run-to-run identical) and immune to mid-window
+  collections (a heavy-churn region that swung a `GC.GetTotalMemory` delta to -133 MB
+  read a stable 8,000,000 bytes here). The byte counter is profiler-dependent
+  like the count probe: in the editor and development players it is functional, and on
+  the published non-development Standalone IL2CPP Release leg -- where the profiler is
+  stripped -- BOTH metrics report the `Unmeasured` sentinel (rendered `n/a`), never a
+  fabricated `0`. Bytes are INFORMATIONAL -- the perf-delta PR comment renders byte
+  deltas goodness-signed (`N fewer bytes` / `N more bytes`) -- while the regression gate
+  stays on the allocation COUNT, which remains the canonical signal (Unity's own
+  Performance Testing package likewise reads the alloc-CALL count, not bytes). The
+  cross-library comparison tables now also surface this byte metric as a dedicated
+  GC-allocated-bytes matrix, and the Unity `SendMessage` comparison boxes its value
+  payload on every dispatch (as any real `SendMessage(value)` call must) so its
+  allocation columns show that real per-call cost instead of a misleading zero. New API:
+  `AllocationProbe.MeasureWithBytes` returning `AllocationProbe.AllocationSample`,
+  `AllocationProbe.Window.SampleBytes()`/`SampleBoth()`,
+  `AllocationProbe.BytesFunctional`, `BenchmarkMeasurement.GcAllocatedBytes`,
+  `ColdLatencyMeasurement.MedianGcAllocatedBytes`, and
+  `MinimumMeasurement<T>.GcAllocatedBytes`.
+- New "What's New in 3.x" documentation page (Getting Started) that summarizes
+  the user-visible improvements across the 3.x line -- faster zero-allocation
+  dispatch, the base-call analyzer and inspector overlay, project-wide settings,
+  memory-reclamation controls, `ReregisterOnEnableAfterRelease`, the clarified
+  `ToggleMessageHandler` semantics, Unity 6.4+/6.5 compatibility, and the
+  dependency-injection helpers -- with links to the authoritative changelog and
+  the migration guide.
+
+### Fixed
+
+- The token-creation allocation guard no longer flakes in a warm editor. The
+  diagnostics-lazy win (token `Create` allocating 7 managed objects instead of 11) was
+  guarded by an absolute `GC.Alloc` recorder COUNT budget, but a warm, long-lived editor
+  domain attributes background allocations to whatever measurement window is open --
+  measured on the host editor, the minimum over 64 windows was ~19 allocations for that
+  7-allocation operation (median ~51), well above any budget tight enough to catch the
+  revert -- so the guard false-failed run-to-run. A measure-first probe also disproved the
+  assumption that the swing came from the `DxPools` collection pools: the steady refcount
+  registration path does not rent from them at all (hits = misses = 0), so the noise is
+  pure background-editor `GC.Alloc` pollution that no pool pre-warm can remove. The guard
+  is now a DETERMINISTIC state assertion -- after `Create` with diagnostics off, the lazy
+  `_callCounts`/`_emissionBuffer` backing fields must still be `null` -- which uses no
+  allocation probe, never flakes, and runs in the per-PR EditMode correctness leg rather
+  than the weekly perf-gated Allocation scope.
+- Two more memory-reclamation/registration allocation guards no longer flake in a warm
+  editor. The forced-trim guard measured a `GC.Alloc` COUNT budget over a 32-trim window
+  and the dirty-target reuse guard a per-batch count budget; both false-failed run-to-run
+  on the same warm-editor ambient-noise floor that the token-creation guard hit. The
+  forced-trim guard is now a DETERMINISTIC assertion on the exact `IMessageBus.TrimResult`
+  eviction counts (the first force-trim reclaims; every subsequent one is an idempotent
+  no-op that evicts nothing and leaves the live slot count stable) plus a `DxPools`
+  Misses-flat check (repeated no-op trims rent no fresh pooled collection); the
+  dirty-target guard now relies solely on its existing exact pool Hits/Misses assertions
+  (renting the warmed collection, never allocating a fresh one). Neither uses an allocation
+  probe, so neither flakes. The two deterministic registration STORAGE structural guards
+  (the by-value metadata parameter and the staging-function map value type) were also moved
+  from the weekly perf-gated Allocation suite into the per-PR EditMode correctness leg, so
+  they protect every PR. Internal test/quality change only; no public API or runtime
+  behavior change.
+- Benchmark and library-comparison allocation reporting is now honest. The harness
+  measured allocations with `GC.GetAllocatedBytesForCurrentThread()`, which returns
+  `0` for every allocation under Unity's Boehm GC (verified: a forced 1 MB array
+  allocation read back a `0`-byte delta), so the published "allocated bytes" column
+  was a vacuous `0` for every technology -- hiding real per-operation allocations
+  (Unity `SendMessage`, for example, boxes its value-type payload once per call).
+  The metric is now a COUNT of managed allocations from the reliable `GC.Alloc`
+  profiler recorder (new `AllocationProbe`), renamed `gcAllocations`, and reports an
+  `Unmeasured` sentinel (rendered `n/a`) -- never a fabricated `0` -- when no probe
+  is available on a backend. The perf-doc/PR-comment renderers, the regression gate,
+  and the methodology docs were updated accordingly; the doc's allocation column
+  reads `n/a` until the next CI run repopulates real counts.
+- Source generators (`[DxUntargetedMessage]`, `[DxTargetedMessage]`,
+  `[DxBroadcastMessage]`, `[DxAutoConstructor]`) now work in projects that do not use
+  assembly definitions. The generator and analyzer DLLs previously shipped under the
+  editor-only `Editor/Analyzers/` folder, which Unity scopes to the package's editor
+  assembly and assemblies that reference it -- so a consumer's runtime code in
+  `Assembly-CSharp` (or a runtime asmdef referencing only the runtime assembly) never
+  received the generator, and `[Dx*Message]` types failed to implement their generated
+  interface with cryptic `CS0315`/`CS0452` errors. The labeled DLLs now ship under
+  `Runtime/Analyzers/` (governed by the all-platforms runtime assembly), so Unity
+  applies the generator to the DxMessaging runtime assembly and every assembly that
+  references it, including the predefined `Assembly-CSharp`. No assembly definition is
+  required. Closes GitHub issue #229.
+- Documentation no longer teaches the obsolete `IMessageBus.GlobalDiagnosticsMode`
+  API. The reference, patterns, glossary, and migration guides now use
+  `IMessageBus.GlobalDiagnosticsTargets` with the `DiagnosticsTarget` flags enum
+  (matching the canonical diagnostics guide), and the API reference no longer shows a
+  write to the read-only `IMessageBus.DiagnosticsMode` property. A source-derived
+  drift-guard (`DocsObsoleteApiReferenceTests`) now fails the build if any published
+  doc references a member marked `[Obsolete]` in the runtime, so this cannot regress.
+
+### Changed
+
+- Registration now allocates one fewer managed object per handler in the common case. The
+  registration token stored every handle's de-registration in a per-handle holder object,
+  but the common case is EXACTLY ONE de-registration per handle, so the single
+  de-registration delegate is now stored INLINE in the token's de-registration map (with no
+  holder object); a holder is allocated only when a rare second de-registration accumulates
+  on the same handle (the re-entrant retarget-recovery replay). The ordering,
+  partial-failure, and rollback-baseline semantics are unchanged (pinned by the existing
+  `PendingDeregistrationStorageTests` and the full re-entrancy suite), and a new
+  `RegistrationStorageStructuralGuardTests.DeregistrationsStoreInlineActionNotPerHandleHolder`
+  deterministically guards the inline storage against regression. Internal change only; no
+  public API or behavior change.
+- **BREAKING (v4):** the `IMessageBus` registration contract now returns an opaque,
+  zero-allocation handle instead of a deregistration delegate. The 14
+  `IMessageBus.Register*<T>` methods return a new `readonly struct`
+  `DxMessaging.Core.MessageBus.MessageBusRegistration` (previously `System.Action`), and a
+  new `void IMessageBus.Deregister<T>(in MessageBusRegistration registration) where T : IMessage`
+  undoes a registration (call it with the same `T` you registered with; for
+  `RegisterGlobalAcceptAll`, any `T : IMessage` works since the global slot is not
+  type-keyed). This removes the per-registration bus-side deregistration **closure** (the
+  prior `Action` plus its display class) from the handler registration path -- roughly
+  **two fewer managed allocations per registration** -- by packing the deregistration
+  snapshot into the returned value handle and re-expressing the bus's deregistration logic
+  against it (behaviour and the four reentrancy invariants -- generation guard, identity
+  liveness / over-deregistration, token idempotency, no counter underflow -- are unchanged).
+  Custom `IMessageBus` implementers that wrap `MessageBus` (the
+  `DelegatingMessageBus`-style extension point) just forward the new members; from-scratch
+  implementers mint handles via the public `MessageBusRegistration(long, object)`
+  constructor and read them back in their own `Deregister<T>`.
+  **The Unity-facing surface is unaffected:** `MessageRegistrationToken` and
+  `MessageAwareComponent` keep their existing public shapes. The `MessageHandler.Register*`
+  facades were narrowed from `public` to `internal` (they now return the internal
+  `HandlerDeregistration`, still implicitly an `Action`) as part of this bus<->handler
+  boundary rework -- see the dedicated entry below; only code that called those facades
+  **directly** is affected. The larger per-registration allocation reduction (collapsing the
+  token/handler closures onto a single per-handle `Registration` object) landed on top of this
+  contract change -- see the entries below.
+- The published performance report no longer prints columns of `n/a`. The
+  Standalone IL2CPP leg runs in a Release player whose stripped profiler cannot
+  measure GC allocations or bytes, so the renderer now OMITS a memory column from a
+  per-scope dispatch table when every row is unmeasured (the Standalone table is
+  throughput-only), omits a whole cross-library memory matrix when no leg measured
+  that metric, and drops the unmeasured allocation/byte segment from each per-PR
+  delta cell -- instead of filling them with a wall of `n/a`. The real allocation
+  and byte numbers still publish from the in-editor PlayMode (Mono) leg, and `n/a`
+  now appears only as a genuine per-row or per-library cell (a metric measured for
+  the scope in general but missing for that one entry).
+- Registration allocates less. Each registration token's diagnostics-only
+  call-count and emission-history collections are now created lazily instead of
+  eagerly, so a token whose owner never enables diagnostics (the default) no longer
+  pays for them -- token creation drops from 11 to 7 managed allocations. The
+  per-registration metadata is now passed by value instead of through a closure
+  factory that was invoked immediately, removing one delegate allocation per handler
+  registration. Steady-state dispatch stays allocation-free, and diagnostics, the
+  inspector overlay, and all lifecycle behavior are unchanged.
+- Registering a handler OR a post-processor with the convenience `Action<T>` /
+  `Action<InstanceId, T>` overloads now allocates one fewer closure per registration.
+  This covers the handler registers (`RegisterUntargeted`, `RegisterTargeted`,
+  `RegisterTargetedWithoutTargeting`, the sourced-broadcast register, and
+  `RegisterBroadcastWithoutSource`) and the matching post-processor registers
+  (`RegisterTargetedPostProcessor`, `RegisterTargetedWithoutTargetingPostProcessor`, the
+  GameObject/Component/source broadcast post-processors, and
+  `RegisterBroadcastWithoutSourcePostProcessor`). Each such registration previously built
+  two delegates -- a diagnostics-augmented `Action` wrapper plus a separate by-ref
+  `FastHandler` adapter for the flat-dispatch path -- and now folds diagnostics into a
+  single by-ref `FastHandler` closure that is the dispatch target directly (also removing a
+  per-dispatch indirection). The public API is unchanged; the optimization is internal and
+  verified by differential allocation guards that pin the `Action` registration cost to the
+  already-optimal `FastHandler` registration cost. Diagnostics, deduplication, and dispatch
+  ordering are preserved.
+- Every registration kind now allocates about two fewer managed objects. The token used to
+  wrap each staged registration in a per-registration parameterless `Action` (a delegate plus
+  its display class) whose only job was to re-bundle the handle, the staging function, and the
+  de-registration bookkeeping; the token now stores each staging function directly and pairs it
+  with its handle in the replay queue, so that wrapper -- and the closure `InternalRegister`
+  needed to build it -- is gone. Measured cold-registration floor (FastHandler, diagnostics off):
+  untargeted drops from 14.69 to 12.69 managed allocations per registration (a clean -2.00), with
+  the same ~2-allocation reduction across targeted, broadcast, without-targeting/source, and
+  post-processor registrations (~12% fewer registration allocations overall). The de-registration
+  replay, rollback-on-failure, re-entrancy, and equal-priority registration-order semantics are
+  unchanged; the public API is unchanged. Pinned structurally by a deterministic guard that the
+  token stores the staging function (not an `Action` wrapper).
+- Every active registration now allocates about two fewer managed objects again. The token
+  tracked each handle's live de-registration in a per-handle holder that eagerly allocated a
+  `List` (plus its backing array) to hold what is almost always a single de-registration; the
+  holder now keeps that one de-registration inline and only allocates an overflow list on the
+  rare second de-registration for the same handle. Measured cold-registration floor (FastHandler,
+  diagnostics off): untargeted drops from 13.29 to 11.29 managed allocations per registration (a
+  clean -2.00), with the same ~2-allocation reduction across targeted and broadcast. The
+  insertion-order, partial-failure-retryable, and rollback-baseline de-registration semantics are
+  unchanged (verified by a differential simulation across every count/failure/start-index
+  combination); the public API is unchanged.
+- Each handler/post-processor registration now allocates one fewer managed object by replacing
+  its per-registration de-registration **closure** with a per-handle **object**. The typed
+  handler used to hand back a captured parameterless `Action` (a delegate plus the display class
+  holding the slot, cache key, priority, and generation it closed over) as the thing the token
+  would later invoke to tear the registration down; that closure is now a single per-handle
+  `HandlerDeregistration` object whose `Deregister()` instance method carries the same captured
+  state as plain fields (and converts implicitly to `Action`, so the token's replay/rollback
+  machinery is untouched). To let one non-generic object tear down a generic
+  `HandlerActionCache<TU>` without re-introducing a per-handler-delegate-type closure, the erased
+  `IHandlerActionCache` gained three non-generic operations (`ContainsEntry`, `BumpVersion`,
+  `DeregisterEntry`). The de-registration **order** (generation guard, slot-version liveness,
+  keyed-vs-scalar split, identity/over-de-registration check, version bump, bus de-register,
+  refcount decrement) is a faithful re-expression of the prior closure body, pinned by the 19
+  arbitrary-order `MixedOrderDeregistrationTests` and the full re-entrancy suite. Because these
+  `MessageHandler.Register*` facades now return the internal `HandlerDeregistration` (still
+  implicitly an `Action`), they were narrowed from `public` to `internal` -- this is part of the
+  v4 bus<->handler boundary rework and does NOT touch the Unity-facing surface
+  (`MessageRegistrationToken`, `MessageAwareComponent`); only code calling
+  `MessageHandler.Register*` **directly** is affected.
+- Every registration kind now allocates roughly half as many managed objects again by
+  collapsing the token's per-handle staging closures into one unified per-handle object.
+  Each registration previously staged a `Func<handle, HandlerDeregistration>` (a delegate plus
+  its display class capturing the target/source, user handler, and priority) whose nested
+  `AugmentedHandler` local function became a _second_ delegate (the diagnostics-augmented flat
+  invoker). Both are now a single per-handle `Registration` object stored in `_registrations`:
+  its fields hold the captured staging state, and its diagnostics-augmented invoker is an
+  _instance method_ bound to the object -- so `MessageHandler` still receives a `FastHandler<T>`
+  delegate and the hot dispatch path stays delegate-based (no virtual/interface call per
+  dispatch). A `Register()` method runs a kind-switch to call the matching
+  `MessageHandler.Register*` and reproduce the exact prior staging body per kind. Because the
+  constrained `MessageHandler.Register*<T>` calls require `T : ITargetedMessage` /
+  `IUntargetedMessage` / `IBroadcastMessage` (which a single `Registration<T> where T : IMessage`
+  cannot satisfy), the object is realized as three constraint-family generic subclasses plus one
+  non-generic global-accept-all subclass over a non-generic `Registration` base -- still a
+  unified per-handle object with a kind-switch, not a per-method subclass explosion. Measured
+  marginal cost (cold, FastHandler, diagnostics off) drops from ~9.3 to ~4.6 managed allocations
+  per registration (about half). The equal-priority registration-order dispatch, idempotent
+  double-deregister, partial-failure rollback, generation/slot-version guards, refcount handlers,
+  and diagnostics call-counts/emission semantics are all unchanged (pinned by the 19
+  `MixedOrderDeregistrationTests` and the full re-entrancy suite); the public API is unchanged.
+  Pinned structurally by a deterministic guard that `_registrations` stores the unified
+  `Registration` object, not a `Func`/`Action` wrapper.
+- Deregistration is now O(1) on the steady path. The v4 bus `Deregister<T>` had been
+  re-resolving the sink from the registration method (a `switch` plus `ScalarSinkForMethod` /
+  `ContextSinkForMethod`) and re-walking the whole sink -> type -> [context ->] priority ->
+  handler chain on every call -- even though the leaf handler-cache is already captured on the
+  registration handle. It now operates on that captured cache DIRECTLY, deferring the
+  re-resolution to a cold fallback taken only when the handler is not found there (the rare
+  post-sweep or over-deregistration case, which the fallback classifies as a silent no-op vs an
+  error). This removes the per-deregistration re-resolution that had regressed the
+  deregistration-heavy teardown path, with no change to dispatch, registration allocations, the
+  generation/sweep-staleness/over-deregistration guards, or the public API; the throw-safe
+  ordering (the handler-cache mutation stays after the throwing `IMessageBus.Deregister`) is
+  unchanged. A stale over-deregistration whose `(type, priority)` slot was reused by a different
+  handler now leaves the live registration completely untouched (new
+  `StaleOverDeregistrationTests` regression coverage). The token's de-registration store also
+  records the common first-registration in a single dictionary operation (`TryAdd`) instead of a
+  probe-then-insert pair.
+- The bug-report issue template now offers the package version as a dropdown of
+  released versions (with an `Other` fallback) instead of a free-text field, so
+  reports carry an exact, valid version. The list is generated from
+  `package.json`, `CHANGELOG.md`, and git tags, kept in sync by
+  `npm run check:issue-template-versions` (gated in `validate:all`), and
+  self-heals on the default branch via the `Update Issue Template Versions`
+  workflow. Closes GitHub issue #230.
+- The Roslyn source generator no longer copies its DLLs into the consumer's
+  `Assets/Plugins/Editor/` folder on editor load; it (with its pinned Roslyn dependency
+  DLLs) ships ready-to-use under the package's `Runtime/Analyzers/` folder
+  (RoslynAnalyzer-labeled, excluded from player builds). Projects upgrading from an
+  earlier version have the redundant in-project copy removed automatically during asset
+  import, before script compilation, so the package's copy and the old in-project copy
+  never both run the generator (which would otherwise duplicate generated members). No
+  manual action is required: the cleanup only removes the
+  `Assets/Plugins/Editor/WallstopStudios.DxMessaging` folder when it contains the
+  first-party source-generator DLL plus exact known legacy analyzer/dependency DLL names
+  the package created, and leaves any foreign DLL, foreign `.meta`, subfolder, or
+  other content untouched. If a mixed or incomplete legacy payload is detected, the
+  editor logs one warning with manual cleanup guidance instead of deleting the folder
+  silently.
+
 ## [3.1.0]
 
 ### Added

package/Editor/Analyzers/BaseCallLogMessageParser.cs.meta

@@ -6,6 +6,6 @@ MonoImporter:
   defaultReferences: []
   executionOrder: 0
   icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Editor/Analyzers/BaseCallReportAggregator.cs.meta

@@ -6,6 +6,6 @@ MonoImporter:
   defaultReferences: []
   executionOrder: 0
   icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Editor/Analyzers/DxMessagingConsoleHarvester.cs

@@ -84,13 +84,13 @@ namespace DxMessaging.Editor.Analyzers
     /// </para>
     /// <para>
     /// The inspector overlay reads its snapshot from the unified per-FQN map populated here on
-    /// every rescan. Use the menu <c>Tools > DxMessaging > Rescan Base-Call Warnings</c> for a
+    /// every rescan. Use the menu <c>Tools > Wallstop Studios > DxMessaging > Rescan Base-Call Warnings</c> for a
     /// manual force-rescan.
     /// </para>
     /// <para>
     /// <see cref="IsAvailable"/> stays <c>true</c> as long as the static constructor itself does
     /// not throw -- the IL scanner is always wired, so the overlay never falls back to its
-    /// degraded "harvester unavailable" HelpBox in normal operation. <see cref="LogEntriesAvailable"/>
+    /// degraded "harvester unavailable" warning surface in normal operation. <see cref="LogEntriesAvailable"/>
     /// continues to report whether the legacy reflection layer is bindable, for diagnostics only.
     /// </para>
     /// </remarks>
@@ -187,7 +187,7 @@ namespace DxMessaging.Editor.Analyzers
         // or whether it was loaded eagerly from `Library/DxMessaging/baseCallReport.json` in the
         // static ctor and has not yet been overwritten. The inspector overlay reads this to
         // distinguish "fresh-this-session" warnings from cached-from-previous-session warnings;
-        // when the cache is showing, we annotate the HelpBox with a small suffix so the user
+        // when the cache is showing, we annotate the warning surface so the user
         // understands the data may be stale until the first post-reload scan completes.
         //
         // Default `false`: the static ctor's `LoadFromDisk` runs first, so by the time anything
@@ -241,7 +241,7 @@ namespace DxMessaging.Editor.Analyzers
         /// constructor itself throws (a hard initialization failure). The LogEntries reflection
         /// layer is the optional source -- see <see cref="LogEntriesAvailable"/> for that flag.
         /// The inspector overlay reads this property to decide whether to render its degraded
-        /// HelpBox, so the contract here is "should the overlay attempt to render at all".
+        /// warning surface, so the contract here is "should the overlay attempt to render at all".
         /// </remarks>
         public static bool IsAvailable { get; private set; } = true;
 
@@ -259,11 +259,11 @@ namespace DxMessaging.Editor.Analyzers
         /// loaded eagerly by the static constructor.
         /// </summary>
         /// <remarks>
-        /// The inspector overlay reads this to annotate its HelpBox: when <c>false</c> AND a
-        /// warning is being shown, the overlay appends a "(cached from previous session --
-        /// refreshing...)" suffix so the user knows the data is from yesterday's scan and a fresh
+        /// The inspector overlay reads this to annotate its warning surface: when <c>false</c> AND a
+        /// warning is being shown, the overlay adds a "Report is cached from previous session;
+        /// refreshing..." note so the user knows the data is from yesterday's scan and a fresh
         /// one is in flight. The flag is set inside <see cref="RescanNow"/> and never reset, so
-        /// the suffix disappears as soon as the first post-reload scan lands and stays gone for
+        /// the note disappears as soon as the first post-reload scan lands and stays gone for
         /// the rest of the session.
         /// </remarks>
         public static bool IsFreshThisSession => _isFreshThisSession;

package/Editor/Analyzers/DxMessagingConsoleHarvester.cs.meta

@@ -6,6 +6,6 @@ MonoImporter:
   defaultReferences: []
   executionOrder: 0
   icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Editor/CustomEditors/MessageAwareComponentFallbackEditor.cs

@@ -1,14 +1,17 @@
 namespace DxMessaging.Editor.CustomEditors
 {
 #if UNITY_EDITOR
+    using System;
+    using DxMessaging.Editor.Analyzers;
     using DxMessaging.Unity;
     using UnityEditor;
+    using UnityEditor.UIElements;
+    using UnityEngine.UIElements;
 
     /// <summary>
-    /// Primary CustomEditor for every <see cref="MessageAwareComponent"/> subclass. Renders the
-    /// DxMessaging warning HelpBox above an inspector body that is byte-for-byte identical to
-    /// Unity's default <c>GenericInspector</c> (achieved via
-    /// <see cref="Editor.DrawDefaultInspector"/>).
+    /// Primary CustomEditor for every <see cref="MessageAwareComponent"/> subclass. Hosts the
+    /// DxMessaging warning above a default inspector body that keeps Unity's serialized field
+    /// surface intact.
     /// </summary>
     /// <remarks>
     /// We register as a non-fallback (primary) editor with
@@ -33,20 +36,20 @@ namespace DxMessaging.Editor.CustomEditors
     /// </list>
     ///
     /// <para>
-    /// The current design is the simple one: be the primary editor, prepend the overlay's
-    /// HelpBox via <see cref="MessageAwareComponentInspectorOverlay.RenderInsideOnInspectorGUI"/>,
-    /// then call <see cref="Editor.DrawDefaultInspector"/>. The body therefore matches
-    /// <c>GenericInspector</c> exactly: no missing Script row, no extra vertical gap. To avoid
-    /// double-rendering when the header hook ALSO fires for our editor instance (Unity 2022+),
+    /// The current primary path is <see cref="CreateInspectorGUI"/>: it hosts the UI Toolkit
+    /// warning view, then fills Unity's default Inspector body through
+    /// <see cref="InspectorElement.FillDefaultInspector"/> so the disabled Script row and
+    /// serialized fields remain present. To avoid double-rendering when the header hook ALSO
+    /// fires for our editor instance (Unity 2022+),
     /// <see cref="MessageAwareComponentInspectorOverlay"/> unconditionally skips the header path
     /// for <see cref="MessageAwareComponentFallbackEditor"/> instances.
     /// </para>
     ///
     /// <para>
-    /// We do NOT short-circuit <see cref="OnInspectorGUI"/> on event type. Unity invokes
-    /// editors twice per frame (Layout + Repaint), and both passes MUST emit identical control
-    /// counts, otherwise the inspector window's layout cache is corrupted and adjacent
-    /// components fail to render. See
+    /// <see cref="OnInspectorGUI"/> remains as an IMGUI compatibility fallback. We do NOT
+    /// short-circuit it on event type. Unity invokes editors twice per frame (Layout + Repaint),
+    /// and both passes MUST emit identical control counts, otherwise the inspector window's layout
+    /// cache is corrupted and adjacent components fail to render. See
     /// <see cref="MessageAwareComponentInspectorOverlay.RenderInsideOnInspectorGUI"/> for the
     /// matching invariant on the overlay side.
     /// </para>
@@ -63,6 +66,23 @@ namespace DxMessaging.Editor.CustomEditors
     [CanEditMultipleObjects]
     public sealed class MessageAwareComponentFallbackEditor : Editor
     {
+        internal const string RootName = "dxmessaging-fallback-inspector";
+        internal const string RootClassName = "dxmessaging-fallback-inspector";
+        internal const string WarningHostName = "dxmessaging-fallback-inspector-warning-host";
+        internal const string WarningHostClassName = "dxmessaging-fallback-inspector-warning-host";
+        internal const string DefaultInspectorBodyName =
+            "dxmessaging-fallback-inspector-default-body";
+        internal const string DefaultInspectorBodyClassName =
+            "dxmessaging-fallback-inspector-default-body";
+
+        public override VisualElement CreateInspectorGUI()
+        {
+            return BuildInspectorGUI(
+                this,
+                () => MessageAwareComponentInspectorOverlay.ResolveInspectorState(target)
+            );
+        }
+
         public override void OnInspectorGUI()
         {
             // Render the overlay BEFORE the default body so the warning appears prominently at
@@ -76,6 +96,144 @@ namespace DxMessaging.Editor.CustomEditors
             // [SerializeField] fields.
             DrawDefaultInspector();
         }
+
+        internal static VisualElement BuildInspectorGUI(
+            Editor editor,
+            Func<MessageAwareComponentInspectorState> resolveState
+        )
+        {
+            if (editor == null)
+            {
+                throw new ArgumentNullException(nameof(editor));
+            }
+            if (resolveState == null)
+            {
+                throw new ArgumentNullException(nameof(resolveState));
+            }
+
+            VisualElement root = new() { name = RootName };
+            DxMessagingEditorTheme.Apply(root);
+            root.AddToClassList(RootClassName);
+
+            VisualElement warningHost = new() { name = WarningHostName };
+            warningHost.AddToClassList(WarningHostClassName);
+            root.Add(warningHost);
+
+            InspectorWarningBinding binding = new(warningHost, resolveState);
+            root.userData = binding;
+            binding.Refresh();
+
+            VisualElement defaultBody = new() { name = DefaultInspectorBodyName };
+            defaultBody.AddToClassList(DefaultInspectorBodyClassName);
+            InspectorElement.FillDefaultInspector(defaultBody, editor.serializedObject, editor);
+            root.Add(defaultBody);
+
+            root.RegisterCallback<AttachToPanelEvent>(_ => binding.Connect());
+            root.RegisterCallback<DetachFromPanelEvent>(_ => binding.Disconnect());
+
+            return root;
+        }
+
+        internal static void RefreshInspectorWarning(VisualElement root)
+        {
+            if (root == null)
+            {
+                throw new ArgumentNullException(nameof(root));
+            }
+            if (root.userData is not InspectorWarningBinding binding)
+            {
+                throw new InvalidOperationException(
+                    "Fallback inspector root is missing its warning binding."
+                );
+            }
+
+            binding.Refresh();
+        }
+
+        private sealed class InspectorWarningBinding
+        {
+            private readonly VisualElement _warningHost;
+            private readonly Func<MessageAwareComponentInspectorState> _resolveState;
+            private bool _connected;
+            private bool _refreshRetryScheduled;
+
+            internal InspectorWarningBinding(
+                VisualElement warningHost,
+                Func<MessageAwareComponentInspectorState> resolveState
+            )
+            {
+                _warningHost = warningHost ?? throw new ArgumentNullException(nameof(warningHost));
+                _resolveState =
+                    resolveState ?? throw new ArgumentNullException(nameof(resolveState));
+            }
+
+            internal void Connect()
+            {
+                if (_connected)
+                {
+                    return;
+                }
+
+                DxMessagingConsoleHarvester.ReportUpdated += Refresh;
+                MessageAwareComponentInspectorOverlay.InspectorStateInvalidated += Refresh;
+                _connected = true;
+                Refresh();
+            }
+
+            internal void Disconnect()
+            {
+                if (!_connected)
+                {
+                    return;
+                }
+
+                DxMessagingConsoleHarvester.ReportUpdated -= Refresh;
+                MessageAwareComponentInspectorOverlay.InspectorStateInvalidated -= Refresh;
+                _connected = false;
+            }
+
+            internal void Refresh()
+            {
+                MessageAwareComponentInspectorState state = _resolveState();
+                if (state.Kind == MessageAwareComponentInspectorStateKind.None)
+                {
+                    if (
+                        MessageAwareComponentInspectorOverlay.IsInspectorResolutionTransientlyBlocked()
+                    )
+                    {
+                        ScheduleRefreshRetry();
+                        return;
+                    }
+
+                    _warningHost.Clear();
+                    _warningHost.style.display = DisplayStyle.None;
+                    return;
+                }
+
+                _refreshRetryScheduled = false;
+                _warningHost.Clear();
+                _warningHost.style.display = DisplayStyle.Flex;
+                _warningHost.Add(MessageAwareComponentInspectorOverlay.CreateInspectorView(state));
+            }
+
+            private void ScheduleRefreshRetry()
+            {
+                if (_refreshRetryScheduled)
+                {
+                    return;
+                }
+
+                _refreshRetryScheduled = true;
+                System.Action<System.Action> schedule =
+                    MessageAwareComponentInspectorOverlay.TransientRefreshScheduler
+                    ?? DxMessagingEditorIdle.ScheduleAssetDatabaseMutation;
+                schedule(() =>
+                {
+                    _refreshRetryScheduled = false;
+                    Refresh();
+                });
+            }
+        }
     }
 #endif
 }

package/Editor/CustomEditors/MessageAwareComponentFallbackEditor.cs.meta

@@ -6,6 +6,6 @@ MonoImporter:
   defaultReferences: []
   executionOrder: 0
   icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+  userData:
+  assetBundleName:
+  assetBundleVariant: