matterviz 0.4.1 → 0.4.3

package/dist/trajectory/Trajectory.svelte

@@ -5,9 +5,9 @@
   import { StatusMessage } from '../feedback'
   import Spinner from '../feedback/Spinner.svelte'
   import Icon from '../Icon.svelte'
-  import { drag_over_handlers, handle_url_drop, load_from_url } from '../io'
+  import * as io from '../io'
   import { forward_window_keydown, handle_and_prevent } from '../keyboard'
-  import { format_num, trajectory_property_config } from '../labels'
+  import { format_num, trajectory_property_config, type TrajPropertyConfig } from '../labels'
   import type { Vec2 } from '../math'
   import { sanitize_html } from '../sanitize'
   import { FullscreenButton, type FullscreenToggleProp, toggle_fullscreen } from '../layout'
@@ -17,21 +17,29 @@
   import { Histogram, ScatterPlot } from '../plot'
   import { toggle_series_visibility } from '../plot/core/utils/series-visibility'
   import { DEFAULTS } from '../settings'
+  import type { AnyStructure } from '../structure'
   import Structure from '../structure/Structure.svelte'
   import { scaleLinear } from 'd3-scale'
   import type { ComponentProps, Snippet } from 'svelte'
-  import { untrack } from 'svelte'
+  import { onMount, untrack } from 'svelte'
   import { tooltip } from 'svelte-multiselect/attachments'
   import type { HTMLAttributes } from 'svelte/elements'
+  import { SvelteSet } from 'svelte/reactivity'
   import { full_data_extractor } from './extract'
   import type {
     ParseProgress,
     TrajectoryDataExtractor,
     TrajectoryFrame,
+    TrajectoryMetadata,
     TrajectoryType,
     TrajHandlerData,
   } from './index'
-  import { TrajectoryError, TrajectoryExportPane, TrajectoryInfoPane } from './index'
+  import {
+    FRAME_LOAD_DEBOUNCE_MS,
+    TrajectoryError,
+    TrajectoryExportPane,
+    TrajectoryInfoPane,
+  } from './index'
   import type { AtomTypeMapping, LoadingOptions } from './parse'
   import {
     get_unsupported_format_message,
@@ -41,6 +49,7 @@
   } from './parse'
   import {
     generate_axis_labels,
+    generate_axis_scale_types,
     generate_plot_series,
     generate_streaming_plot_series,
     should_hide_plot,
@@ -64,6 +73,12 @@
     total_frames: number
     on_step_change: (idx: number) => void
   }
+  type PlotMetadataStreamMessage = {
+    command?: string
+    file_path?: string
+    plot_metadata?: TrajectoryMetadata[]
+    is_complete?: boolean
+  }
 
   let {
     trajectory = $bindable(),
@@ -106,85 +121,86 @@
     wrapper = $bindable(),
     fullscreen = $bindable(false),
     ...rest
-  }: EventHandlers & HTMLAttributes<HTMLDivElement> & {
-    // trajectory data - can be provided directly or loaded from file
-    trajectory?: TrajectoryType
-    // URL to load trajectory from (alternative to providing trajectory directly)
-    data_url?: string
-    // current step index being displayed
-    current_step_idx?: number
-    // custom function to extract plot data from trajectory frames
-    data_extractor?: TrajectoryDataExtractor
-
-    // file drop handlers
-    allow_file_drop?: boolean
-    // layout configuration - 'auto' (default) adapts to element size, 'horizontal'/'vertical' forces layout
-    layout?: `auto` | Orientation
-    // structure viewer props (passed to Structure component)
-    structure_props?: ComponentProps<typeof Structure>
-    // plot props (passed to ScatterPlot component)
-    scatter_props?: ComponentProps<typeof ScatterPlot>
-    // histogram props (passed to Histogram component, excluding series which is handled separately)
-    histogram_props?: Omit<ComponentProps<typeof Histogram>, `series`>
-    // spinner props (passed to Spinner component)
-    spinner_props?: ComponentProps<typeof Spinner>
-    // custom snippets for additional UI elements
-    trajectory_controls?: Snippet<[ControlsProps]>
-    // Custom error snippet for advanced error handling
-    error_snippet?: Snippet<[{ error_msg: string; on_dismiss: () => void }]>
-    // Controls visibility configuration.
-    // - 'always': controls always visible
-    // - 'hover': controls visible on component hover (default)
-    // - 'never': controls never visible
-    // - object: { mode, hidden, style } for fine-grained control
-    // Control names: 'filename', 'nav', 'step', 'fps', 'info-pane', 'export-pane', 'view-mode', 'fullscreen'
-    show_controls?: ShowControlsProp
-    // show/hide the fullscreen button
-    fullscreen_toggle?: FullscreenToggleProp
-    // automatically start playing when trajectory data is loaded
-    auto_play?: boolean
-    // display mode: 'structure+scatter' (default), 'structure' (only structure), 'scatter' (only scatter), 'histogram' (only histogram), 'structure+histogram' (structure with histogram)
-    display_mode?:
-      | `structure+scatter`
-      | `structure`
-      | `scatter`
-      | `histogram`
-      | `structure+histogram`
-    // step labels configuration for slider
-    // - positive number: number of evenly spaced ticks
-    // - negative number: spacing between ticks (e.g. -10 = every 10th step)
-    // - array: exact step indices to label
-    // - undefined: no labels
-    step_labels?: number | number[]
-    // visible properties - bindable array of property keys currently shown in the plot
-    // - controls which trajectory properties are plotted (e.g. ['energy', 'volume', 'force_max'])
-    // - bindable: reflects current visibility state and can be used for external control
-    // - if not provided, uses default visible properties (energy, force_max, stress_frobenius)
-    // - if specified properties don't exist in data, falls back to automatic selection
-    visible_properties?: string[]
-    // custom labels for trajectory properties - maps property keys to display labels
-    // - e.g. {energy: 'Total Energy', volume: 'Cell Volume', force_max: 'Max Force'}
-    // - merged with built-in trajectory_property_config
-    ELEM_PROPERTY_LABELS?: Record<string, string>
-    fps_range?: Vec2 // allowed FPS range [min_fps, max_fps]
-    fps?: number // frame rate for playback
-    // Loading options for large files
-    loading_options?: LoadingOptions
-    // Map LAMMPS atom types to element symbols (e.g. {1: 'Na', 2: 'Cl'})
-    atom_type_mapping?: AtomTypeMapping
-    // Disable plot skimming (mouse over plot doesn't update structure/step slider)
-    plot_skimming?: boolean
-    // bindable: true while the pointer is over the viewer (drives hover-scoped shortcuts)
-    hovered?: boolean
-    // bindable: whether the (structure) controls pane is currently open
-    controls_open?: boolean
-    // bindable: whether the trajectory info pane is currently open
-    info_pane_open?: boolean
-    // bindable: top-level wrapper element
-    wrapper?: HTMLDivElement
-    // bindable: fullscreen state
-    fullscreen?: boolean
-  } = $props()
+  }: EventHandlers &
+    HTMLAttributes<HTMLDivElement> & {
+      // trajectory data - can be provided directly or loaded from file
+      trajectory?: TrajectoryType
+      // URL to load trajectory from (alternative to providing trajectory directly)
+      data_url?: string
+      // current step index being displayed
+      current_step_idx?: number
+      // custom function to extract plot data from trajectory frames
+      data_extractor?: TrajectoryDataExtractor
+
+      // file drop handlers
+      allow_file_drop?: boolean
+      // layout configuration - 'auto' (default) adapts to element size, 'horizontal'/'vertical' forces layout
+      layout?: `auto` | Orientation
+      // structure viewer props (passed to Structure component)
+      structure_props?: ComponentProps<typeof Structure>
+      // plot props (passed to ScatterPlot component)
+      scatter_props?: ComponentProps<typeof ScatterPlot>
+      // histogram props (passed to Histogram component, excluding series which is handled separately)
+      histogram_props?: Omit<ComponentProps<typeof Histogram>, `series`>
+      // spinner props (passed to Spinner component)
+      spinner_props?: ComponentProps<typeof Spinner>
+      // custom snippets for additional UI elements
+      trajectory_controls?: Snippet<[ControlsProps]>
+      // Custom error snippet for advanced error handling
+      error_snippet?: Snippet<[{ error_msg: string; on_dismiss: () => void }]>
+      // Controls visibility configuration.
+      // - 'always': controls always visible
+      // - 'hover': controls visible on component hover (default)
+      // - 'never': controls never visible
+      // - object: { mode, hidden, style } for fine-grained control
+      // Control names: 'filename', 'nav', 'step', 'fps', 'info-pane', 'export-pane', 'view-mode', 'fullscreen'
+      show_controls?: ShowControlsProp
+      // show/hide the fullscreen button
+      fullscreen_toggle?: FullscreenToggleProp
+      // automatically start playing when trajectory data is loaded
+      auto_play?: boolean
+      // display mode: 'structure+scatter' (default), 'structure' (only structure), 'scatter' (only scatter), 'histogram' (only histogram), 'structure+histogram' (structure with histogram)
+      display_mode?:
+        | `structure+scatter`
+        | `structure`
+        | `scatter`
+        | `histogram`
+        | `structure+histogram`
+      // step labels configuration for slider
+      // - positive number: number of evenly spaced ticks
+      // - negative number: spacing between ticks (e.g. -10 = every 10th step)
+      // - array: exact step indices to label
+      // - undefined: no labels
+      step_labels?: number | number[]
+      // visible properties - bindable array of property keys currently shown in the plot
+      // - controls which trajectory properties are plotted (e.g. ['energy', 'volume', 'force_max'])
+      // - bindable: reflects current visibility state and can be used for external control
+      // - if not provided, uses default visible properties (energy, force_max, stress_frobenius)
+      // - if specified properties don't exist in data, falls back to automatic selection
+      visible_properties?: string[]
+      // custom labels for trajectory properties - maps property keys to display labels
+      // - e.g. {energy: 'Total Energy', volume: 'Cell Volume', force_max: 'Max Force'}
+      // - merged with built-in trajectory_property_config
+      ELEM_PROPERTY_LABELS?: Record<string, string>
+      fps_range?: Vec2 // allowed FPS range [min_fps, max_fps]
+      fps?: number // frame rate for playback
+      // Loading options for large files
+      loading_options?: LoadingOptions
+      // Map LAMMPS atom types to element symbols (e.g. {1: 'Na', 2: 'Cl'})
+      atom_type_mapping?: AtomTypeMapping
+      // Disable plot skimming (mouse over plot doesn't update structure/step slider)
+      plot_skimming?: boolean
+      // bindable: true while the pointer is over the viewer (drives hover-scoped shortcuts)
+      hovered?: boolean
+      // bindable: whether the (structure) controls pane is currently open
+      controls_open?: boolean
+      // bindable: whether the trajectory info pane is currently open
+      info_pane_open?: boolean
+      // bindable: top-level wrapper element
+      wrapper?: HTMLDivElement
+      // bindable: fullscreen state
+      fullscreen?: boolean
+    } = $props()
 
   let dragover = $state(false)
   let loading = $state(false)
