matterviz 0.4.1 → 0.4.2

package/dist/structure/ArrowInstances.svelte

@@ -0,0 +1,160 @@
+<script lang="ts">
+  // Instanced arrows (shaft cylinders + head cones) for per-site vector layers
+  // (forces, magnetic moments, ...). Replaces one <Arrow> component per site
+  // (2 meshes + 2 geometries + 2 materials each) with 2 draw calls per layer.
+  // Sizing math mirrors Arrow.svelte so the two render identically.
+  import type { Vec3 } from '../math'
+  import { EPS } from '../math'
+  import { T, useThrelte } from '@threlte/core'
+  import { untrack } from 'svelte'
+  import type { BufferGeometry } from 'three'
+  import {
+    Color,
+    ConeGeometry,
+    CylinderGeometry,
+    InstancedMesh,
+    Matrix4,
+    MeshStandardMaterial,
+    Quaternion,
+    Vector3,
+  } from 'three'
+
+  type ArrowInstance = {
+    position: Vec3
+    vector: Vec3
+    scale: number
+    color: string
+  }
+
+  let {
+    arrows,
+    shaft_radius,
+    arrow_head_radius,
+    arrow_head_length,
+  }: {
+    arrows: ArrowInstance[]
+    shaft_radius: number // negative = relative to shaft length
+    arrow_head_radius: number // negative = relative to shaft length
+    arrow_head_length: number // negative = relative to arrow length
+  } = $props()
+
+  const { invalidate } = useThrelte()
+
+  // Unit primitives scaled per instance: cylinder radius/length via (x=r, y=len, z=r)
+  const shaft_geometry = new CylinderGeometry(1, 1, 1, 12)
+  const head_geometry = new ConeGeometry(1, 1, 12)
+  const shaft_material = new MeshStandardMaterial()
+  const head_material = new MeshStandardMaterial()
+  $effect(() => () => {
+    shaft_geometry.dispose()
+    head_geometry.dispose()
+    shaft_material.dispose()
+    head_material.dispose()
+  })
+
+  const make_mesh = (
+    geometry: BufferGeometry,
+    material: MeshStandardMaterial,
+    count: number,
+  ): InstancedMesh => {
+    const mesh = new InstancedMesh(geometry, material, count)
+    mesh.frustumCulled = false
+    mesh.raycast = () => undefined // arrows are display-only
+    mesh.userData.per_instance_color = true
+    return mesh
+  }
+
+  // Recreate meshes only when the arrow count changes (fixed buffer capacity)
+  let shaft_mesh = $state.raw<InstancedMesh | null>(null)
+  let head_mesh = $state.raw<InstancedMesh | null>(null)
+  $effect(() => {
+    const count = arrows.length
+    const prev = untrack(() => shaft_mesh)
+    if (prev && prev.count === count) return
+    prev?.dispose()
+    untrack(() => head_mesh)?.dispose()
+    if (count === 0) {
+      shaft_mesh = null
+      head_mesh = null
+      return
+    }
+    shaft_mesh = make_mesh(shaft_geometry, shaft_material, count)
+    head_mesh = make_mesh(head_geometry, head_material, count)
+  })
+  // Unmount-only cleanup (a cleanup on the effect above would dispose meshes
+  // on every re-run, including runs that keep them; cleanups run untracked)
+  $effect(() => () => {
+    shaft_mesh?.dispose()
+    head_mesh?.dispose()
+  })
+
+  const up_axis = new Vector3(0, 1, 0)
+  const scratch_dir = new Vector3()
+  const scratch_quat = new Quaternion()
+  const scratch_pos = new Vector3()
+  const scratch_scale = new Vector3()
+  const scratch_matrix = new Matrix4()
+  const scratch_color = new Color()
+
+  $effect(() => {
+    const shafts = shaft_mesh
+    const heads = head_mesh
+    if (!shafts || !heads) return
+    const limit = Math.min(arrows.length, shafts.count)
+    for (let idx = 0; idx < limit; idx++) {
+      const { position, vector, scale, color } = arrows[idx]
+      const mag = Math.hypot(vector[0], vector[1], vector[2])
+      if (mag > EPS) {
+        scratch_dir.set(vector[0] / mag, vector[1] / mag, vector[2] / mag)
+        scratch_quat.setFromUnitVectors(up_axis, scratch_dir)
+      } else {
+        scratch_dir.set(0, 1, 0)
+        scratch_quat.identity()
+      }
+      const vec_len = mag * scale
+      const head_len = arrow_head_length < 0 ? vec_len * -arrow_head_length : arrow_head_length
+      const shaft_len = Math.max(0, vec_len - head_len * 0.5)
+      const shaft_r = shaft_radius < 0 ? shaft_len * -shaft_radius : shaft_radius
+      const head_r = arrow_head_radius < 0 ? shaft_len * -arrow_head_radius : arrow_head_radius
+
+      // Shafts shorter than Arrow.svelte's 0.01 render threshold collapse to zero scale
+      const draw_shaft = shaft_len > 0.01
+      scratch_pos.set(
+        position[0] + scratch_dir.x * shaft_len * 0.5,
+        position[1] + scratch_dir.y * shaft_len * 0.5,
+        position[2] + scratch_dir.z * shaft_len * 0.5,
+      )
+      scratch_scale.set(
+        draw_shaft ? shaft_r : 0,
+        draw_shaft ? shaft_len : 0,
+        draw_shaft ? shaft_r : 0,
+      )
+      shafts.setMatrixAt(idx, scratch_matrix.compose(scratch_pos, scratch_quat, scratch_scale))
+
+      const head_offset = shaft_len + head_len * 0.5
+      scratch_pos.set(
+        position[0] + scratch_dir.x * head_offset,
+        position[1] + scratch_dir.y * head_offset,
+        position[2] + scratch_dir.z * head_offset,
+      )
+      scratch_scale.set(head_r, head_len, head_r)
+      heads.setMatrixAt(idx, scratch_matrix.compose(scratch_pos, scratch_quat, scratch_scale))
+
+      scratch_color.set(color)
+      shafts.setColorAt(idx, scratch_color)
+      heads.setColorAt(idx, scratch_color)
+    }
+    for (const mesh of [shafts, heads]) {
+      mesh.instanceMatrix.needsUpdate = true
+      if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true
+    }
+    invalidate()
+  })
+</script>
+
+{#if shaft_mesh}
+  <T is={shaft_mesh} />
+{/if}
+{#if head_mesh}
+  <T is={head_mesh} />
+{/if}

package/dist/structure/ArrowInstances.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { Vec3 } from '../math';
+type ArrowInstance = {
+    position: Vec3;
+    vector: Vec3;
+    scale: number;
+    color: string;
+};
+type $$ComponentProps = {
+    arrows: ArrowInstance[];
+    shaft_radius: number;
+    arrow_head_radius: number;
+    arrow_head_length: number;
+};
+declare const ArrowInstances: import("svelte").Component<$$ComponentProps, {}, "">;
+type ArrowInstances = ReturnType<typeof ArrowInstances>;
+export default ArrowInstances;

package/dist/structure/AtomLegend.svelte

@@ -10,10 +10,7 @@
   import { colors } from '../state.svelte'
   import type { AnyStructure } from './'
   import { atomic_radii } from './'
-  import type {
-    AtomColorConfig,
-    AtomPropertyColors,
-  } from './atom-properties'
+  import type { AtomColorConfig, AtomPropertyColors } from './atom-properties'
   import type { MoyoDataset } from '@spglib/moyo-wasm'
   import type { Snippet } from 'svelte'
   import { click_outside, tooltip } from 'svelte-multiselect/attachments'
@@ -77,8 +74,7 @@
   }
 
   let show_element_legend = $derived(
-    atom_color_config.mode === `element` && elements &&
-      Object.keys(elements).length > 0,
+    atom_color_config.mode === `element` && elements && Object.keys(elements).length > 0,
   )
   let show_property_legend = $derived(
     atom_color_config.mode !== `element` && property_colors?.colors.length,
@@ -111,33 +107,43 @@
   let format_value = (val: number | string): string => {
     if (typeof val === `number`) return format_num(val, `.3~f`)
 
-    if (typeof val === `string` && val.includes(`|`)) { // Format Wyckoff orbit IDs
+    if (typeof val === `string` && val.includes(`|`)) {
+      // Format Wyckoff orbit IDs
       const [wyckoff, element] = val.split(`|`, 2)
       // Count how many sites have this wyckoff+element combination
-      const count = property_colors?.values.filter((property_value) =>
-        property_value === val
-      ).length ?? 0
+      const count =
+        property_colors?.values.filter((property_value) => property_value === val).length ?? 0
       return `${element}:${count}${wyckoff}`
     }
     return String(val)
   }
 
-  // Map from property value to color (computed once, reused in categorical legend)
-  let color_map = $derived(
-    new Map(
-      // Use unique_values instead of values to avoid undefined colors from duplicates
-      property_colors?.unique_values?.flatMap((val) => {
-        const idx = property_colors.values.indexOf(val)
-        return idx !== -1 ? [[val, property_colors.colors[idx]]] : []
-      }),
-    ),
-  )
+  // Map each property value to its first color in a single O(n) pass (reused in
+  // categorical and discrete legends). Skips undefined colors if arrays ever drift.
+  let color_map = $derived.by(() => {
+    const map = new Map<number | string, string>()
+    const { values = [], colors: value_colors = [] } = property_colors ?? {}
+    for (const [idx, val] of values.entries()) {
+      const color = value_colors[idx]
+      if (color !== undefined && !map.has(val)) map.set(val, color)
+    }
+    return map
+  })
+
+  // Continuous integer properties (e.g. coordination numbers) render as a discrete
+  // segmented bar with one labeled block per integer value instead of a smooth gradient.
+  // Cap segment count so high-cardinality numeric properties keep the gradient bar.
+  const MAX_DISCRETE_SEGMENTS = 20
+  let is_discrete_numeric = $derived.by(() => {
+    const uniq = property_colors?.unique_values
+    // Number.isInteger is false for strings/non-numbers (no coercion), so it also
+    // excludes categorical (e.g. Wyckoff) data without a separate type check
+    return Boolean(
+      uniq?.length && uniq.length <= MAX_DISCRETE_SEGMENTS && uniq.every(Number.isInteger),
+    )
+  })
 
-  function toggle_visibility<T>(
-    set: Set<T>,
-    value: T,
-    event: MouseEvent,
-  ): Set<T> {
+  function toggle_visibility<T>(set: Set<T>, value: T, event: MouseEvent): Set<T> {
     event.preventDefault()
     event.stopPropagation()
     const new_set = new SvelteSet(set)
@@ -156,8 +162,7 @@
     const query = remap_search.toLowerCase()
     return ELEM_SYMBOLS.filter((elem) => {
       const data = element_data?.find((el) => el.symbol === elem)
-      return elem.toLowerCase().includes(query) ||
-        data?.name?.toLowerCase().includes(query)
+      return elem.toLowerCase().includes(query) || data?.name?.toLowerCase().includes(query)
     })
   })
 
@@ -165,14 +170,13 @@
   let sorted_element_entries = $derived.by(() => {
     if (!elements) return []
     const element_amounts = elements as Record<string, number>
-    const ordered_known_entries = ELEM_SYMBOLS
-      .flatMap((element_symbol) => {
-        const amount = element_amounts[element_symbol]
-        return amount === undefined ? [] : [[element_symbol, amount] as const]
-      })
+    const ordered_known_entries = ELEM_SYMBOLS.flatMap((element_symbol) => {
+      const amount = element_amounts[element_symbol]
+      return amount === undefined ? [] : [[element_symbol, amount] as const]
+    })
     const unknown_entries = Object.entries(element_amounts)
-      .filter(([element_symbol]) =>
-        !known_element_symbols.has(element_symbol as ElementSymbol)
+      .filter(
+        ([element_symbol]) => !known_element_symbols.has(element_symbol as ElementSymbol),
       )
       .sort(([element_a], [element_b]) => element_a.localeCompare(element_b))
     return [...ordered_known_entries, ...unknown_entries]
@@ -195,7 +199,7 @@
   const MAX_RADIUS = 5
 
   const parse_radius = (value: string): number | null => {
-    const num = parseFloat(value)
+    const num = Number(value)
     return !isNaN(num) && num >= MIN_RADIUS && num <= MAX_RADIUS ? num : null
   }
 
@@ -238,7 +242,7 @@
 {#snippet mode_selector_snippet()}
   <div
     class="mode-selector"
-    {@attach click_outside({ callback: () => mode_menu_open = false })}
+    {@attach click_outside({ callback: () => (mode_menu_open = false) })}
   >
     <button
       class="mode-toggle"
@@ -254,10 +258,7 @@
     </button>
     {#if mode_menu_open}
       <div class="mode-dropdown">
-        {#each Object.entries(SETTINGS_CONFIG.structure.atom_color_mode.enum || {}) as
-          [value, label]
-          (value)
-        }
+        {#each Object.entries(SETTINGS_CONFIG.structure.atom_color_mode.enum || {}) as [value, label] (value)}
           <button
             class="mode-option"
             class:selected={atom_color_config.mode === value}
@@ -323,7 +324,7 @@
 {/snippet}
 
 {#if show_element_legend}
-  <div {...rest} class="atom-legend element-legend {rest.class ?? ``}">
+  <div {...rest} class={[`atom-legend element-legend`, rest.class]}>
     {@render mode_selector_snippet()}
     {#each sorted_element_entries as [elem, amt], idx (elem)}
       {@const is_hidden = hidden_elements.has(elem as ElementSymbol)}
@@ -331,7 +332,8 @@
       <div class="legend-item">
         <label
           bind:this={labels[idx]}
-          title="{element_data?.find((el) => el.symbol === displayed_elem)?.name ?? ``}{displayed_elem !== elem ? ` (remapped from ${elem})` : ``}"
+          title="{element_data?.find((el) => el.symbol === displayed_elem)?.name ??
+            ``}{displayed_elem !== elem ? ` (remapped from ${elem})` : ``}"
           {@attach tooltip()}
           style:background-color={colors.element[displayed_elem]}
           class:hidden={is_hidden}
@@ -364,13 +366,12 @@
         <button
           class="toggle-visibility"
           class:element-hidden={is_hidden}
-          onclick={(
-            event,
-          ) => (hidden_elements = toggle_visibility(
-            hidden_elements,
-            elem as ElementSymbol,
-            event,
-          ))}
+          onclick={(event) =>
+            (hidden_elements = toggle_visibility(
+              hidden_elements,
+              elem as ElementSymbol,
+              event,
+            ))}
           title={is_hidden ? `Show ${elem} atoms` : `Hide ${elem} atoms`}
           {@attach tooltip({ placement: `top` })}
           type="button"
@@ -390,8 +391,8 @@
             <div class="radius-control">
               <label
                 title={displayed_elem !== elem
-                ? `Radius for ${elem} atoms (displayed as ${displayed_elem})`
-                : `Radius for ${elem} atoms`}
+                  ? `Radius for ${elem} atoms (displayed as ${displayed_elem})`
+                  : `Radius for ${elem} atoms`}
                 {@attach tooltip({ placement: `top` })}
               >
                 <span>Radius ({elem})</span>
@@ -403,10 +404,7 @@
                   value={get_element_radius(elem as ElementSymbol)}
                   oninput={(event) => {
                     if (event.target instanceof HTMLInputElement) {
-                      update_element_radius(
-                        elem as ElementSymbol,
-                        event.target.value,
-                      )
+                      update_element_radius(elem as ElementSymbol, event.target.value)
                     }
                   }}
                 />
@@ -480,11 +478,29 @@
         <h4>{legend_title}</h4>
       </div>
     {/if}
-    {#if atom_color_config.scale_type === `continuous` && property_colors}
-      <div
-        title={legend_title}
-        {@attach tooltip({ placement: `top` })}
-      >
+    {#if atom_color_config.scale_type === `continuous` && property_colors && is_discrete_numeric}
+      <div class="discrete-colorbar">
+        {#each property_colors.unique_values ?? [] as value (value)}
+          {@const color = color_map.get(value)}
+          {@const is_hidden = hidden_prop_vals.has(value)}
+          <button
+            type="button"
+            class="discrete-segment"
+            class:hidden={is_hidden}
+            style:background-color={color}
+            aria-pressed={is_hidden}
+            onclick={(event) =>
+              (hidden_prop_vals = toggle_visibility(hidden_prop_vals, value, event))}
+            title={is_hidden ? `Show ${format_value(value)}` : `Hide ${format_value(value)}`}
+            {@attach tooltip({ placement: `top` })}
+            {@attach contrast_color()}
+          >
+            {format_value(value)}
+          </button>
+        {/each}
+      </div>
+    {:else if atom_color_config.scale_type === `continuous` && property_colors}
+      <div title={legend_title} {@attach tooltip({ placement: `top` })}>
         <ColorBar
           color_scale={atom_color_config.scale}
           range={[property_colors.min_value ?? 0, property_colors.max_value ?? 0]}
@@ -499,10 +515,7 @@
         />
       </div>
     {:else if atom_color_config.scale_type === `categorical` && property_colors}
-      {#each property_colors.unique_values || [] as
-        value
-        (`${atom_color_config.mode}-${value}`)
-      }
+      {#each property_colors.unique_values || [] as value (`${atom_color_config.mode}-${value}`)}
         {@const color = color_map.get(value)}
         {@const is_hidden = hidden_prop_vals.has(value)}
         <div class="legend-item">
@@ -517,13 +530,8 @@
           <button
             class="toggle-visibility"
             class:element-hidden={is_hidden}
-            onclick={(
-              event,
-            ) => (hidden_prop_vals = toggle_visibility(
-              hidden_prop_vals,
-              value,
-              event,
-            ))}
+            onclick={(event) =>
+              (hidden_prop_vals = toggle_visibility(hidden_prop_vals, value, event))}
             title={is_hidden ? `Show ${format_value(value)}` : `Hide ${format_value(value)}`}
             {@attach tooltip({ placement: `top` })}
             type="button"
@@ -552,7 +560,9 @@
     gap: var(--struct-legend-gap, clamp(3pt, 2cqmin, 7pt));
   }
   .element-legend {
-    font-size: var(--struct-legend-font, clamp(7pt, 2.5cqmin, 12pt));
+    /* 9pt floor keeps chips legible in small embeds (carousel cards) where
+      the cqmin term collapses */
+    font-size: var(--struct-legend-font, clamp(9pt, 2.5cqmin, 12pt));
   }
   .atom-legend .legend-item {
     position: relative;
@@ -598,7 +608,10 @@
     display: grid;
     place-items: center;
     opacity: 0;
-    transition: opacity 0.2s ease, background 0.2s ease, transform 0.1s ease;
+    transition:
+      opacity 0.2s ease,
+      background 0.2s ease,
+      transform 0.1s ease;
     z-index: 2;
     pointer-events: auto;
   }
@@ -717,7 +730,7 @@
 
   /* Property Legend Styles */
   .property-legend {
-    font-size: var(--struct-legend-font, clamp(8pt, 3cqmin, 14pt));
+    font-size: var(--struct-legend-font, clamp(9pt, 3cqmin, 14pt));
   }
   .mode-selector {
     position: relative;
@@ -753,7 +766,9 @@
     margin-bottom: 0.25rem;
     background: var(--surface-bg);
     border-radius: var(--border-radius, 3pt);
-    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);
     display: flex;
     flex-direction: column;
     z-index: 10;
@@ -795,6 +810,31 @@
   .mode-option span {
     white-space: nowrap;
   }
+  /* Discrete color bar: contiguous integer-labeled segments (e.g. coordination numbers) */
+  .discrete-colorbar {
+    display: flex;
+    height: var(--struct-discrete-bar-height, 16px);
+    border-radius: var(--border-radius, 3pt);
+    overflow: hidden;
+  }
+  .discrete-segment {
+    flex: 1 1 0;
+    min-width: 1.7em;
+    margin: 0;
+    padding: 0 4pt;
+    border: none;
+    border-radius: 0;
+    font-size: 0.85em;
+    line-height: 1;
+    cursor: pointer;
+    display: grid;
+    place-items: center;
+    transition: opacity 0.2s ease;
+  }
+  .discrete-segment.hidden {
+    opacity: 0.35;
+    text-decoration: line-through;
+  }
   .category-label {
     padding: var(--struct-legend-padding, 0 4pt);
     border-radius: var(--struct-legend-radius, var(--border-radius, 3pt));

package/dist/structure/AtomLegend.svelte.d.ts

@@ -30,6 +30,6 @@ type $$ComponentProps = Omit<HTMLAttributes<HTMLDivElement>, `children`> & {
         structure?: AnyStructure | null;
     }]>;
 };
-declare const AtomLegend: import("svelte").Component<$$ComponentProps, {}, "labels" | "atom_color_config" | "hidden_elements" | "hidden_prop_vals" | "element_mapping" | "element_radius_overrides" | "site_radius_overrides">;
+declare const AtomLegend: import("svelte").Component<$$ComponentProps, {}, "labels" | "hidden_elements" | "hidden_prop_vals" | "element_radius_overrides" | "site_radius_overrides" | "atom_color_config" | "element_mapping">;
 type AtomLegend = ReturnType<typeof AtomLegend>;
 export default AtomLegend;

package/dist/structure/Bond.svelte

@@ -4,7 +4,11 @@
   import type { InstancedMesh } from 'three'
   import { Color, InstancedBufferAttribute, Matrix4, ShaderMaterial } from 'three'
 
-  let { group, saturation = 0.5, brightness = 0.7 }: {
+  let {
+    group,
+    saturation = 0.5,
+    brightness = 0.7,
+  }: {
     group: BondGroupWithGradients
     saturation?: number
     brightness?: number
@@ -104,12 +108,10 @@
 
     // Update geometry color attributes
     const { geometry } = mesh
-    for (
-      const [name, buffer] of [
-        [`instanceColorStart`, colors_start],
-        [`instanceColorEnd`, colors_end],
-      ] as const
-    ) {
+    for (const [name, buffer] of [
+      [`instanceColorStart`, colors_start],
+      [`instanceColorEnd`, colors_end],
+    ] as const) {
       const existing = geometry.getAttribute(name)
       if (existing?.array === buffer) existing.needsUpdate = true
       else geometry.setAttribute(name, new InstancedBufferAttribute(buffer, 3))
@@ -118,23 +120,29 @@
     mesh.count = count
   })
 
-  let shader_material = $derived(
-    new ShaderMaterial({
-      vertexShader: vertex_shader,
-      fragmentShader: fragment_shader,
-      uniforms: {
-        ambientIntensity: { value: group.ambient_light ?? 0.7 },
-        directionalIntensity: { value: group.directional_light ?? 0.3 },
-        saturation: { value: saturation },
-        brightness: { value: brightness },
-      },
-    }),
-  )
+  // Create the GPU material once + mutate uniforms reactively (a $derived would leak a new
+  // ShaderMaterial per lighting tweak). The $effect sets real uniform values before paint.
+  const shader_material = new ShaderMaterial({
+    vertexShader: vertex_shader,
+    fragmentShader: fragment_shader,
+    uniforms: {
+      ambientIntensity: { value: 0.7 },
+      directionalIntensity: { value: 0.3 },
+      saturation: { value: 0.5 },
+      brightness: { value: 0.7 },
+    },
+  })
+
+  $effect(() => {
+    shader_material.uniforms.ambientIntensity.value = group.ambient_light ?? 0.7
+    shader_material.uniforms.directionalIntensity.value = group.directional_light ?? 0.3
+    shader_material.uniforms.saturation.value = saturation
+    shader_material.uniforms.brightness.value = brightness
+  })
+
+  $effect(() => () => shader_material.dispose())
 </script>
 
-<T.InstancedMesh
-  args={[undefined, shader_material, group.instances.length]}
-  bind:ref={mesh}
->
+<T.InstancedMesh args={[undefined, shader_material, group.instances.length]} bind:ref={mesh}>
   <T.CylinderGeometry args={[group.thickness, group.thickness, 1, 8]} />
 </T.InstancedMesh>

package/dist/structure/CanvasTooltip.svelte

@@ -4,13 +4,22 @@
   import type { HTMLAttributes } from 'svelte/elements'
   import type { Vec3 } from '../math'
 
-  let { position, children, ...rest }: HTMLAttributes<HTMLDivElement> & {
+  let {
+    position,
+    children,
+    ...rest
+  }: HTMLAttributes<HTMLDivElement> & {
     position: Vec3
     children: Snippet<[{ position: Vec3 }]>
   } = $props()
 </script>
 
-<HTML {position} pointerEvents="none">
+<!-- Constant zIndexRange: threlte's default [16777271, 0] maps camera distance
+  over [near, far], which extrapolates to a NEGATIVE z-index for sites beyond
+  camera.far (common in zoomed-out carousel cards) — painting the tooltip
+  behind the canvas. A degenerate range pins z-index at 1000, always above the
+  canvas and sibling overlays. -->
+<HTML {position} pointerEvents="none" zIndexRange={[1000, 1000]}>
   <div {...rest} role="tooltip">
     {@render children({ position })}
   </div>
@@ -23,7 +32,10 @@
     box-sizing: border-box;
     text-align: var(--canvas-tooltip-text-align, left);
     border-radius: var(--canvas-tooltip-border-radius, var(--border-radius, 3pt));
-    background: var(--canvas-tooltip-bg, light-dark(rgba(226, 232, 240, 0.96), rgba(15, 23, 42, 0.96)));
+    background: var(
+      --canvas-tooltip-bg,
+      light-dark(rgba(226, 232, 240, 0.96), rgba(15, 23, 42, 0.96))
+    );
     padding: var(--canvas-tooltip-padding, 1pt 5pt);
     color: var(--canvas-tooltip-text-color, light-dark(#0f172a, #f8fafc));
     font-family: var(--canvas-tooltip-font-family);