Merge branch 'main' into sb/zen-helpsb/zen-help

- Combine HelpCommand (this branch) with HistoryCommand (main) in zen CLI dispatcher
- Keep filter-aware TuiPickOne rewrite; adopt main's ASCII arrow glyphs in doc comment

1 files changed, 69 insertions, 0 deletions

diff --git a/src/zen/trace/timeline_query.h b/src/zen/trace/timeline_query.h
new file mode 100644
index 000000000..f773d8e58
--- /dev/null
+++ b/src/zen/trace/timeline_query.h
@@ -0,0 +1,69 @@
+// Copyright Epic Games, Inc. All Rights Reserved.
+
+#pragma once
+
+#include "trace_model.h"
+
+#include <cstdint>
+#include <memory>
+#include <span>
+#include <vector>
+
+namespace zen::trace_detail {
+
+// Plain-data view of a single timeline scope returned by a TimelineQuery.
+// Mirrors the on-disk TimelineScope but is intentionally decoupled from the
+// in-memory model so that alternative backends can share the same result type.
+struct TimelineScopeView
+{
+	uint32_t BeginUs;
+	uint32_t DurationUs;
+	uint32_t NameId;
+	uint16_t Depth;
+	uint16_t MergeCount;  // 0 == raw LOD 0, N>0 == N merged scopes
+};
+
+// Common parameters for a viewport-style timeline query.
+struct TimelineQueryRequest
+{
+	uint32_t StartUs;
+	uint32_t EndUs;
+	uint32_t MinDurUs;
+	uint32_t ResolutionUs;	// 0 == LOD 0 (raw); >0 picks the smallest LOD with ResolutionUs >= this
+};
+
+// Backend-agnostic interface for serving timeline scope data to the trace
+// viewer HTTP handlers. Currently only the in-memory implementation exists,
+// but the abstraction is preserved as a clean swap point if a different
+// backend (e.g. on-disk indexed store) ever becomes useful.
+class TimelineQuery
+{
+public:
+	virtual ~TimelineQuery() = default;
+
+	// Append all scopes for a single thread matching the request to Out.
+	// Out is not cleared; callers can chain queries into the same buffer.
+	virtual void QueryThread(uint32_t ThreadId, const TimelineQueryRequest& Req, std::vector<TimelineScopeView>& Out) const = 0;
+
+	// Result of a batch query: a single flat scope vector plus per-thread
+	// ranges into it. Ranges[i] corresponds to ThreadIds[i] from the request.
+	struct BatchResult
+	{
+		struct Range
+		{
+			uint32_t Begin;
+			uint32_t End;
+		};
+		std::vector<TimelineScopeView> Scopes;
+		std::vector<Range>			   Ranges;
+	};
+
+	// Query several threads in one call. Out is cleared before being filled.
+	virtual void QueryBatch(std::span<const uint32_t> ThreadIds, const TimelineQueryRequest& Req, BatchResult& Out) const = 0;
+};
+
+// In-memory implementation. Holds a reference to Model — the model must
+// outlive the returned object.
+std::unique_ptr<TimelineQuery> MakeInMemoryTimelineQuery(const TraceModel& Model);
+
+}  // namespace zen::trace_detail