@@ -193,22 +209,22 @@
   let parse_warning_msg = $state<string | undefined>(undefined)
   $effect(() => {
     const warnings = trajectory?.metadata?.parse_warnings
-    parse_warning_msg = Array.isArray(warnings) && warnings.length > 0
-      ? `${warnings.length} parse warning${warnings.length > 1 ? `s` : ``}: ${
-        warnings.join(`; `)
-      }`
-      : undefined
+    parse_warning_msg =
+      Array.isArray(warnings) && warnings.length > 0
+        ? `${warnings.length} parse warning${warnings.length > 1 ? `s` : ``}: ${warnings.join(
+            `; `,
+          )}`
+        : undefined
   })
   let is_playing = $state(false)
-  let play_interval: ReturnType<typeof setInterval> | undefined = $state(undefined)
+  // requestAnimationFrame handle for the playback loop (rAF auto-pauses in background tabs and
+  // self-throttles, unlike setInterval which drifts and queues work when a frame render overruns)
+  let play_raf: number | undefined
 
   // Ensure fps is within the allowed range
   $effect(() => {
-    if (fps < fps_range[0]) {
-      fps = fps_range[0]
-    } else if (fps > fps_range[1]) {
-      fps = fps_range[1]
-    }
+    const clamped = Math.max(fps_range[0], Math.min(fps_range[1], fps))
+    if (clamped !== fps) fps = clamped
   })
   let current_filename = $state<string | undefined>(undefined)
   let current_file_path = $state<string | null>(null)
@@ -218,6 +234,9 @@
   let element_size = $state({ width: 0, height: 0 })
   let filename_copied = $state(false)
   let orig_data = $state<string | ArrayBuffer | null>(null)
+  let data_url_load_id = 0
+  let loaded_data_url: string | undefined
+  let url_owned_trajectory: TrajectoryType | undefined
 
   let controls_config = $derived(normalize_show_controls(show_controls))
 
@@ -232,13 +251,26 @@
   })
 
   // Get total frame count (supports both regular and indexed trajectories)
-  let total_frames = $derived(
-    trajectory?.total_frames || trajectory?.frames.length || 0,
-  )
+  let total_frames = $derived(trajectory?.total_frames || trajectory?.frames.length || 0)
+
+  // Clamp out-of-range step indices (e.g. an initial current_step_idx of
+  // Number.MAX_SAFE_INTEGER means "jump to the last frame", used by hosts
+  // restoring viewer position across trajectory reloads). Hosts are notified
+  // of the correction so their recorded position matches the shown frame.
+  $effect(() => {
+    if (total_frames > 0 && current_step_idx > total_frames - 1) {
+      current_step_idx = total_frames - 1
+      notify_step_change()
+    } else if (current_step_idx < 0) {
+      current_step_idx = 0
+      notify_step_change()
+    }
+  })
 
   // Current frame - load on demand for indexed trajectories
   let current_frame = $state<TrajectoryFrame | null>(null)
   let frame_load_request_id = 0
+  let frame_load_timeout: ReturnType<typeof setTimeout> | undefined
 
   // Auto-play when trajectory changes (handles both props and file loading)
   $effect(() => {
@@ -252,8 +284,10 @@
     if (trajectory && current_step_idx >= 0 && current_step_idx < total_frames) {
       if (trajectory.frame_loader) {
         // Load frame on demand (works for both indexed files and external streaming)
-        load_frame_on_demand(current_step_idx)
+        current_frame = null
+        schedule_frame_load_on_demand(current_step_idx)
       } else {
+        clear_frame_load_timeout()
         // Use in-memory frame for regular trajectories
         current_frame = trajectory.frames[current_step_idx] || null
       }
@@ -262,11 +296,175 @@
     }
   })
 
