Documentation
¶
Overview ¶
Package devtools provides lightweight in-browser inspection for GoWebComponents applications.
The initial surface focuses on the minimum useful debugging view:
- component tree visibility
- hook state inspection
- current route inspection
- structured runtime diagnostics
Use Panel to render an embeddable development overlay inside an app, or call SnapshotNow to retrieve the current inspection state programmatically.
Devtools composes three contribution sources:
- app-owned sections and overlay actions registered through Set* helpers
- compatibility host contributions registered through ApplyHostExtensions
- kernel-owned internal contributions resolved from the framework plugin kernel
Index ¶
- func ApplyHostExtensions(parseHost *plugin.Host) func()
- func ClearTraceReplay()
- func ErrorOverlay(parseProps ErrorOverlayProps) ui.Node
- func ExportBrowserExtensionManifestJSON(parseBrowser string) ([]byte, error)
- func ExportBugCaptureBundleJSON(parseBundle BugCaptureBundle) ([]byte, error)
- func ExportExtensionPanelPayloadJSON(parseSnapshot Snapshot) ([]byte, error)
- func ExportSnapshotJSON(parseSnapshot Snapshot) ([]byte, error)
- func ExportSupportDiagnosticBundleJSON(parseBundle BugCaptureBundle) ([]byte, error)
- func ExportTraceCaptureJSON(parseCapture TraceCapture) ([]byte, error)
- func Panel(parseProps PanelProps) ui.Node
- func ReplayBugCaptureBundle(parseBundle BugCaptureBundle)
- func ResetCoordinationInspection()
- func ResetErrorOverlayActions()
- func ResetExtensionSections()
- func ResetMultiClientInspection()
- func ResetSerializationBoundaryInspection()
- func SetCoordinationInspection(parseState Coordination)
- func SetErrorOverlayActions(parseActions []ErrorOverlayAction)
- func SetExtensionSections(parseSections []ExtensionSection)
- func SetMultiClientInspection(parseState MultiClient)
- func SetSerializationBoundaryInspection(parseState BoundaryInspection)
- func SetTraceReplay(parseCapture TraceCapture)
- type Boundary
- type BoundaryInspection
- type Branch
- type BrowserExtensionManifest
- type BugCaptureBundle
- type CacheEntry
- type Classification
- type ComponentRenderTrace
- type ConflictState
- type Coordination
- type Diagnostic
- type ErrorOverlayAction
- type ErrorOverlayActionContext
- type ErrorOverlayIssue
- type ErrorOverlayProps
- type ExtensionPanelPayload
- type ExtensionSection
- type FlamegraphFrame
- type Hook
- type HydrationDebug
- type KernelPluginEvent
- type KernelPluginHealth
- type KernelSnapshot
- type Log
- type LogLevel
- type MultiClient
- type MultiClientFailure
- type MultiClientPeer
- type MultiClientTraffic
- type Node
- type PanelProps
- type Profiling
- type ProfilingEvent
- type ProfilingPhaseTotals
- type ReconnectStatus
- type ReplayEntry
- type Route
- type RouteLoader
- type RouteMetadata
- type RouteRedirect
- type RouteStack
- type RouteStartupBudget
- type Severity
- type Snapshot
- type SnapshotComparison
- type StartupProfiling
- type Stats
- type SupportDiagnosticBundle
- type SyncEvent
- type SyncHealthEntry
- type SyncQueueEntry
- type TraceCapture
- type WorkerJob
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ApplyHostExtensions ¶
ApplyHostExtensions registers one compatibility host source and returns a cleanup that removes it.
func ClearTraceReplay ¶
func ClearTraceReplay()
ClearTraceReplay disables the current replayed trace.
func ErrorOverlay ¶
func ErrorOverlay(parseProps ErrorOverlayProps) ui.Node
ErrorOverlay renders a focused development overlay for current runtime failures.
func ExportBrowserExtensionManifestJSON ¶
ExportBrowserExtensionManifestJSON serializes a browser-specific extension manifest.
func ExportBugCaptureBundleJSON ¶
func ExportBugCaptureBundleJSON(parseBundle BugCaptureBundle) ([]byte, error)
ExportBugCaptureBundleJSON serializes one local debugging bundle into stable JSON.
func ExportExtensionPanelPayloadJSON ¶
ExportExtensionPanelPayloadJSON serializes the stable browser-extension panel payload.
func ExportSnapshotJSON ¶
ExportSnapshotJSON serializes a devtools snapshot into stable JSON.
func ExportSupportDiagnosticBundleJSON ¶
func ExportSupportDiagnosticBundleJSON(parseBundle BugCaptureBundle) ([]byte, error)
ExportSupportDiagnosticBundleJSON serializes one redacted support-safe bundle into stable JSON.
func ExportTraceCaptureJSON ¶
func ExportTraceCaptureJSON(parseCapture TraceCapture) ([]byte, error)
ExportTraceCaptureJSON serializes one trace capture into stable JSON.
func Panel ¶
func Panel(parseProps PanelProps) ui.Node
Panel renders an embeddable in-browser devtools overlay.
func ReplayBugCaptureBundle ¶
func ReplayBugCaptureBundle(parseBundle BugCaptureBundle)
ReplayBugCaptureBundle replays the bug-capture bundle through the trace replay path.
func ResetCoordinationInspection ¶
func ResetCoordinationInspection()
ResetCoordinationInspection clears the app-owned coordination inspection state.
func ResetErrorOverlayActions ¶
func ResetErrorOverlayActions()
ResetErrorOverlayActions clears the current app-owned recovery actions for the error overlay.
func ResetExtensionSections ¶
func ResetExtensionSections()
ResetExtensionSections clears the current app-owned or companion-owned devtools sections.
func ResetMultiClientInspection ¶
func ResetMultiClientInspection()
ResetMultiClientInspection clears the stored multi-client inspection state.
func ResetSerializationBoundaryInspection ¶
func ResetSerializationBoundaryInspection()
ResetSerializationBoundaryInspection clears the app-owned boundary inspection state.
func SetCoordinationInspection ¶
func SetCoordinationInspection(parseState Coordination)
SetCoordinationInspection stores app-owned worker, sync, and replay inspection state.
func SetErrorOverlayActions ¶
func SetErrorOverlayActions(parseActions []ErrorOverlayAction)
SetErrorOverlayActions replaces the current app-owned recovery actions for the error overlay.
func SetExtensionSections ¶
func SetExtensionSections(parseSections []ExtensionSection)
SetExtensionSections replaces the current app-owned or companion-owned devtools sections.
func SetMultiClientInspection ¶
func SetMultiClientInspection(parseState MultiClient)
SetMultiClientInspection stores a snapshot of multi-client state for inspection.
func SetSerializationBoundaryInspection ¶
func SetSerializationBoundaryInspection(parseState BoundaryInspection)
SetSerializationBoundaryInspection stores app-owned boundary inspection state.
func SetTraceReplay ¶
func SetTraceReplay(parseCapture TraceCapture)
SetTraceReplay activates replay mode for the supplied captured trace.
Types ¶
type Boundary ¶
type Boundary struct {
Name string
Kind string
Direction string
Transport string
Encoding string
Scope string
Target string
Status string
CorrelationID string
SizeBytes int
InlineBytes int
BinaryBytes int
Notes []string
Redacted []string
Downgraded []string
Rejected []string
}
Boundary describes one client/server data boundary crossing (transport, encoding, size, status).
type BoundaryInspection ¶
type BoundaryInspection struct {
Entries []Boundary
}
BoundaryInspection is the set of inspected client/server data boundaries.
func InspectBootstrapBoundaries ¶
func InspectBootstrapBoundaries(parseBootstrap ui.SSRBootstrap) (BoundaryInspection, error)
InspectBootstrapBoundaries converts an SSR bootstrap payload into a boundary inspection snapshot.
func InspectSerializationBoundaries ¶
func InspectSerializationBoundaries() BoundaryInspection
InspectSerializationBoundaries returns the current app-owned boundary inspection state.
type Branch ¶
type Branch struct {
Name string
Kind string
Path string
RenderDurationNs int64
DiffDurationNs int64
CommitDurationNs int64
EffectDurationNs int64
CleanupDurationNs int64
SelfDurationNs int64
SubtreeDurationNs int64
}
Branch describes one hot subtree in profiling output.
type BrowserExtensionManifest ¶
type BrowserExtensionManifest struct {
ManifestVersion int `json:"manifest_version"`
Name string `json:"name"`
Version string `json:"version"`
Description string `json:"description"`
DevtoolsPage string `json:"devtools_page"`
Permissions []string `json:"permissions,omitempty"`
HostPermissions []string `json:"host_permissions,omitempty"`
Background map[string]string `json:"background,omitempty"`
BrowserSpecific map[string]any `json:"browser_specific_settings,omitempty"`
}
BrowserExtensionManifest describes the browser-extension shell that hosts the GWC devtools panel in Chrome-compatible and Firefox-compatible browsers.
func BrowserExtensionManifestFor ¶
func BrowserExtensionManifestFor(parseBrowser string) BrowserExtensionManifest
BrowserExtensionManifestFor returns a manifest for a GWC companion devtools extension. Pass "firefox" to include Firefox's browser_specific_settings block.
type BugCaptureBundle ¶
type BugCaptureBundle struct {
Version int
Label string
CapturedAt string
Trace TraceCapture
}
BugCaptureBundle packages one local debugging artifact for later replay or attachment.
func CaptureBugBundle ¶
func CaptureBugBundle(parseLabel string) BugCaptureBundle
CaptureBugBundle captures one local debugging bundle from the current live snapshot.
func ImportBugCaptureBundleJSON ¶
func ImportBugCaptureBundleJSON(parseData []byte) (BugCaptureBundle, error)
ImportBugCaptureBundleJSON deserializes one local debugging bundle from JSON.
type CacheEntry ¶
type Classification ¶
type Classification string
Classification is the category label grouping related diagnostics and logs.
type ComponentRenderTrace ¶
type ComponentRenderTrace struct {
Name string
Path string
RenderCount int
RerenderCount int
LastTrigger string
LastRenderDurationNs int64
TotalRenderDurationNs int64
AverageRenderDurationNs int64
LastRenderedAt string
TriggerCounts map[string]int
}
ComponentRenderTrace aggregates render/rerender counts and durations for one component.
type ConflictState ¶
type ConflictState struct {
Entity string
Owner string
Status string
Strategy string
DetectedAt time.Time
LastError string
}
ConflictState describes an entity's current sync-conflict status and resolution strategy.
type Coordination ¶
type Coordination struct {
Workers []WorkerJob
SyncEvents []SyncEvent
Replay []ReplayEntry
QueueEntries []SyncQueueEntry
SyncHealth []SyncHealthEntry
Reconnect ReconnectStatus
Conflict ConflictState
LastReplayError string
}
Coordination aggregates worker, sync, replay, reconnect, and conflict state for offline/realtime debugging.
func InspectCoordination ¶
func InspectCoordination() Coordination
InspectCoordination returns the current app-owned coordination inspection state.
type Diagnostic ¶
type Diagnostic struct {
Source string
Severity Severity
Classification Classification
Code string
Docs string
Remediation string
Recoverable bool
TopFrame string
Consequence string
Message string
Count int
Path string
ComponentStack []string
Fields map[string]string
}
Diagnostic describes a runtime diagnostic entry surfaced in devtools.
type ErrorOverlayAction ¶
type ErrorOverlayAction struct {
Label string
MatchCodes []string
MatchSources []string
Run func(ErrorOverlayActionContext)
}
ErrorOverlayAction describes one app-owned recovery action for overlay issues.
func InspectComposedErrorOverlayActions ¶
func InspectComposedErrorOverlayActions() []ErrorOverlayAction
InspectComposedErrorOverlayActions returns app-owned, host-owned, and kernel-owned overlay actions.
func InspectErrorOverlayActions ¶
func InspectErrorOverlayActions() []ErrorOverlayAction
InspectErrorOverlayActions returns the current app-owned recovery actions for the error overlay.
type ErrorOverlayActionContext ¶
type ErrorOverlayActionContext struct {
Snapshot Snapshot
Issue ErrorOverlayIssue
}
ErrorOverlayActionContext is passed to one overlay recovery action handler.
type ErrorOverlayIssue ¶
type ErrorOverlayIssue struct {
Severity Severity
Source string
Code string
Message string
TopFrame string
Path string
Docs string
}
ErrorOverlayIssue is one actionable failure surfaced by the browser overlay.
type ErrorOverlayProps ¶
ErrorOverlayProps configures the embeddable in-browser error overlay.
type ExtensionPanelPayload ¶
type ExtensionPanelPayload struct {
SchemaVersion string `json:"schemaVersion"`
Route Route `json:"route"`
Tree *Node `json:"tree,omitempty"`
Stats Stats `json:"stats"`
Profiling Profiling `json:"profiling"`
Extensions []ExtensionSection `json:"extensions,omitempty"`
Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
Logs []Log `json:"logs,omitempty"`
}
ExtensionPanelPayload is the stable JSON envelope consumed by companion browser extensions. It intentionally mirrors Snapshot sections instead of DOM internals so Chrome and Firefox panels can share one renderer.
func BuildExtensionPanelPayload ¶
func BuildExtensionPanelPayload(parseSnapshot Snapshot) ExtensionPanelPayload
BuildExtensionPanelPayload projects a live devtools snapshot into the stable extension bridge payload.
type ExtensionSection ¶
ExtensionSection is a named block of extra summary lines contributed by a devtools extension.
func InspectComposedExtensionSections ¶
func InspectComposedExtensionSections() []ExtensionSection
InspectComposedExtensionSections returns app-owned, host-owned, and kernel-owned extension sections.
func InspectExtensionSections ¶
func InspectExtensionSections() []ExtensionSection
InspectExtensionSections returns the current app-owned or companion-owned devtools sections.
type FlamegraphFrame ¶
type FlamegraphFrame struct {
Name string
Kind string
Path string
Depth int
StartNs int64
DurationNs int64
SelfDurationNs int64
RenderDurationNs int64
DiffDurationNs int64
CommitDurationNs int64
EffectDurationNs int64
CleanupDurationNs int64
}
FlamegraphFrame is one node in a render-timeline flamegraph (offset, depth, durations).
type HydrationDebug ¶
type HydrationDebug struct {
CorrelationID string
StartedAt string
FinishedAt string
DurationNs int64
ExistingDOMNodeCount int
FallbackCount int
MismatchCount int
DiscardedNodeCount int
Strict bool
Failed bool
Failure string
RecentMessages []string
}
HydrationDebug records the outcome of a client hydration pass (mismatches, fallbacks, failures).
type KernelPluginEvent ¶
type KernelPluginEvent struct {
PluginID string
Operation string
Reason string
Message string
When time.Time
}
KernelPluginEvent stores one plugin diagnostic summary.
type KernelPluginHealth ¶
type KernelPluginHealth struct {
ID string
State string
Reason string
Message string
ErrorCount int
}
KernelPluginHealth stores one plugin health summary.
type KernelSnapshot ¶
type KernelSnapshot struct {
APIVersion string
Plugins []KernelPluginHealth
Events []KernelPluginEvent
}
KernelSnapshot is the top-level devtools view of plugin kernel state.
type Log ¶
type Log struct {
Domain string
Level LogLevel
Classification Classification
Code string
Docs string
Remediation string
Recoverable bool
TopFrame string
Consequence string
Message string
Timestamp string
CorrelationID string
Fields map[string]string
}
Log is one captured runtime log entry surfaced in devtools.
type LogLevel ¶
type LogLevel string
LogLevel is the verbosity level of a captured devtools Log entry.
type MultiClient ¶
type MultiClient struct {
Enabled bool
LocalPeerID string
ResolvedTransport string
AuthorityView map[string]string
Peers []MultiClientPeer
RecentTraffic []MultiClientTraffic
FailedPublishes []MultiClientFailure
}
func InspectMultiClient ¶
func InspectMultiClient() MultiClient
InspectMultiClient returns a copy of the current multi-client inspection state.
type MultiClientFailure ¶
type MultiClientPeer ¶
type MultiClientTraffic ¶
type Node ¶
type Node struct {
Name string
Path string
Kind string
Dirty bool
NeedsUpdate bool
FineGrained bool
ReactiveSource string
UpdateOrigin string
EffectCount int
HookCount int
Signature string
RenderDurationNs int64
DiffDurationNs int64
CommitDurationNs int64
EffectDurationNs int64
CleanupDurationNs int64
SelfDurationNs int64
SubtreeDurationNs int64
Hooks []Hook
Children []Node
}
Node describes one component or host node in the inspected runtime tree.
type PanelProps ¶
type PanelProps struct {
Title string
InitiallyOpen bool
RefreshInterval time.Duration
MaxDepth int
}
PanelProps configures the embeddable devtools panel.
type Profiling ¶
type Profiling struct {
RenderCalls int
ScheduledRootUpdates int
ScheduledFiberMarks int
ScheduledGranularMarks int
WorkLoopPasses int
ProcessedUnits int
CommitCount int
FineGrainedCommits int
FineGrainedDescendantHostCommits int
FineGrainedDescendantTextCommits int
EffectExecutions int
CleanupExecutions int
LastRenderDurationNs int64
LastCommitDurationNs int64
LastEffectDurationNs int64
LastCleanupDurationNs int64
PhaseTotals ProfilingPhaseTotals
ComponentRenders []ComponentRenderTrace
RecentEvents []ProfilingEvent
FlamegraphFrames []FlamegraphFrame
Startup StartupProfiling
HotBranches []Branch
}
Profiling summarizes runtime profiling counters and hot branches.
type ProfilingEvent ¶
type ProfilingEvent struct {
Domain string
Name string
Phase string
Target string
CorrelationID string
DurationNs int64
Timestamp string
Fields map[string]string
}
ProfilingEvent is one timed event captured during profiling (a phase on a target).
type ProfilingPhaseTotals ¶
type ProfilingPhaseTotals struct {
RenderDurationNs int64
DiffDurationNs int64
CommitDurationNs int64
EffectDurationNs int64
CleanupDurationNs int64
}
ProfilingPhaseTotals sums per-phase durations (render/diff/commit/effect/cleanup) in nanoseconds.
type ReconnectStatus ¶
type ReconnectStatus struct {
State string
Transport string
Attempts int
MaxAttempts int
NextRetryAt time.Time
LastChange time.Time
IsConnected bool
}
ReconnectStatus describes the current realtime reconnect/backoff state.
type ReplayEntry ¶
type ReplayEntry struct {
ID string
Kind string
Method string
URL string
Owner string
State string
LastError string
Attempts int
MaxAttempts int
NextAttemptAt time.Time
UpdatedAt time.Time
}
ReplayEntry is one queued offline mutation awaiting or undergoing replay.
type Route ¶
type Route struct {
Path string
Query map[string][]string
Params map[string]string
Loading bool
Stack []RouteStack
Loaders []RouteLoader
LastRedirect RouteRedirect
Metadata RouteMetadata
}
type RouteLoader ¶
type RouteMetadata ¶
type RouteRedirect ¶
type RouteStack ¶
type RouteStartupBudget ¶
type RouteStartupBudget struct {
RouteFamily string
LastRoutePath string
SampleCount int
AverageBootstrapReadDurationNs int64
AverageWASMTransferBytes int64
AverageWASMDecodedBytes int64
AverageBootstrapDecodedBytes int64
AverageCacheWarmupDurationNs int64
AverageServiceWorkerOverheadNs int64
AverageInitialRouteDataBytes int64
AverageHydrationDurationNs int64
AverageStartupCommitDurationNs int64
AverageFirstInteractionDurationNs int64
}
RouteStartupBudget holds averaged startup timings per route family for budget tracking.
type Severity ¶
type Severity string
Severity ranks a devtools Diagnostic from informational to error.
type Snapshot ¶
type Snapshot struct {
Route Route
Cache []CacheEntry
MultiClient MultiClient
Boundaries BoundaryInspection
Coordination Coordination
Kernel KernelSnapshot
Extensions []ExtensionSection
Tree *Node
Stats Stats
Profiling Profiling
Hydration HydrationDebug
Diagnostics []Diagnostic
Logs []Log
}
Snapshot is the top-level devtools inspection payload.
func SnapshotNow ¶
func SnapshotNow() Snapshot
SnapshotNow captures the current runtime, route, and diagnostic inspection state.
func UseSnapshot ¶
UseSnapshot polls SnapshotNow on an interval and returns the latest snapshot.
type SnapshotComparison ¶
type SnapshotComparison struct {
Equal bool
ChangedSections []string
PreviousFingerprint string
CurrentFingerprint string
PreviousSize int
CurrentSize int
}
SnapshotComparison summarizes how two inspection snapshots differ.
func CompareSnapshots ¶
func CompareSnapshots(parsePrevious, parseCurrent Snapshot) (SnapshotComparison, error)
CompareSnapshots compares two snapshots and reports the top-level sections that changed.
type StartupProfiling ¶
type StartupProfiling struct {
Mode string
StartedAt string
BootstrapReadDurationNs int64
WASMTransferBytes int64
WASMDecodedBytes int64
BootstrapDecodedBytes int64
CacheWarmupDurationNs int64
ServiceWorkerOverheadNs int64
InitialRouteDataBytes int64
HydrationDurationNs int64
StartupCommitDurationNs int64
FirstInteractionDurationNs int64
FirstInteractionCaptured bool
FirstInteractionEvent string
RouteBudgets []RouteStartupBudget
}
StartupProfiling captures one-time app startup timings (bootstrap, transfer, hydration, first interaction).
type Stats ¶
type Stats struct {
TotalFibers int
DirtyFibers int
ComponentFibers int
HostFibers int
TextFibers int
FineGrainedFibers int
HookEntries int
Effects int
}
Stats summarizes the current inspected runtime tree.
type SupportDiagnosticBundle ¶
type SupportDiagnosticBundle struct {
Version int
Sanitized bool
Label string
CapturedAt string
Trace TraceCapture
}
SupportDiagnosticBundle packages one redacted debugging artifact for support workflows.
func CaptureSupportDiagnosticBundle ¶
func CaptureSupportDiagnosticBundle(parseLabel string) SupportDiagnosticBundle
CaptureSupportDiagnosticBundle captures one redacted support-safe debugging bundle from the current snapshot.
func ImportSupportDiagnosticBundleJSON ¶
func ImportSupportDiagnosticBundleJSON(parseData []byte) (SupportDiagnosticBundle, error)
ImportSupportDiagnosticBundleJSON deserializes one support-safe bundle from JSON.
func SanitizeBugCaptureBundleForSupport ¶
func SanitizeBugCaptureBundleForSupport(parseBundle BugCaptureBundle) SupportDiagnosticBundle
SanitizeBugCaptureBundleForSupport converts one local debugging bundle into one support-safe artifact.
type SyncEvent ¶
type SyncEvent struct {
Channel string
Transport string
Direction string
Topic string
Target string
Status string
Error string
Correlation string
Timestamp time.Time
}
SyncEvent is one realtime sync channel event (publish/receive on a topic).
type SyncHealthEntry ¶
type SyncHealthEntry struct {
Entity string
Owner string
Status string
Version string
PendingOps int
LastSyncAt time.Time
LastError string
}
SyncHealthEntry reports per-entity sync health (pending ops, version, last sync).
type SyncQueueEntry ¶
type SyncQueueEntry struct {
ID string
Entity string
Operation string
Owner string
State string
URL string
Attempts int
MaxAttempts int
LastError string
QueuedAt time.Time
UpdatedAt time.Time
}
SyncQueueEntry is one entity operation pending in the offline sync queue.
type TraceCapture ¶
TraceCapture stores one labeled devtools snapshot for export, comparison, and replay.
func CaptureTrace ¶
func CaptureTrace(parseLabel string) TraceCapture
CaptureTrace captures the current live devtools snapshot with a label and timestamp.
func CurrentTraceReplay ¶
func CurrentTraceReplay() (TraceCapture, bool)
CurrentTraceReplay returns the current replayed trace, if any.
func ImportTraceCaptureJSON ¶
func ImportTraceCaptureJSON(parseData []byte) (TraceCapture, error)
ImportTraceCaptureJSON deserializes one trace capture from JSON.
Source Files
¶
- bug_capture.go
- capture_service.go
- composed_sources.go
- coordination_state.go
- devtools_sections_wasm.go
- devtools_tree_wasm.go
- devtools_wasm.go
- doc.go
- error_overlay_actions.go
- extension_bridge.go
- extension_sections.go
- host_extensions.go
- multi_client_state.go
- plugin_bridge.go
- serialization_boundaries.go
- snapshot_export.go
- support_bundle.go
- trace_capture.go
- types.go