auto_logger

Documentation: Added AutoLogger.addSystemUIChangeHandler() to developer documentation and AI guide — public API for chaining custom SystemChrome.setSystemUIChangeCallback handlers alongside auto_logger's logging, was only documented in source code docstring

Fixed: SafeDisposalMixin.safeSetState() had redundant async keyword — returned Future<void> instead of void, adding unnecessary microtask scheduling overhead on every call. Changed from Future<void> safeSetState(VoidCallback fn) async to void safeSetState(VoidCallback fn).

Documentation: Added metadata field names to AI guide startup events — BINDING_MODE (existingBinding, mode, limitedFeatures), DEBUG_MODE (debug, profile, release), PLATFORM_INFO (os, osVersion, dartVersion, locale)

Documentation: Added specific changed-field names to AI guide ACCESSIBILITY event — now lists all 7 diffed properties (accessibleNavigation, invertColors, disableAnimations, boldText, reduceMotion, highContrast, onOffSwitchLabels)

Documentation: Added metadata field names to AI guide platform channel events — PLATFORM_SEND (channel, direction), PLATFORM_RECEIVE (channel, direction), PLATFORM_PLATFORM (channel, direction)

Documentation: Added INSERT and UPDATE/DELETE SQL metadata JSON examples to parsing guide Section 6 — only SELECT was shown, but insertId (INSERT) and rowsAffected (UPDATE/DELETE) have different metadata shapes

Fixed: _getSourceLocation() in zone_config.dart was missing package:talker/ URI filter — SLOW_CALLBACK sourceLocation could point to a Talker frame instead of user code. _extractFiles() and _fingerprint() in the same file already had the filter; now consistent.

Fixed: SSL_CERT_REJECTED logged via logger.problem() without structured metadata — host and port were only in the message string. Now includes metadata: {'host': host, 'port': port} for programmatic parsing.

Fixed: GrpcLoggingHelper.onRequest() and .onResponse() called request?.toString() / response?.toString() twice — once for .length, once for the value. gRPC protobuf toString() can be expensive. Now cached in local variable.

Documentation: Fixed Image Cache metadata JSON example in parsing guide — was combining fields from 7 different IMAGE_CACHE events into one misleading block; now split into per-event examples (same pattern as SharedPreferences and Hive fixes)

Fixed: SafeDisposalMixin.dispose() resource disposal crash — if any tracked resource's .dispose() threw an exception (e.g., already-disposed AnimationController), all subsequent disposals AND super.dispose() were skipped, causing cascading leaks. Each .dispose() now wrapped in try-catch.