+  // LRU cache of decoded frames (keyed to the current trajectory) so scrub/playback over
+  // indexed/streaming trajectories avoids re-reading frames and prefetch can warm upcoming ones.
+  // Capped by frame count AND a total-atom budget (cache many tiny frames or few huge ones).
+  const FRAME_CACHE_MAX = 64
+  const FRAME_CACHE_MAX_ATOMS = 200_000
+  let frame_cache = new Map<number, TrajectoryFrame>()
+  let frame_cache_owner: TrajectoryType | undefined
+  // Frames currently being read (direct or prefetch) so we don't kick off duplicate loads
+  const inflight_frames = new Set<number>()
+  let streaming_file_path = $derived(
+    trajectory?.metadata?.streaming_file_path as string | undefined,
+  )
+  let plot_metadata_loading = $derived(trajectory?.metadata?.plot_metadata_loading === true)
+
+  const clear_frame_load_timeout = () => {
+    if (frame_load_timeout) clearTimeout(frame_load_timeout)
+    frame_load_timeout = undefined
+  }
+
+  const skip_stale_url_stream = () =>
+    Boolean(data_url && loaded_data_url && data_url !== loaded_data_url)
+
+  // Replace the trajectory with an updated copy, keeping URL ownership if it applied.
+  // No-ops while a data_url switch is in flight so stale streams can't mutate the old model.
+  const update_trajectory = (updates: Partial<TrajectoryType>) => {
+    if (!trajectory || skip_stale_url_stream()) return
+    const preserves_url_ownership = trajectory === url_owned_trajectory
+    trajectory = { ...trajectory, ...updates }
+    if (preserves_url_ownership) url_owned_trajectory = trajectory
+  }
+
+  const merge_plot_metadata = (batch: TrajectoryMetadata[]) => {
+    if (batch.length === 0) return
+    update_trajectory({ plot_metadata: [...(trajectory?.plot_metadata ?? []), ...batch] })
+  }
+
+  const finish_plot_metadata_loading = () =>
+    update_trajectory({
+      metadata: { ...trajectory?.metadata, plot_metadata_loading: false },
+    })
+
+  onMount(() => {
+    const handle_plot_metadata_stream = (event: MessageEvent<PlotMetadataStreamMessage>) => {
+      // Global listener: other code posts arbitrary messages (including null data)
+      if (typeof event.data !== `object` || event.data === null) return
+      const { command, file_path, is_complete, plot_metadata } = event.data
+      if (command !== `plot_metadata_stream` || file_path !== streaming_file_path) return
+      if (Array.isArray(plot_metadata)) merge_plot_metadata(plot_metadata)
+      if (is_complete) finish_plot_metadata_loading()
+    }
+    globalThis.addEventListener(`message`, handle_plot_metadata_stream)
+    return () => {
+      globalThis.removeEventListener(`message`, handle_plot_metadata_stream)
+      clear_frame_load_timeout()
+    }
+  })
+
+  // Reset per-trajectory caches when the trajectory changes (frames belong to the old one)
+  function ensure_frame_cache_owner() {
+    if (frame_cache_owner !== trajectory) {
+      frame_cache = new Map()
+      inflight_frames.clear()
+      frame_cache_owner = trajectory
+    }
+  }
+  // Sync LRU read (delete + re-insert refreshes recency); undefined on miss
+  function cache_get(frame_idx: number): TrajectoryFrame | undefined {
+    const hit = frame_cache.get(frame_idx)
+    if (!hit) return undefined
+    frame_cache.delete(frame_idx)
+    frame_cache.set(frame_idx, hit)
+    return hit
+  }
+  // Sync LRU write, evicting oldest entries until under both the frame and atom budgets
+  function cache_put(frame_idx: number, frame: TrajectoryFrame) {
+    frame_cache.set(frame_idx, frame)
+    let total_atoms = 0
+    for (const cached of frame_cache.values())
+      total_atoms += cached.structure?.sites?.length ?? 0
+    while (
+      frame_cache.size > 1 &&
+      (frame_cache.size > FRAME_CACHE_MAX || total_atoms > FRAME_CACHE_MAX_ATOMS)
+    ) {
+      const oldest = frame_cache.keys().next().value
+      if (oldest === undefined) break
+      total_atoms -= frame_cache.get(oldest)?.structure?.sites?.length ?? 0
+      frame_cache.delete(oldest)
+    }
+  }
+
+  // Warm the next couple of frames in the background (fire-and-forget) so playback/forward-scrub
+  // doesn't stall on a serial per-frame read; skips frames already cached or in flight
+  function prefetch_frames(from_idx: number) {
+    const frame_loader = trajectory?.frame_loader
+    if (!frame_loader) return
+    if (trajectory?.indexed_frames && trajectory.indexed_frames.length < total_frames) return
+    const owner = trajectory
+    for (const ahead of [1, 2]) {
+      const idx = from_idx + ahead
+      if (idx >= total_frames || frame_cache.has(idx) || inflight_frames.has(idx)) continue
+      inflight_frames.add(idx)
+      frame_loader
+        .load_frame(orig_data || ``, idx)
+        .then((frame) => {
+          if (frame && frame_cache_owner === owner) cache_put(idx, frame)
+        })
+        .catch(() => {})
+        .finally(() => inflight_frames.delete(idx))
+    }
+  }
+
+  function use_cached_or_in_memory_frame(
+    load_trajectory: TrajectoryType,
+    frame_idx: number,
+  ): boolean {
+    const cached = cache_get(frame_idx)
+    if (cached) {
+      current_frame = cached
+      prefetch_frames(frame_idx)
+      return true
+    }
+
+    const in_memory_frame = load_trajectory.frames[frame_idx]
+    if (in_memory_frame) {
+      cache_put(frame_idx, in_memory_frame)
+      current_frame = in_memory_frame
+      prefetch_frames(frame_idx)
+      return true
+    }
+    return false
+  }
+
+  function schedule_frame_load_on_demand(frame_idx: number) {
+    const load_trajectory = trajectory
+    if (!load_trajectory?.frame_loader) return
+    ensure_frame_cache_owner()
+    frame_load_request_id++
+
+    if (use_cached_or_in_memory_frame(load_trajectory, frame_idx)) return
+
+    clear_frame_load_timeout()
+    // Debouncing during playback would keep resetting the timer at fps above
+    // ~1000/FRAME_LOAD_DEBOUNCE_MS and stall uncached streamed frames entirely.
+    // untrack: this runs synchronously inside the step-change $effect, so tracking
+    // is_playing would re-run that effect on every play/pause toggle and kick off
+    // duplicate loads for a frame that's already in flight.
+    if (untrack(() => is_playing)) {
+      void load_frame_on_demand(frame_idx)
+      return
+    }
+    const request_id = frame_load_request_id
+    frame_load_timeout = setTimeout(() => {
+      frame_load_timeout = undefined
+      if (
+        request_id === frame_load_request_id &&
+        trajectory === load_trajectory &&
+        current_step_idx === frame_idx
+      ) {
+        load_frame_on_demand(frame_idx)
+      }
+    }, FRAME_LOAD_DEBOUNCE_MS)
+  }
+
   // Load frame on demand - works for both indexed files and external streaming
   async function load_frame_on_demand(frame_idx: number) {
     const load_trajectory = trajectory
     const frame_loader = load_trajectory?.frame_loader
     if (!load_trajectory || !frame_loader) return
+    ensure_frame_cache_owner()
 
     const request_id = ++frame_load_request_id
     const request_is_current = () =>
@@ -274,13 +472,18 @@
       trajectory === load_trajectory &&
       current_step_idx === frame_idx
 
+    if (use_cached_or_in_memory_frame(load_trajectory, frame_idx)) return
+    inflight_frames.add(frame_idx) // let concurrent prefetch skip the frame we're already loading
     try {
       const frame = await frame_loader.load_frame(
-        orig_data || ``, // Use original_data for indexed files, empty string for external streaming
+        orig_data || ``, // original_data for indexed files, empty string for external streaming
         frame_idx,
       )
+      // cache the decoded frame even if it arrived stale (still valid data for that index)
+      if (frame && frame_cache_owner === load_trajectory) cache_put(frame_idx, frame)
       if (!request_is_current()) return
       current_frame = frame
+      prefetch_frames(frame_idx) // warm upcoming frames for smooth playback/scrub
     } catch (error) {
       if (!request_is_current()) return
       console.error(`Failed to load frame ${frame_idx}:`, error)
@@ -292,14 +495,22 @@
         step_idx: frame_idx,
         frame_count: total_frames,
       })
+    } finally {
+      inflight_frames.delete(frame_idx)
     }
   }
 
-  // Current frame structure for display
-  let current_structure = $derived(current_frame?.structure)
+  // Current frame structure for display. Holds the last resolved structure so the 3D
+  // view doesn't blank while an uncached frame loads on demand (current_frame is nulled
+  // during loads to keep the info pane from showing the previous frame's data).
+  let current_structure = $state<AnyStructure | undefined>(undefined)
+  $effect(() => {
+    if (current_frame?.structure) current_structure = current_frame.structure
+    else if (!trajectory) current_structure = undefined
+  })
 
   // Track hidden elements (persists across frame changes)
-  let hidden_elements = $state(new Set<ElementSymbol>())
+  let hidden_elements = $state(new SvelteSet<ElementSymbol>())
 
   let step_label_positions = $derived.by((): number[] => {
     if (!step_labels || total_frames <= 1) return []
@@ -310,11 +521,14 @@
 
     if (typeof step_labels === `number`) {
       if (step_labels > 0) {
-        return scaleLinear().domain([0, total_frames - 1]).nice()
+        return scaleLinear()
+          .domain([0, total_frames - 1])
+          .nice()
           .ticks(Math.min(step_labels, total_frames))
           .map((tick) => Math.round(tick))
-          .filter((tick, idx, ticks) =>
-            tick >= 0 && tick < total_frames && ticks.indexOf(tick) === idx
+          .filter(
+            (tick, idx, ticks) =>
+              tick >= 0 && tick < total_frames && ticks.indexOf(tick) === idx,
           )
       }
       if (step_labels < 0) {
@@ -335,11 +549,13 @@
   let extended_config = $derived.by(() => {
     if (!ELEM_PROPERTY_LABELS) return trajectory_property_config
 
-    const custom_config: Record<string, { label: string; unit: string }> = {}
+    const custom_config: Record<string, TrajPropertyConfig> = {}
     for (const [key, label] of Object.entries(ELEM_PROPERTY_LABELS)) {
-      const existing = trajectory_property_config[key] ||
-        trajectory_property_config[key.toLowerCase()]
-      custom_config[key] = { label, unit: existing?.unit || `` }
+      const existing =
+        trajectory_property_config[key] || trajectory_property_config[key.toLowerCase()]
+      // Spread the existing config so fields like axis_group survive the
+      // label override (losing axis_group would break dedicated-axis grouping)
+      custom_config[key] = { ...existing, label, unit: existing?.unit || `` }
     }
     return { ...trajectory_property_config, ...custom_config }
   })
@@ -392,7 +608,8 @@
 
     // Only update if changed (use untrack to avoid circular dependency)
     const current = untrack(() => visible_properties) || []
-    const has_changed = visible_keys.length !== current.length ||
+    const has_changed =
+      visible_keys.length !== current.length ||
       !visible_keys.every((key, idx) => key === current[idx])
 
     if (has_changed) {
@@ -407,82 +624,74 @@
     plot_series = toggle_series_visibility(plot_series, series_idx)
   }
 
+  // Streamed trajectories plot sampled per-frame metadata, so x values are frame numbers
+  let x_axis_quantity = $derived(trajectory?.plot_metadata ? `Frame` : `Step`)
   let x_axis = $derived({
-    label: `Step`,
-    format: `.3~s`,
+    label: x_axis_quantity,
+    // ~g (not ~s) so sub-1 values read as 0.8 rather than SI "800m"; integer steps stay clean
+    format: `~g`,
     ticks: step_label_positions,
   })
   // Generate axis labels based on first visible series on each axis
   let y_axis_labels = $derived(generate_axis_labels(plot_series))
+  // Axes whose visible series are all-positive and span many decades (e.g. SCF
+  // convergence residuals) default to log scale instead of a linear hockey stick
+  let y_axis_scale_types = $derived(generate_axis_scale_types(plot_series))
   let y_axis = $derived({
     label: y_axis_labels.y1,
-    format: `.2~s`,
+    format: `~g`,
     label_shift: { y: 10 },
+    scale_type: y_axis_scale_types.y1,
   })
   let y2_axis = $derived({
     label: y_axis_labels.y2,
-    format: `.2~s`,
+    format: `~g`,
     label_shift: { y: 80 },
+    scale_type: y_axis_scale_types.y2,
   })
-
   // hide plot if all plotted values are constant (no variation)
   let show_plot = $derived(
-    display_mode !== `structure` && !should_hide_plot(trajectory, plot_series),
+    display_mode !== `structure` &&
+      (plot_metadata_loading || !should_hide_plot(trajectory, plot_series)),
   )
-
-  // Determine what to show based on display mode
   let show_structure = $derived(![`scatter`, `histogram`].includes(display_mode))
-  let actual_show_plot = $derived(display_mode !== `structure` && show_plot)
 
   // Check if there are any Y2 series to determine padding
-  let has_y2_series = $derived(
-    plot_series.some((srs) => srs.y_axis === `y2` && srs.visible),
-  )
-
-  // Step navigation functions
+  let has_y2_series = $derived(plot_series.some((srs) => srs.y_axis === `y2` && srs.visible))
+  // Report the current step to on_step_change consumers. Also wired to the step
+  // slider/number input whose bind:value bypasses the navigation functions
+  // below — those handlers pass the event target's value explicitly because
+  // bind:value may not have written the binding yet when oninput fires.
+  function notify_step_change(step_idx: number = current_step_idx) {
+    if (!trajectory || !Number.isFinite(step_idx)) return
+    const last_frame = Math.max(total_frames - 1, 0)
+    const clamped_step = Math.min(Math.max(Math.round(step_idx), 0), last_frame)
+    on_step_change?.({
+      trajectory,
+      step_idx: clamped_step,
+      frame_count: total_frames,
+      frame: current_frame || undefined,
+    })
+  }
+  // Step navigation functions (streaming frame loading is handled by the reactive effect)
   function next_step() {
     if (current_step_idx < total_frames - 1) {
       current_step_idx++
-      // Streaming frame loading handled by reactive effect
-      if (trajectory) {
-        on_step_change?.({
-          trajectory,
-          step_idx: current_step_idx,
-          frame_count: total_frames,
-          frame: current_frame || undefined,
-        })
-      }
+      notify_step_change()
     }
   }
 
   function prev_step() {
     if (current_step_idx > 0) {
       current_step_idx--
-      // Streaming frame loading handled by reactive effect
-      if (trajectory) {
-        on_step_change?.({
-          trajectory,
-          step_idx: current_step_idx,
-          frame_count: total_frames,
-          frame: current_frame || undefined,
-        })
-      }
+      notify_step_change()
     }
   }
 
   function go_to_step(idx: number) {
     if (idx >= 0 && idx < total_frames) {
       current_step_idx = idx
-      // Note: streaming frame loading is handled by reactive effect
-      // Handle callbacks for both traditional and streaming modes
-      if (trajectory) {
-        on_step_change?.({
-          trajectory,
-          step_idx: current_step_idx,
-          frame_count: total_frames,
-          frame: current_frame || undefined,
-        })
-      }
+      notify_step_change()
     }
   }
 
@@ -501,7 +710,7 @@
       reader.addEventListener(`error`, () => reject(new Error(`Failed to read file`)))
 
       // Read as text for text-based formats, binary for others
-      if (file.name.toLowerCase().match(/\.(xyz|json|extxyz|lammpstrj)$/)) {
+      if (/\.(?:xyz|json|extxyz|lammpstrj)$/.test(file.name.toLowerCase())) {
         reader.readAsText(file)
       } else reader.readAsArrayBuffer(file)
     })
@@ -528,44 +737,50 @@
       })
     }
   }