Fixed: LoggingAssetBundle.evict() only called super.evict(key) (CachingAssetBundle's cache) but not _inner.evict(key) — inner bundle's cache was never cleared, causing stale assets to persist after eviction

Fixed: Root/jailbreak detection File(path).exists() could throw on sandboxed paths (iOS/Android filesystem permission errors) — now wrapped in try-catch to prevent init failure

Fixed: Email validation RegExp was recreated on every Validate.email() call — now cached as static final (13-15x faster in AOT per Dart SDK #42366)

Fixed: SQL error logging called error.toString() twice in message construction — now cached in local variable

Documentation: Fixed SharedPreferences metadata in parsing guide — was combining fields from different events (length from SET_STRING, found from GET_STRING) into one generic example; now split into per-event metadata examples matching actual code output

Fixed: StackTrace.current.toString() was called eagerly on every loadingMonitor.track() and withTimeout() invocation — now stores StackTrace as object (cheap) and only stringifies when stuck/timeout event actually fires (loading_monitor.dart, safe_api.dart)

Fixed: _getSourceLocation() in logger.dart was missing package:talker/ URI filter — could report a Talker frame as source location. _getSourceLocationFromStack() already had the filter; now consistent.

Enhanced: didChangeAccessibilityFeatures() now diffs previous vs current AccessibilityFeatures state and logs which properties changed (was logging empty metadata) (lifecycle_observer.dart)

Documentation: Added optional invalidValue parameter to Validate.isTrue example in developer documentation

Fixed: FILE_READ_LINES async now includes ms timing metadata — was the only async file read operation missing duration measurement (io_overrides.dart)

Fixed: FILE_WRITE_BYTES and FILE_WRITE_BYTES_SYNC now include mode metadata — writeAsString logged write mode but writeAsBytes did not (io_overrides.dart)

Fixed: SystemChrome.setSystemUIChangeCallback now chains to user callbacks via addSystemUIChangeHandler() — was silently replacing any existing callback (system_monitor.dart)

Fixed: Cached RegExp in pointer event handler as file-level final — was creating new RegExp on every pointer event, expensive in AOT mode (flutter_init.dart)

Documentation: Fixed Hive metadata JSON example in parsing guide — was mixing fields from 3 different events and using found when HIVE_CONTAINS uses exists; now split into per-event examples

Documentation: Fixed jq commands in parsing guide — added sed 's/.*| //' to extract metadata JSON before piping to jq (log lines are not raw JSON)

Documentation: Updated FILE_READ_LINES metadata in parsing guide to include ms field

Documentation: Updated FILE_WRITE_BYTES metadata in parsing guide to include mode field

Documentation: Added TL;DR summary to Binding Initialization Order section in developer documentation and AI guide

Documentation: Added performance config defaults summary line to Flutter-Only Performance Config section in developer documentation

Documentation: Expanded README "What's Logged Automatically" table — added scroll & layout, keyboard & focus, asset loading, image cache, Drift SQL, WebSocket, gRPC, lifecycle & accessibility rows

Documentation: Added [Flutter only] markers to parsing guide sections 4.3 (Performance), 4.3.1 (Scroll & Layout), 4.3.2 (Pointer & Input), 4.4 (Memory), 4.5 (Platform Channels), 4.8 (Lifecycle)

Documentation: Added Timer/Periodic metadata JSON examples to parsing guide Section 6 — TIMER_CREATE/FIRE and PERIODIC_CREATE/FIRE metadata fields were documented in text but had no JSON examples

Documentation: Strengthened SafeDisposalMixin LEAK explanation in developer documentation — clarifies that mixin checks tracked resources at dispose time and logs LEAK with full debugging context

Documentation: Condensed AI guide Flutter-only configuration section — reduced verbose multi-line comments to single-line format with defaults

Documentation: Completed exception field documentation — added AppException base class shared fields (code, context, originalError, originalStackTrace), ParseException.expectedFormat parameter, and per-exception field summary to developer documentation, AI guide, and README

Fixed: DartAutoLogger.initDart() in auto_logger package was missing loadingMonitor.startMonitoring() call — STUCK_OPERATION detection never activated when using the pure Dart entry point (DartAutoLogger.initDart()/DartAutoLogger.runDart()). The dart_auto_logger package had this fix (fix #92) but it was not applied to auto_logger's duplicate DartAutoLogger class. Now matches dart_auto_logger behavior.

Fixed: Hash function cross-platform inconsistency — hash &= 0xFFFFFFFF produced signed 32-bit values on web (JavaScript) but unsigned on native, causing different fingerprints for the same error across platforms. Changed to hash &= 0x3FFFFFFF (30-bit, always positive on all platforms). Affects logger.dart, zone_config.dart, user_trail.dart.

Fixed: LoadingMonitor.track() same-name collision — concurrent operations with identical names (e.g., two simultaneous track('fetchUser', ...) calls) would overwrite each other's tracking entry. Now uses counter-based unique key '$operation #${_opCounter++}' (same pattern as drift fix, Dio fix, and HTTP fix).

Fixed: WebSocket sink created new LoggingWebSocketSink wrapper on every .sink access — now lazy-cached for identity consistency and reduced allocations.

Fixed: json.encode(metadata) in logger.log() could throw on non-serializable metadata objects, crashing the log call. Now wrapped in try-catch with fallback to metadata.toString().

Fixed: getRouteStack and getStateSnapshot callback crashes during error logging could lose the entire crash/problem/stuck report. Now wrapped in try-catch in all 16 metadata collection sites across core files (_getContext(), _checkStuck(), track() finally, _logSlowCallbackIfNotDuplicate(), safe_api.dart, drift_interceptor.dart) and Flutter files (disposal_mixin.dart, lifecycle_observer.dart, system_monitor.dart, performance_monitor.dart, flutter_init.dart).

Documentation: Fixed unverifiable ~80-90ns zone overhead claim in developer documentation — replaced with defensible "negligible overhead" wording citing Sentry, Firebase, and Flutter all using zones in production

Documentation: Added swipeEdge type clarification to BACK_GESTURE_START metadata in parsing guide and AI guide — value is integer enum index (0=left, 1=right), not a string

Documentation: Fixed parsing guide originalError metadata claim for API_FAILED — logger.problem() produces errorType and errorMessage, not originalError (which only exists on the thrown NetworkException object, not in log metadata)

Documentation: Added AutoLogger.addPlatformErrorHandler() to developer documentation and AI guide — was only documented in source code docstring. Chains a custom PlatformDispatcher.onError handler after AutoLogger's logging.

Documentation: Added runWithLogging() and runWithLoggingAsync() to developer documentation and AI guide — exported public API for running code in a logging zone outside AutoLogger.run(), useful for isolated work

Documentation: Added note about default minLevel: WARN filtering to README — most automatic events are DEBUG level and invisible with default settings, which was not prominently communicated

Fixed: Pointer event logging (hitTestInView + regex) ran on every pointer event even when debug logging was disabled (minLevel defaults to WARN). Now skips expensive hit testing when minLevel > DEBUG, while still recording TAP to user trail for crash context.

Fixed: StackTrace.current.toString() ran on every memory allocation event before log level check. Now skips when minLevel > DEBUG (allocation events are debug-only anyway).

Fixed: Freeze detection timer (100ms periodic) continued firing when app was backgrounded. Now pauses on AppLifecycleState.paused and resumes on resumed, saving CPU on Android where OS doesn't reliably pause timers.

Documentation: Added LoggingAssetBundle section to developer documentation — asset bundle logging is automatic via AutoLogger.run() but was undocumented. Documents all 8 asset events and custom bundle usage.

Documentation: Added Performance Notes section to developer documentation — documents zero-overhead in release builds, debug-only memory tracking, log level gating, freeze timer lifecycle, and zone callback overhead.

Documentation: Fixed SQL Metadata in parsing guide — field name was affected but code uses rowsAffected for UPDATE/DELETE results; args example was "[1]" (string) but code produces ["1"] (list)

Documentation: Fixed File Metadata sync variant descriptions in parsing guide — _SYNC variants do not include ms (sync operations are not timed); FILE_WRITE_SYNC also includes mode (was only documented for FILE_WRITE)

Documentation: Fixed File Metadata example in parsing guide — was showing "bytes" but string operations (FILE_READ, FILE_WRITE) use "chars", byte operations (FILE_READ_BYTES, FILE_WRITE_BYTES) use "bytes", and line operations (FILE_READ_LINES) use "lines". FILE_WRITE also has undocumented "mode" field. Now shows separate examples per operation variant.

Documentation: Added Socket Metadata section to parsing guide Section 6 — documents host/address, port, ms fields for SOCKET_CONNECTED, SOCKET_CONNECT_ERROR, SERVER_BIND, SERVER_BOUND, SERVER_BIND_ERROR events (were emitted in code but not documented in metadata reference)

Fixed: HTTP request tracking collision — pendingHttpRequests used '$method $url' as map key, causing concurrent identical requests (e.g., two simultaneous GET https://api.example.com/users) to overwrite each other's tracking entry. Now uses unique counter suffix #${_httpRequestCounter++} (same pattern as drift fix #22 and Dio fix #23)

Documentation: Added missing file/directory event variants to AI guide — FILE_READ_BYTES, FILE_WRITE_BYTES, FILE_READ_LINES, LINK_CREATE, and all _SYNC counterparts (12 file sync + 5 directory sync variants) were in code and parsing guide but missing from AI guide event listings

Documentation: Added 3 missing ASSET_LOAD_FAILED, ASSET_STRING_FAILED, ASSET_STRUCTURED_FAILED error events to AI guide Asset events listing

Documentation: Added Image cache events section to AI guide — 8 events (IMAGE_CACHE_HIT, IMAGE_CACHE_MISS, IMAGE_EVICT, IMAGE_LOAD_FAILED, IMAGE_CACHE_CLEAR, IMAGE_CACHE_RESIZE, IMAGE_CACHE_RESIZE_BYTES, IMAGE_CACHE_CLEAR_LIVE) had no dedicated listing

Documentation: Added Platform channel events section to AI guide — PLATFORM_SEND, PLATFORM_RECEIVE, PLATFORM_PLATFORM had no dedicated listing

Documentation: Added BINDING_MODE to AI guide Startup events and PERF_MONITOR_INIT to Performance events — both were in parsing guide but missing from AI guide

Documentation: Removed phantom PLATFORM_VIEW_CREATE and PLATFORM_VIEW_DISPOSE events from parsing guide Section 4.5 — PlatformViewsService handler was removed (fix #52, invasive setMessageHandler replaces existing handler) but these events were still documented; renumbered Platform Channels to Section 4.5

Documentation: Fixed LoggingDioInterceptor code docstring in integrations.dart — was showing dio.interceptors.add(LoggingDioInterceptor()) which would not compile because LoggingDioInterceptor does not extend Dio's Interceptor class; now shows correct InterceptorsWrapper pattern matching all user-facing docs

Documentation: Added FRAME_SLOW event to AI guide Performance events listing — was present in parsing guide but missing from AI guide (frame > 16ms, logged at DEBUG level)

Documentation: Removed phantom DIR_TEMP event from AI guide File/Directory event listings — createTemp/createTempSync delegate without logging and DIR_TEMP was never emitted

Documentation: Fixed navigation metadata description in parsing guide — was "All navigation events include route, type, and stack" but only PUSH/POP/REMOVE/SWIPE_START have all three; REPLACE has old/new/stack, SWIPE_END has only stack, SYSTEM_POP has none, SYSTEM_PUSH has uri, BACK_GESTURE_START has progress/swipeEdge, ROUTE_NOT_FOUND has route/args

Added: didRequestAppExit() lifecycle callback — logs REQUEST_APP_EXIT when system requests app termination (macOS/Linux)

Added: handleStartBackGesture() lifecycle callback — logs BACK_GESTURE_START with progress/swipeEdge for Android 14 predictive back (returns false to avoid intercepting)

Added: fseGetTypeSync() override in IOOverrides — logs FSE_TYPE_SYNC (sync version of existing FSE_TYPE)

Added: Socket connection logging via IOOverrides — socketConnect (SOCKET_CONNECT_START/SOCKET_CONNECTED/SOCKET_CONNECT_ERROR), socketStartConnect (SOCKET_START_CONNECT), serverSocketBind (SERVER_BIND/SERVER_BOUND/SERVER_BIND_ERROR)

Added: FrameTiming metadata enrichment — FRAME_DROP, FRAME_SEVERE_DROP, SHADER_JANK events now include vsyncOverheadUs, frameNumber, layerCacheCount, layerCacheBytes, pictureCacheCount, pictureCacheBytes (cache metrics report 0 on web)

Fixed: UI_JANK false positive when browser tab is backgrounded - browsers throttle Timer.periodic (to 1/sec or 1/min) in background tabs, preventing idle detection from resetting _previousFrameRasterFinishUs. Now _trackCumulativeJank includes sanity check: gaps larger than jankWindowMs (12.5s) are skipped and state is reset, since real freezes that long are caught by UI_FREEZE (5s threshold) anyway.

Fixed: Flutter version constraint changed from >=3.0.0 to >=3.22.0 - FlutterMemoryAllocations API requires Flutter 3.22.0+ (introduced May 2024)

Added: Configurable gRPC slow threshold via autoLoggerConfig.grpcSlowThresholdMs (default: 1000ms) - gRPC calls slower than this are logged at WARN level

Fixed: Email validation regex now supports TLDs longer than 4 characters (e.g., .museum, .technology, .international)

Documentation: Clarified Appwrite Realtime comment - it's for monitoring function executions from a long-running Dart app, not from inside serverless functions

Fixed: UI_JANK false attribution bug - cumulative jank from completed operations no longer contaminates subsequent operations. Jank tracking now resets when all tracked operations complete (Firebase-style frame metric boundary). Previously, clicking button A (causing jank) then immediately clicking button B (minimal jank) could falsely attribute A's jank to B.

Fixed: UI_JANK false positive when user performs multiple actions - removed recovery-based reset that triggered when cumulative delay dropped below half threshold. Industry standard (Sentry, Firebase, Android JankStats, iOS MetricKit) is to reset at operation boundaries only, not on arbitrary "recovery" thresholds.

Added: LoadingMonitor.onAllOperationsComplete callback - invoked when activeOperations becomes empty, allowing performance monitors to reset state at operation boundaries

Fixed: Race condition in loadingMonitor.track() when same operation name used concurrently - completion logging now uses captured local opInfo variable instead of re-accessing _activeOperations[operation]! which could be null if removed by concurrent call's finally block

Added: UI_JANK event for cumulative jank detection (Sentry-style "Frames Delay") - detects non-fully-blocking hangs where animation keeps playing but app appears stuck due to multiple short blocking operations (e.g., 400ms each). Catches scenarios that UI_FREEZE misses because frames still render between blocking operations.

Added: Configurable cumulative jank thresholds via performanceMonitor.jankThresholdMs (default: 5000ms), performanceMonitor.jankWindowMultiplier (default: 2.5, minimum 1.0), and performanceMonitor.expectedFrameTimeMs (default: 16ms for 60fps). Window is computed as threshold × multiplier (default: 12500ms), guaranteeing window >= threshold mathematically.

Documentation: Added Timer/Print events (PRINT, TIMER_CREATE, TIMER_FIRE, PERIODIC_CREATE, PERIODIC_FIRE) to parsing guides

Documentation: Added UI_JANK event to AI guide, parsing guide, and developer documentation with metadata format and configuration examples

Fixed: SLOW_CALLBACK now logs once per slow operation instead of multiple times when Dart's async machinery registers callbacks through multiple zone handlers (same fingerprint within 100ms = same operation, skip duplicate)

Fixed: STUCK_OPERATION now includes sourceLocation field extracted from stored call stack - shows where track() was called (operation origin) instead of where detection happened (internal code)

Fixed: UI_FREEZE duplicate logging - flag now resets in _onFrameTimings() when UI recovers instead of recordActivity() on every pointer event (ANR-WatchDog pattern)

Fixed: UI_FREEZE race condition - freeze check now happens BEFORE "idle" check in Timer.periodic callback. Previously, when loadingMonitor.track() completed (operation removed from activeOperations), the timer would see hasPendingWork=false and reset baseline WITHOUT checking for freeze first, causing freezes to be missed intermittently ("every 3-4 clicks")

Fixed: STUCK_OPERATION completion-time check in track() finally block - ensures stuck detection logs even when Timer.periodic doesn't fire (web platform limitation, canonical log line pattern)

Added: errorType and errorMessage fields to crash/problem metadata - exposes exception class name and full error message for better debugging and compatibility with industry standards (Sentry, Firebase Crashlytics)

Fixed: crash() and problem() methods now use StackTrace.current as fallback when stackTrace is null - ensures errors from Completer.completeError without stack trace (and similar cases) still have full debugging context including stack, files, and location-aware fingerprint

Fixed: sourceLocation now extracted from error's stack trace as fallback for zone-caught errors - synchronous errors (null errors, type errors, etc.) caught by the zone now have sourceLocation populated from the error's stack trace when the current call stack has no user code

Fixed: Fingerprint deduplication now uses user code frames instead of raw top 3 frames (which were SDK frames for runtime errors). Two different bugs at different locations no longer get the same fingerprint. Now works correctly on web by also skipping dart-sdk/ and lib/_engine/ frames.

Fixed: CRITICAL performance regression - StackTrace.current.toString() was called for every callback registration (thousands during app startup), causing multi-second frame drops. Now deferred: stack object captured at registration (cheap), .toString() only called when slow callback detected (expensive, but rare).

Fixed: AutoLogger.run() now properly handles zone-based error catching - WidgetsFlutterBinding.ensureInitialized() must NOT be called before AutoLogger.run() for proper async error catching (per Flutter issue #72351)

Fixed: Documentation comment in safe_api.dart incorrectly said "30 seconds" - actual default timeout is 2 minutes

Documentation: Added PROXY_CONFIG and SSL_CERT_REJECTED HTTP events to parsing guide and AI guide

Added: trackTimer() method to SafeDisposalMixin for tracking Timer instances

Added: SafeDisposalMixin now logs 🔒LEAK warning with full debugging context (userTrail, routeStack, pendingOps, pendingHttp, state) when Timer is still active or StreamController is not closed at widget dispose

Fixed: Removed Timer, StreamSubscription, StreamController from leakProneClasses - these dart:async objects are NOT detectable by leak_tracker (only Flutter Framework objects are instrumented)

Documentation: Clarified that Timer/StreamSubscription/StreamController require SafeDisposalMixin for leak detection (not auto-detectable)

Documentation: Fixed parsing guide to use correct event types: LEAK (SafeDisposalMixin), MEMORY_LEAK (leak_tracker), STUCK_OPERATION (was incorrectly documented as STUCK)

Documentation: Clarified that LEAK warning is logged when you navigate away from the screen (widget dispose), not immediately

Fixed: Recursive stack traces now collapsed with count (e.g., recurse (×100)) instead of repeating the same frame hundreds of times

Added: stack_trace package dependency for improved stack trace formatting

Fixed: Stack traces now use Trace.terse to remove framework/SDK noise before logging

Fixed: Removed duplicate stack trace output from Talker (stack is now only in metadata JSON)

Fixed: _extractFiles now uses Trace.parse() for cross-platform compatibility and handles native (package:), relative web (packages/), and full web URLs (http://localhost/packages/...) - files field now correctly populates on web platform

Added: SLOW_CALLBACK events now include complete debugging metadata (sourceLocation, stack, files, fingerprint) - stack trace captured at callback registration time for precise source identification

Fixed: MEMORY_PRESSURE event now includes trigger, triggerAction, and currentRoute fields for consistency with other system-detected events (FRAME_DROP, UI_FREEZE, SHADER_JANK) and documentation

Fixed: Removed prescriptive hint field from LEAK log metadata - logs should contain factual data only, not solution suggestions

Fixed: STUCK_OPERATION now logs once when threshold exceeded instead of repeatedly every 5 seconds - matches UI_FREEZE behavior and industry standard (ANR-WatchDog pattern)

Documentation: Clarified configuration examples in developer documentation - added "Override to 1 minute" comments to defaultTimeoutMs and stuckOperationThresholdMs examples to distinguish override values (60000ms) from actual defaults (120000ms)

Fixed: UI_FREEZE now correctly detects freeze on first user interaction - recordActivity() only resets _lastFrameTime if app was truly idle (elapsed > activityTimeoutMs), preventing baseline reset during active use which caused first-click freezes to be missed

Fixed: UI_JANK idle-to-active false positive - now resets _previousFrameRasterFinishUs, _frameGaps, and _jankAlreadyReported when app becomes truly idle, preventing false jank detection when first frame after idle calculates huge gap from stale timestamp

Fixed: UI_FREEZE race condition - freeze detection now happens in _onFrameTimings() BEFORE resetting state. Timer.periodic and frame timing callbacks have no guaranteed execution order; if frame callback ran first after freeze ended, _lastFrameTime was reset before timer could detect the freeze. Now uses actual gap between last known frame and recovery frame.

Fixed: AutoLogger.run() now accepts FutureOr<Widget> Function() — async builders (e.g., Firebase init inside run callback) previously wouldn't compile because parameter type was Widget Function()

Fixed: Isolate error listener now correctly converts stack trace string using StackTrace.fromString() instead of unsafe as StackTrace cast — Isolate.addErrorListener sends errors as [String, String?], not [Object, StackTrace?]

Fixed: setupHttpOverrides() re-entrance guard — checks HttpOverrides.current is LoggingHttpOverrides to prevent double-wrapping when called from both run() and init()

Fixed: Suppressed textScaleFactor deprecation warning in WidgetsBindingObserver with // ignore: deprecated_member_use — PlatformDispatcher has no non-deprecated text scale API without BuildContext

Documentation: Added developer documentation reference to README

Documentation: Added missing stack field to user-triggered events JSON example in AI guide and metadata bullet list in parsing guide

Documentation: Fixed PRINT event description in parsing guide — captured output is the log message, timestamp in metadata (was incorrectly described as "message in metadata")

Documentation: Added missing ms field to SLOW_CALLBACK metadata list in parsing guide

Widened talker dependency from ^5.0.0 to >=4.0.0 <6.0.0 — allows pub to resolve talker 4.x on Dart 3.0-3.3 (talker 5.x transitively requires Dart 3.4+ via web package)

Widened web_socket_channel dependency from ^3.0.0 to >=2.3.0 <4.0.0 — allows pub to resolve 2.x on Dart 3.0-3.2 (3.x requires Dart 3.3+)

Widened leak_tracker dependency from >=10.0.0 <12.0.0 to >=9.0.0 <12.0.0 — allows pub to resolve 9.x on Dart 3.0 (10.x requires Dart 3.1.2+)

Fixed: WebSocket WS_CONNECTED was logged prematurely before actual handshake — now observes .ready Future to log only after successful connection

Fixed: WebSocket stream errors now logged as WS_ERROR event via .handleError() — previously stream errors (disconnect, protocol error) were silently dropped

Fixed: Removed dead try/catch around WebSocket .ready — errors are handled by .catchError() on the Future

Documentation: Added undocumented event types (INIT, USER_ACTION, BINDING_MODE, PERF_MONITOR_INIT) to parsing guide

Documentation: Added logger.timeout() and logger.stuck() methods to developer documentation manual logging section

Fixed: SizeChangedLayoutNotification was dead code in _logNotification() if-else chain — LayoutChangedNotification (parent class) was checked first, swallowing all subclass matches. Reordered to check SizeChangedLayoutNotification before LayoutChangedNotification

Fixed: SizeChangedLayoutNotification double-logging in LoggingNotificationListener — when both logLayout and logSize are true (defaults), a SizeChangedLayoutNotification was logged twice (as both LAYOUT_CHANGE and SIZE_CHANGE) because it extends LayoutChangedNotification. Added subclass guard to LayoutChangedNotification listener

Fixed: didReplace() in navigation observer now records NAV_REPLACE to user trail — was the only navigation event not recording to user trail (PUSH, POP, REMOVE, SWIPE_START all recorded via _log() helper, but REPLACE called logger.log() directly)

Fixed: Drift queryId collision — replaced statement.hashCode ^ args.hashCode with incrementing _queryCounter++ counter. List.hashCode is identity-based in Dart so concurrent identical queries would collide, and XOR made different queries with matching hashes share the same ID

Fixed: LoggingDioInterceptor request correlation — replaced fragile options.hashCode identity-based tracking with incrementing _requestCounter++ stored in Dio's options.extra map for robust request/response/error matching across interceptor stages

Documentation: Fixed SIZE_CHANGE description in parsing guide — removed incorrect "includes old/new size" claim (SizeChangedLayoutNotification carries no size data, metadata is empty)

Documentation: Added automatic navigation user trail actions (NAV_PUSH, NAV_POP, NAV_REPLACE, NAV_REMOVE, NAV_SWIPE_START) to parsing guide section 4.12

Fixed: Unified SCROLL_START/SCROLL_END metadata between flutter_init.dart and notification_wrapper.dart — both now log {axis, pixels} for SCROLL_START and {axis, pixels, max} for SCROLL_END

Fixed: OVERSCROLL message formatting inconsistency — flutter_init.dart now uses .toStringAsFixed(1) to match notification_wrapper.dart

Documentation: Added UserTrail convenience methods (recordTap, recordButton, recordScroll, recordInput, recordNavigation) to developer documentation

Documentation: Explained loggingDioInterceptor as a pre-configured global instance exported by the package in developer documentation

Documentation: Added scroll/layout events (SCROLL_START, SCROLL_END, OVERSCROLL, LAYOUT_CHANGE, SIZE_CHANGE) and pointer/input events (POINTER_DOWN, POINTER_UP, POINTER_MOVE, POINTER_CANCEL, KEYBOARD, FOCUS_MODE, FOCUS_CHANGE) to AI guide event listings

Documentation: Fixed SCROLL_START/SCROLL_END metadata description in parsing guide — was "axis, widget", now correctly says "axis, pixels" / "axis, pixels, max"

Documentation: Added Scroll metadata JSON example to parsing guide Section 6

Documentation: Fixed parsing guide OVERSCROLL description — was "includes axis, overscroll amount", corrected to "includes overscroll amount" (code only logs overscroll field, no axis)

Documentation: Fixed parsing guide LAYOUT_CHANGE description — was "includes widget info", corrected to no metadata claim (code logs empty metadata)

Documentation: Fixed parsing guide POINTER_MOVE/POINTER_CANCEL — all pointer events include x, y, widget metadata (MOVE was missing "widget", CANCEL had no metadata listed)

Documentation: Split parsing guide Section 6 Scroll Metadata into separate SCROLL and OVERSCROLL subsections — combined JSON example was misleading (OVERSCROLL only has overscroll field, not axis/pixels)

Documentation: Added WebSocket Metadata section to parsing guide Section 6 with url, size, code, reason fields

Documentation: Added navigation metadata note to parsing guide — all nav events include route, type (page/dialog/bottomSheet/popup/unknown), and stack

Documentation: Added metadata descriptions to parsing guide for TIMER_FIRE (ms), PERIODIC_FIRE (count, ms), BACK_GESTURE_START (progress, swipeEdge), ROUTE_NOT_FOUND (route, args), LOADING_START (op, threshold_ms), LOADING_COMPLETE (op, ms)

Documentation: Added INIT, HTTP main events, File/Directory events, Timer/Zone events, Navigation events, Performance events, Memory events, Loading events to AI guide event listings (was only listing non-obvious events, now comprehensive)

Documentation: Fixed AI guide POINTER_MOVE/POINTER_CANCEL metadata descriptions to include widget

Fixed: FOCUS_CHANGE semantic null bug — focused?.debugLabel ?? focused.runtimeType.toString() bypassed null safety (?. only guards debugLabel, not runtimeType), logging "Null" when no widget has focus. Now uses focused?.runtimeType.toString() ?? 'none' fallback.

Fixed: Removed invasive PlatformViewsService handler — setMessageHandler('flutter/platform_views', ...) replaces the framework's existing handler (does not chain), breaking PlatformView widgets (WebView, MapView, etc.). Platform channel logging is already handled by LoggingBinaryMessenger in custom binding mode.

Fixed: didRemove() route stack removal — _routeStack.remove(name) removes first occurrence (wrong for stack where same route name can appear multiple times); now uses lastIndexOf + removeAt to remove the topmost (last) occurrence

Fixed: WebSocket error events now include url in metadata — WS_CONNECT_FAILED, WS_ERROR, and WS_SEND_ERROR were logging errors without the url field that all other WS events include

Fixed: FUNCTION_STDERR now uses logger.problem() instead of logger.log() — auto-injects 10+ debugging fields (sourceLocation, triggerAction, fingerprint, stack, files, etc.) that were missing from stderr logs

Fixed: setupIOOverrides() re-entrance guard — checks IOOverrides.current is LoggingIOOverrides to prevent double-wrapping (same pattern as existing setupHttpOverrides() guard)

Fixed: Leak check timer now stored in _leakCheckTimer field — Timer.periodic() result was previously discarded, preventing proper resource management

Documentation: Added integration event listings (WebSocket, gRPC, SQL/Drift, BLoC, Riverpod, SharedPreferences, Hive, Appwrite, Safe Utilities, User Trail) to AI guide

Documentation: Updated AI guide Pointer events to include type and key metadata fields; added FOCUS_MODE (mode) and FOCUS_CHANGE (widget) metadata descriptions

Documentation: Fixed parsing guide pointer event descriptions to include type, key fields; fixed FOCUS_MODE/FOCUS_CHANGE metadata; fixed TIMER_FIRE description

Documentation: Added Pointer, SQL, gRPC, BLoC, Riverpod, Loading, and Safe Utilities metadata JSON examples to parsing guide Section 6