-  $effect(() => { // Effect to manage playback interval
-    // Only watch is_playing and frame_rate_ms, not play_interval itself
-    const playing = is_playing
-    const rate_ms = 1000 / fps
-
-    // Read current interval once (untrack to avoid circular dependency)
-    const current_interval = untrack(() => play_interval)
-    if (playing) {
-      // Clear existing interval if it exists
-      if (current_interval !== undefined) clearInterval(current_interval)
-
-      // Create new interval with current frame rate
-      play_interval = setInterval(() => {
-        if (current_step_idx >= total_frames - 1) {
-          if (trajectory) {
-            on_end?.({
-              trajectory,
-              step_idx: current_step_idx,
-              frame_count: total_frames,
-              frame: current_frame || undefined,
-            })
-          }
-          go_to_step(0) // Loop back to 1st step
-          if (trajectory) {
-            on_loop?.({ trajectory, frame_count: total_frames })
-          }
-        } else next_step()
-      }, rate_ms)
-    } else if (current_interval !== undefined) {
-      // Clear interval when not playing
-      clearInterval(current_interval)
-      play_interval = undefined
-    }
-  })
+  // Advance one frame (or loop back to start), firing the matching callbacks
+  function advance_playback() {
+    if (current_step_idx >= total_frames - 1) {
+      if (trajectory) {
+        on_end?.({
+          trajectory,
+          step_idx: current_step_idx,
+          frame_count: total_frames,
+          frame: current_frame || undefined,
+        })
+      }
+      go_to_step(0) // loop back to 1st step
+      if (trajectory) on_loop?.({ trajectory, frame_count: total_frames })
+    } else next_step()
+  }
 
-  // Cleanup interval on component destroy
-  $effect(() => () => {
-    if (play_interval !== undefined) clearInterval(play_interval)
+  // rAF playback loop. Only tracks `is_playing`; `fps`/`current_step_idx`/`total_frames` are read
+  // live in the untracked tick, so changing fps mid-play retargets the cadence without restarting.
+  // Clamped delta + at most one advance per tick lets a background tab resume cleanly (no jump),
+  // but also caps playback at the ~60fps refresh rate (= default fps_range max; higher won't help).
+  $effect(() => {
+    if (!is_playing) return
+    let last = performance.now()
+    let accumulated_ms = 0
+    const tick = (now: number) => {
+      // stop if the trajectory went away or is no longer animatable (e.g. swapped mid-play)
+      if (!trajectory || total_frames <= 1) {
+        is_playing = false
+        return
+      }
+      accumulated_ms += Math.min(now - last, 250)
+      last = now
+      const step_ms = 1000 / Math.max(0.1, fps)
+      if (accumulated_ms >= step_ms) {
+        accumulated_ms = Math.min(accumulated_ms - step_ms, step_ms)
+        advance_playback()
+      }
+      play_raf = requestAnimationFrame(tick)
+    }
+    play_raf = requestAnimationFrame(tick)
+    return () => {
+      if (play_raf !== undefined) cancelAnimationFrame(play_raf)
+      play_raf = undefined
+    }
   })
 
   // Handle internal file format drops
@@ -582,10 +797,7 @@
           const array_buffer = await response.arrayBuffer()
           await load_trajectory_data(array_buffer, file_info.name)
         } else {
-          console.warn(
-            `Binary file without ArrayBuffer or blob URL:`,
-            file_info.name,
-          )
+          console.warn(`Binary file without ArrayBuffer or blob URL:`, file_info.name)
         }
       } else {
         await load_trajectory_data(file_info.content, file_info.name)
@@ -607,26 +819,23 @@
 
     try {
       // Check for our custom internal file format first
-      const internal_data = event.dataTransfer?.getData(
-        `application/x-matterviz-file`,
-      )
+      const internal_data = event.dataTransfer?.getData(`application/x-matterviz-file`)
       if (internal_data) {
         const handled = await handle_internal_file_drop(internal_data)
         if (handled) return
       }
 
       // Handle URL-based files (e.g. from FilePicker)
-      const handled = await handle_url_drop(event, async (content, filename) => {
-        current_filename = filename
-        file_size = content instanceof ArrayBuffer
-          ? content.byteLength
-          : new Blob([content]).size
-        await load_trajectory_data(content, filename)
-      }).catch(() => false)
-
-      if (handled) {
-        return
-      }
+      const handled = await io
+        .handle_url_drop(event, async (content, filename) => {
+          current_filename = filename
+          file_size =
+            content instanceof ArrayBuffer ? content.byteLength : new Blob([content]).size
+          await load_trajectory_data(content, filename)
+        })
+        .catch(() => false)
+
+      if (handled) return
 
       // Handle file system drops with optimized large file support
       const file = event.dataTransfer?.files[0]
@@ -658,33 +867,58 @@
     }
   }
 
-  $effect(() => { // Load trajectory from URL when data_url is provided
-    if (data_url && !trajectory) {
-      loading = true
-      error_msg = null
-
-      load_from_url(data_url, async (content, filename) => {
-        current_filename = filename
-        file_size = content instanceof ArrayBuffer
-          ? content.byteLength
-          : new Blob([content]).size
-        await load_trajectory_data(content, filename)
+  // Load trajectory from URL when data_url is provided. Track the model produced by
+  // this effect so caller-owned trajectory props keep precedence while URL-owned
+  // models can reload when data_url changes.
+  $effect(() => {
+    const requested_url = data_url
+    const current_trajectory = trajectory
+    const caller_owns_trajectory = Boolean(
+      current_trajectory && current_trajectory !== url_owned_trajectory,
+    )
+    if (!requested_url || caller_owns_trajectory) {
+      loaded_data_url = undefined
+      url_owned_trajectory = undefined
+      return
+    }
+    if (loaded_data_url === requested_url) return
+
+    const load_id = ++data_url_load_id
+    const is_current = () => load_id === data_url_load_id
+    loading = true
+    error_msg = null
+
+    io.load_from_url(requested_url, async (content, filename) => {
+      if (!is_current()) return
+      current_filename = filename
+      file_size =
+        content instanceof ArrayBuffer ? content.byteLength : new Blob([content]).size
+      await load_trajectory_data(content, filename, {
+        on_trajectory_loaded: (loaded_trajectory) => {
+          if (!is_current()) return
+          url_owned_trajectory = loaded_trajectory
+          loaded_data_url = requested_url
+        },
+        should_commit: is_current,
       })
-        .then(() => {
-          loading = false
-        })
-        .catch((err: Error) => {
-          console.error(`Failed to load trajectory from URL:`, err)
-          error_msg = `Failed to load trajectory: ${err.message}`
-          current_filename = undefined
-          file_size = undefined
-          loading = false
-          on_error?.({
-            error_msg,
-            filename: current_filename || undefined,
-            file_size: file_size || undefined,
-          })
-        })
+    })
+      .catch((err: Error) => {
+        if (!is_current()) return
+        console.error(`Failed to load trajectory from URL:`, err)
+        error_msg = `Failed to load trajectory: ${err.message}`
+        current_filename = undefined
+        file_size = undefined
+        on_error?.({ error_msg, filename: io.basename_from_url(requested_url) })
+      })
+      .finally(() => {
+        if (is_current()) loading = false
+      })
+
+    return () => {
+      if (is_current()) {
+        data_url_load_id += 1
+        loading = false
+      }
     }
   })
 
@@ -693,87 +927,82 @@
     on_frame_rate_change?.({ trajectory, fps })
   })
 
-  async function load_trajectory_data(data: string | ArrayBuffer, filename: string) {
+  async function load_trajectory_data(
+    data: string | ArrayBuffer,
+    filename: string,
+    options: {
+      on_trajectory_loaded?: (loaded_trajectory: TrajectoryType) => void
+      should_commit?: () => boolean
+    } = {},
+  ) {
+    const { on_trajectory_loaded, should_commit = () => true } = options
     loading = true
     error_msg = null
     parsing_progress = null
 
     // Reset previous loading state
     orig_data = null
+    const file_size_bytes =
+      data instanceof ArrayBuffer ? data.byteLength : new Blob([data]).size
 
     try {
       const data_size = data instanceof ArrayBuffer ? data.byteLength : data.length
 
       // Determine loading strategy based on file size
-      const bin_file_threshold = loading_options.bin_file_threshold ??
-        MAX_BIN_FILE_SIZE
-      const text_file_threshold = loading_options.text_file_threshold ??
-        MAX_TEXT_FILE_SIZE
-      if (
+      const bin_file_threshold = loading_options.bin_file_threshold ?? MAX_BIN_FILE_SIZE
+      const text_file_threshold = loading_options.text_file_threshold ?? MAX_TEXT_FILE_SIZE
+      const is_large_file =
         (data instanceof ArrayBuffer && data_size > bin_file_threshold) ||
         (typeof data === `string` && data_size > text_file_threshold)
-      ) { // Large files: Use indexed loading
-        await load_with_indexing(data, filename)
-      } else {
-        // Small files: Use regular loading
-        const merged_options = { ...loading_options, atom_type_mapping }
-        trajectory = await parse_trajectory_async(data, filename, (progress) => {
-          parsing_progress = progress
-        }, merged_options)
-      }
+
+      // Large files get indexed loading by default (loading_options can override)
+      const parsed_trajectory = await parse_trajectory_async(
+        data,
+        filename,
+        (progress) => {
+          if (should_commit()) parsing_progress = progress
+        },
+        {
+          ...(is_large_file ? { use_indexing: true } : {}),
+          ...loading_options,
+          atom_type_mapping,
+        },
+      )
+      if (!should_commit()) return
+      trajectory = parsed_trajectory
+      if (trajectory) on_trajectory_loaded?.(trajectory)
+      // Keep original data only when parsing attached a frame_loader for on-demand loads.
+      // Direct-parse fallbacks load all frames upfront, so retaining a duplicate wastes memory.
+      orig_data = trajectory?.frame_loader ? data : null
 
       current_step_idx = 0
       current_filename = filename
-
-      const file_size_bytes = data instanceof ArrayBuffer
-        ? data.byteLength
-        : new Blob([data]).size
-      on_file_load?.({ // emit file load event
-        trajectory,
-        frame_count: trajectory?.frames.length ?? 0,
-        total_atoms: trajectory?.frames[0]?.structure.sites.length ?? 0,
+      file_size = file_size_bytes
+
+      const loaded_trajectory = trajectory
+      on_file_load?.({
+        // emit file load event
+        trajectory: loaded_trajectory,
+        frame_count: loaded_trajectory?.frames.length ?? 0,
+        total_atoms: loaded_trajectory?.frames[0]?.structure.sites.length ?? 0,
         filename,
         file_size: file_size_bytes,
       })
     } catch (err) {
+      if (!should_commit()) return
       const unsupported_message = get_unsupported_format_message(
         filename,
         typeof data === `string` ? data : ``,
       )
       error_msg = unsupported_message || `Failed to parse trajectory: ${err}`
+      on_error?.({ error_msg, filename, file_size: file_size_bytes })
       current_filename = undefined
       file_size = undefined
-
-      on_error?.({ // emit error event
-        error_msg,
-        filename: current_filename || undefined,
-        file_size: file_size || undefined,
-      })
     } finally {
-      parsing_progress = null
-      loading = false
-    }
-  }
-
-  // Load using indexed parsing for large files
-  async function load_with_indexing(data: string | ArrayBuffer, filename: string) {
-    try { // Use indexed parsing for efficient large file handling
-      const merged_options = {
-        use_indexing: true,
-        ...loading_options,
-        atom_type_mapping,
+      if (should_commit()) {
+        parsing_progress = null
+        loading = false
       }
-      trajectory = await parse_trajectory_async(data, filename, (progress) => {
-        parsing_progress = progress
-      }, merged_options)
-
-      // Keep original data for on-demand frame loads only when indexed parsing attached a
-      // frame_loader. Direct-parse fallbacks (e.g. large JSON or extensionless blob:
-      // filenames) load all frames upfront, so retaining a full duplicate payload wastes memory.
-      orig_data = trajectory?.frame_loader ? data : null
-    } catch (error) {
-      console.error(`Indexed loading failed:`, error)
-      throw error
     }
   }
 
@@ -808,8 +1037,7 @@
     // Don't handle shortcuts if user is typing in an input field (but allow if it's our step input and not focused)
     const target = event.target instanceof HTMLElement ? event.target : null
     const is_step_input = target?.classList.contains(`step-input`) ?? false
-    const is_input_focused =
-      target?.tagName === `INPUT` || target?.tagName === `TEXTAREA`
+    const is_input_focused = target?.tagName === `INPUT` || target?.tagName === `TEXTAREA`
 
     // Skip if typing in an input that's not our step input
     if (is_input_focused && !is_step_input) return false
@@ -848,7 +1076,7 @@
       go_to_step(Math.max(0, current_step_idx - 25))
     } else if (event.key === `PageDown`) {
       go_to_step(Math.min(total_frames - 1, current_step_idx + 25))
-    } // Interface shortcuts
+    }  // Interface shortcuts
     else if (event.key === `f` && fullscreen_toggle) toggle_fullscreen(wrapper)
     // 'i' key handled by the TrajectoryInfoPane's built-in toggle
     // Playback speed shortcuts (only when playing)
@@ -858,14 +1086,14 @@
     } else if (event.key === `-` && is_playing) {
       fps = Math.max(fps_range[0], fps - 0.2)
       on_frame_rate_change?.({ trajectory, fps })
-    } // System shortcuts
+    }  // System shortcuts
     else if (event.key === `Escape`) {
       if (document.fullscreenElement) document.exitFullscreen()
       else if (view_mode_dropdown_open) view_mode_dropdown_open = false
       // Escape key for info pane handled by DraggablePane
-    } // Number keys 0-9 - jump to percentage of trajectory
+    }  // Number keys 0-9 - jump to percentage of trajectory
     else if (event.key >= `0` && event.key <= `9`) {
-      go_to_step(Math.floor((parseInt(event.key, 10) / 10) * (total_frames - 1)))
+      go_to_step(Math.floor((Number(event.key) / 10) * (total_frames - 1)))
     } else handled = false
 
     return handled
@@ -889,8 +1117,12 @@
 
 <div
   class:dragover
-  class:active={is_playing || structure_info_open || controls_open ||
-  scatter_controls.open || trajectory_export_open || info_pane_open}
+  class:active={is_playing ||
+    structure_info_open ||
+    controls_open ||
+    scatter_controls.open ||
+    trajectory_export_open ||
+    info_pane_open}
   bind:this={wrapper}
   bind:clientWidth={element_size.width}
   bind:clientHeight={element_size.height}
@@ -900,13 +1132,17 @@
   onmouseenter={() => (hovered = true)}
   onmouseleave={() => (hovered = false)}
   ondrop={handle_file_drop}
-  {...drag_over_handlers({ allow: () => allow_file_drop, set_dragover: (over) => dragover = over })}
+  {...io.drag_over_handlers({
+    allow: () => allow_file_drop,
+    set_dragover: (over) => (dragover = over),
+  })}
   onclick={handle_click_outside}
   onkeydown={handle_and_prevent(onkeydown)}
   {...rest}
-  class="trajectory {actual_layout} {rest.class ?? ``}"
+  class={[`trajectory`, actual_layout, rest.class]}
   class:show-both-views={[`structure+scatter`, `structure+histogram`].includes(display_mode) &&
-  actual_show_plot && show_structure}
+    show_plot &&
+    show_structure}
 >
   {#if loading}
     {@const text = parsing_progress
@@ -918,11 +1154,7 @@
       {...spinner_props}
     />
   {:else if error_msg}
-    <TrajectoryError
-      {error_msg}
-      on_dismiss={() => (error_msg = null)}
-      {error_snippet}
-    />
+    <TrajectoryError {error_msg} on_dismiss={() => (error_msg = null)} {error_snippet} />
   {:else if trajectory}
     {#if parse_warning_msg}
       <StatusMessage
@@ -934,17 +1166,14 @@
     {/if}
     <!-- Trajectory Controls -->
     {#if controls_config.mode !== `never`}
-      <div
-        class="trajectory-controls {controls_config.class}"
-        style={controls_config.style}
-      >
+      <div class="trajectory-controls {controls_config.class}" style={controls_config.style}>
         {#if trajectory_controls}
           {@render trajectory_controls({
-        trajectory,
-        current_step_idx,
-        total_frames: total_frames,
-        on_step_change: go_to_step,
-      })}
+            trajectory,
+            current_step_idx,
+            total_frames: total_frames,
+            on_step_change: go_to_step,
+          })}
         {:else}
           {#if current_filename && controls_config.visible(`filename`)}
             <button
@@ -955,7 +1184,7 @@
                 if (current_filename) {
                   navigator.clipboard.writeText(current_filename)
                   filename_copied = true
-                  setTimeout(() => filename_copied = false, 1000)
+                  setTimeout(() => (filename_copied = false), 1000)
                 }
               }}
             >
@@ -963,7 +1192,7 @@
               {#if filename_copied}
                 <Icon
                   icon="Check"
-                  style="color: var(--success-color); position: absolute; right: 3pt; top: 50%; transform: translateY(-50%); font-size: 16px; animation: fade-in 0.1s; background: var(--surface-bg-hover); border-radius: 50%"
+                  style="--icon-size: 16px; color: var(--success-color); position: absolute; right: 3pt; top: 50%; transform: translateY(-50%); animation: fade-in 0.1s; background: var(--surface-bg-hover); border-radius: 50%; padding: 2px; box-sizing: content-box"
                 />
               {/if}
             </button>
@@ -975,14 +1204,16 @@
               <button
                 onclick={prev_step}
                 disabled={current_step_idx === 0 || is_playing}
-                title="Previous step"
+                title="Previous step (←) · Home: first · j: −10 · PageUp: −25"
               >
                 ⏮
               </button>
               <button
                 onclick={toggle_play}
                 disabled={total_frames <= 1}
-                title={is_playing ? `Pause playback` : `Play trajectory`}
+                title={`${
+                  is_playing ? `Pause` : `Play`
+                } (Space) · ←/→ step · 0-9 jump % · +/- speed · f fullscreen`}
                 class="play-button"
                 class:playing={is_playing}
               >
@@ -991,7 +1222,7 @@
               <button
                 onclick={next_step}
                 disabled={current_step_idx === total_frames - 1 || is_playing}
-                title="Next step"
+                title="Next step (→) · End: last · l: +10 · PageDown: +25"
               >
                 ⏭
               </button>
@@ -1006,6 +1237,7 @@
                 min="0"
                 max={total_frames - 1}
                 bind:value={current_step_idx}
+                oninput={(event) => notify_step_change(event.currentTarget.valueAsNumber)}
                 class="step-input"
                 title="Enter step number to jump to"
                 aria-label="Step input"
@@ -1018,15 +1250,15 @@
                   min="0"
                   max={total_frames - 1}
                   bind:value={current_step_idx}
+                  oninput={(event) => notify_step_change(event.currentTarget.valueAsNumber)}
                   class="step-slider"
                   title="Drag to navigate steps"
                 />
                 {#if step_label_positions.length > 0}
                   <div class="step-labels">
                     {#each step_label_positions as step_idx (step_idx)}
-                      {@const position_percent = total_frames > 1
-              ? (step_idx / (total_frames - 1)) * 100
-              : 0}
+                      {@const position_percent =
+                        total_frames > 1 ? (step_idx / (total_frames - 1)) * 100 : 0}
                       {@const adjusted_position = 1.5 + (position_percent * (100 - 2)) / 100}
                       <div class="step-tick" style:left="{adjusted_position}%"></div>
                       <div class="step-label" style:left="{adjusted_position}%">
@@ -1039,8 +1271,8 @@
             </div>
           {/if}
 
-          <!-- Frame rate control - only shown when playing -->
-          {#if is_playing && controls_config.visible(`fps`)}
+          <!-- Frame rate control: shown for any multi-frame trajectory so speed can be set before play -->
+          {#if total_frames > 1 && controls_config.visible(`fps`)}
             <label
               class="fps-section"
               style="font-size: 0.9em; display: flex; align-items: center; gap: 5pt; margin-inline: 6pt"
@@ -1052,7 +1284,7 @@
                 max={fps_range[1]}
                 bind:value={fps}
                 title="Frame rate: {format_num(fps, `.2~s`)} fps"
-                style="width: clamp(60px, 8cqw, 90px); accent-color: var(--accent-color)"
+                style="width: clamp(60px, 8cqw, 90px)"
               />
               <input
                 type="number"
@@ -1070,6 +1302,7 @@
             {#if trajectory && controls_config.visible(`info-pane`)}
               <TrajectoryInfoPane
                 {trajectory}
+                {current_frame}
                 {current_step_idx}
                 {current_filename}
                 {current_file_path}
@@ -1091,8 +1324,7 @@
               />
             {/if}
             <!-- Display mode dropdown -->
-            {#if plot_series.length > 0 &&
-          controls_config.visible(`view-mode`)}
+            {#if plot_series.length > 0 && controls_config.visible(`view-mode`)}
               <div class="view-mode-dropdown-wrapper">
                 <button
                   onclick={() => (view_mode_dropdown_open = !view_mode_dropdown_open)}
@@ -1102,40 +1334,21 @@
                   style="background-color: transparent; padding: 0"
                 >
                   <Icon
-                    icon={({
-                      structure: `Atom`,
-                      'structure+scatter': `TwoColumns`,
-                      'structure+histogram': `TwoColumns`,
-                      scatter: `ScatterPlot`,
-                      histogram: `Histogram`,
-                    } as const)[display_mode]}
+                    icon={(
+                      {
+                        structure: `Atom`,
+                        'structure+scatter': `TwoColumns`,
+                        'structure+histogram': `TwoColumns`,
+                        scatter: `ScatterPlot`,
+                        histogram: `Histogram`,
+                      } as const
+                    )[display_mode]}
                   />
                   <Icon icon={view_mode_dropdown_open ? `ArrowUp` : `ArrowDown`} />
                 </button>
                 {#if view_mode_dropdown_open}
                   <div class="view-mode-dropdown">
-                    {#each [
-              { mode: `structure`, icon: `Atom`, label: `Structure-only` },
-              {
-                mode: `structure+scatter`,
-                icon: `TwoColumns`,
-                label: `Structure + Scatter`,
-              },
-              {
-                mode: `structure+histogram`,
-                icon: `TwoColumns`,
-                label: `Structure + Histogram`,
-              },
-              { mode: `scatter`, icon: `ScatterPlot`, label: `Scatter-only` },
-              {
-                mode: `histogram`,
-                icon: `Histogram`,
-                label: `Histogram-only`,
-              },
-            ] as const as
-                      option
-                      (option.mode)
-                    }
+                    {#each [{ mode: `structure`, icon: `Atom`, label: `Structure-only` }, { mode: `structure+scatter`, icon: `TwoColumns`, label: `Structure + Scatter` }, { mode: `structure+histogram`, icon: `TwoColumns`, label: `Structure + Histogram` }, { mode: `scatter`, icon: `ScatterPlot`, label: `Scatter-only` }, { mode: `histogram`, icon: `Histogram`, label: `Histogram-only` }] as const as option (option.mode)}
                       <button
                         class="view-mode-option"
                         class:selected={display_mode === option.mode}
@@ -1170,7 +1383,7 @@
 
     <div
       class="content-area"
-      class:hide-plot={!actual_show_plot}
+      class:hide-plot={!show_plot}
       class:hide-structure={!show_structure}
       class:show-both={[`structure+scatter`, `structure+histogram`].includes(display_mode)}
       class:show-structure-only={display_mode === `structure`}
@@ -1191,8 +1404,12 @@
         />
       {/if}
 
-      {#if actual_show_plot}
-        {#if display_mode === `scatter` || display_mode === `structure+scatter`}
+      {#if show_plot}
+        {#if plot_metadata_loading}
+          <div class="plot-metadata-loading plot">
+            <Spinner text="Sampling trajectory plot data..." style="--spinner-size: 1.4em" />
+          </div>
+        {:else if display_mode === `scatter` || display_mode === `structure+scatter`}
           <ScatterPlot
             series={plot_series}
             {x_axis}
@@ -1201,27 +1418,22 @@
             controls={scatter_controls}
             current_x_value={current_step_idx}
             change={plot_skimming ? handle_plot_change : undefined}
-            padding={{ t: 20, b: 60, l: 52, r: has_y2_series ? 100 : 20 }}
+            padding={{ t: 20, b: 60, r: has_y2_series ? 100 : 20 }}
             range_padding={0}
             style="height: 100%"
             {...scatter_props}
             legend={{
-              ...scatter_props.legend ?? {},
+              ...(scatter_props.legend ?? {}),
               on_toggle: (series_idx: number) => {
                 handle_legend_toggle(series_idx)
                 scatter_props.legend?.on_toggle?.(series_idx)
               },
             }}
-            class="plot {scatter_props.class ?? ``}"
+            class={[`plot`, scatter_props.class]}
           >
-            {#snippet tooltip({
-              x,
-              y,
-              metadata,
-              label,
-            }: ScatterHandlerProps)}
+            {#snippet tooltip({ x, y, metadata, label }: ScatterHandlerProps)}
               {@const formatted_y = typeof y === `number` ? format_num(y) : y}
-              Step: {Math.round(x)}<br />
+              {x_axis_quantity}: {Math.round(x)}<br />
               {@html sanitize_html(metadata?.series_label || label || `Value`)}: {formatted_y}
             {/snippet}
           </ScatterPlot>
@@ -1242,7 +1454,7 @@
               histogram_props.on_series_toggle?.(series_idx)
             }}
             style="height: 100%"
-            class="plot {histogram_props.class ?? ``}"
+            class={[`plot`, histogram_props.class]}
             --ctrl-btn-top="6ex"
           >
             {#snippet tooltip({
@@ -1266,8 +1478,8 @@
     <EmptyState class="trajectory-empty-state">
       <h3 id="load-trajectory">Load Trajectory</h3>
       <p>
-        Drop a trajectory file here (.xyz, .extxyz, .json, .json.gz, XDATCAR, .traj, .h5)
-        or provide trajectory data via props
+        Drop a trajectory file here (.xyz, .extxyz, .json, .json.gz, XDATCAR, .traj, .h5) or
+        provide trajectory data via props
       </p>
       <strong style="display: block; margin-block: 1em 1ex">Supported formats:</strong>
       <ul>
@@ -1279,9 +1491,7 @@
         <li>HDF5 trajectory files (.h5, .hdf5)</li>
         <li>Compressed files (.gz)</li>
       </ul>
-      <p>
-        💡 Force vectors will be automatically displayed when present in trajectory data
-      </p>
+      <p>💡 Force vectors will be automatically displayed when present in trajectory data</p>
     </EmptyState>
   {/if}
 </div>
@@ -1299,9 +1509,6 @@
     contain: layout;
     z-index: var(--traj-z-index, 1);
     container-type: size; /* enable cqh for panes if explicit height is set */
-    :global(.plot) {
-      background: var(--surface-bg);
-    }
     &.active {
       z-index: 2; /* needed so info/control panes from an active viewer overlay those of the next (if there is one) */
       .trajectory-controls {
@@ -1350,10 +1557,19 @@
       grid-template-rows: 1fr !important;
     }
   }
+  .plot-metadata-loading {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.6em;
+    min-height: 0;
+    color: var(--text-muted, currentColor);
+    background: var(--surface-bg);
+  }
   .trajectory-controls {
     display: flex;
     align-items: center;
-    gap: clamp(2pt, 1cqw, 1ex);
+    gap: clamp(4pt, 1.6cqw, 1.5ex);
     padding: clamp(2pt, 0.5cqw, 1ex) clamp(4pt, 1cqw, 1.2ex);
     background: var(--surface-bg-hover);
     backdrop-filter: blur(4px);
@@ -1373,7 +1589,7 @@
     }
     button {
       background: var(--btn-bg);
-      font-size: clamp(0.8rem, 2cqw, 1rem);
+      font-size: var(--ctrl-btn-icon-size, clamp(0.7rem, 2cqmin, 0.85rem));
       &:hover:not(:disabled) {
         background: var(--btn-bg-hover);
       }
@@ -1389,7 +1605,14 @@
   .nav-section {
     display: flex;
     align-items: center;
-    gap: clamp(1pt, 0.5cqw, 5pt);
+    gap: clamp(3pt, 1cqw, 9pt);
+  }
+  /* nudge control-button icons slightly larger via transform */
+  .nav-section button,
+  .view-mode-button,
+  .info-section
+    :global(:is(.trajectory-info-toggle, .trajectory-export-toggle, .fullscreen-button)) {
+    transform: scale(1.15);
   }
   .step-section {
     display: flex;
@@ -1411,7 +1634,8 @@
   }
   .step-slider {
     width: 100%;
-    accent-color: var(--accent-color);
+    position: relative;
+    z-index: 1; /* keep the slider knob above the step labels (which follow it in the DOM) */
   }
   .step-labels {
     position: absolute;
@@ -1469,7 +1693,7 @@
     position: relative;
   }
   .info-section :global(:is(.trajectory-info-toggle, .trajectory-export-toggle)) {
-    font-size: clamp(1rem, 2.2cqw, 1.1rem);
+    font-size: var(--ctrl-btn-icon-size, clamp(0.7rem, 2cqmin, 0.85rem));
   }
   .play-button {
     min-width: clamp(32px, 4cqw, 36px);
@@ -1479,10 +1703,7 @@
     &.playing {
       background: var(--traj-pause-btn-bg, var(--btn-bg, rgba(0, 0, 0, 0.1)));
       &:hover:not(:disabled) {
-        background: var(
-          --traj-pause-btn-bg-hover,
-          var(--btn-bg-hover, rgba(0, 0, 0, 0.1))
-        );
+        background: var(--traj-pause-btn-bg-hover, var(--btn-bg-hover, rgba(0, 0, 0, 0.1)));
       }
     }
   }
@@ -1530,14 +1751,20 @@
   .view-mode-dropdown-wrapper {
     display: flex;
     position: relative;
+    z-index: var(--trajectory-view-mode-z-index, 20);
   }
   .view-mode-dropdown {
     position: absolute;
     top: 115%;
     right: 0;
-    background: var(--surface-bg);
+    z-index: 1;
+    min-width: max-content;
+    background: var(--trajectory-view-mode-bg, light-dark(#fff, #2f3137));
     border-radius: 4px;
-    box-shadow: 0 8px 16px -4px rgba(0, 0, 0, 0.3), 0 4px 8px -2px rgba(0, 0, 0, 0.1);
+    box-shadow:
+      0 8px 16px -4px rgba(0, 0, 0, 0.3),
+      0 4px 8px -2px rgba(0, 0, 0, 0.1);
+    pointer-events: auto;
   }
   .view-mode-option {
     display: flex;