matterviz 0.4.0 → 0.4.2

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

@@ -2,31 +2,27 @@ import type { D3InterpolateName } from '../colors';
 import type { ElementSymbol } from '../element';
 import type { IsosurfaceSettings, VolumetricData } from '../isosurface/types';
 import type { Vec3 } from '../math';
-import type { CameraProjection, ShowBonds, VectorColorMode, VectorLayerConfig } from '../settings';
+import type { SceneControlProps } from '../scene';
+import type { ShowBonds, VectorColorMode, VectorLayerConfig } from '../settings';
 import type { AnyStructure, BondEditMode, BondOrder, MeasureMode, Site, StructureBond } from './';
 import { Lattice } from './';
 import type { AtomColorConfig } from './atom-properties';
+import type { SymmetryElement } from '../symmetry';
+import SymmetryElements from '../symmetry/SymmetryElements.svelte';
 import type { MoyoDataset } from '@spglib/moyo-wasm';
 import * as extras from '@threlte/extras';
 import { type ComponentProps, type Snippet } from 'svelte';
 import { SvelteMap } from 'svelte/reactivity';
-import { type Camera, type Scene } from 'three';
 import type { BondingStrategy } from './bonding';
-type $$ComponentProps = {
+import type { PolyhedraColorMode } from './polyhedra';
+type $$ComponentProps = SceneControlProps & {
     structure?: AnyStructure;
     base_structure?: AnyStructure;
     atom_radius?: number;
     same_size_atoms?: boolean;
     camera_position?: [x: number, y: number, z: number];
     camera_target?: Vec3;
-    camera_projection?: CameraProjection;
-    rotation_damping?: number;
-    max_zoom?: number;
-    min_zoom?: number;
-    rotate_speed?: number;
-    zoom_speed?: number;
-    pan_speed?: number;
-    zoom_to_cursor?: boolean;
+    camera_direction?: Vec3;
     show_atoms?: boolean;
     show_bonds?: ShowBonds;
     show_site_labels?: boolean;
@@ -42,23 +38,32 @@ type $$ComponentProps = {
     vector_shaft_radius?: number;
     vector_arrow_head_radius?: number;
     vector_arrow_head_length?: number;
-    gizmo?: boolean | ComponentProps<typeof extras.Gizmo>;
     hovered_idx?: number | null;
     hovered_site?: Site | null;
     float_fmt?: string;
-    auto_rotate?: number;
-    initial_zoom?: number;
     bond_thickness?: number;
     bond_color?: string;
     bonding_strategy?: BondingStrategy;
     auto_bond_order?: boolean;
     aromatic_display?: `aromatic` | `kekule`;
     bonding_options?: Record<string, unknown>;
-    fov?: number;
-    ambient_light?: number;
-    directional_light?: number;
+    show_polyhedra?: ShowBonds;
+    polyhedra_opacity?: number;
+    polyhedra_show_edges?: boolean;
+    polyhedra_edge_color?: string;
+    polyhedra_color_mode?: PolyhedraColorMode;
+    polyhedra_color?: string;
+    polyhedra_hide_center_atoms?: boolean;
+    polyhedra_min_neighbors?: number;
+    polyhedra_max_neighbors?: number;
+    polyhedra_excluded_elements?: readonly string[];
+    polyhedra_included_elements?: readonly string[];
+    polyhedra_rendered_elements?: string[];
     sphere_segments?: number;
     lattice_props?: ComponentProps<typeof Lattice>;
+    symmetry_elements?: SymmetryElement[];
+    symmetry_elements_props?: Omit<ComponentProps<typeof SymmetryElements>, `elements` | `lattice`>;
+    symmetry_declutter?: boolean;
     atom_label?: Snippet<[{
         site: Site;
         site_idx: number;
@@ -84,8 +89,6 @@ type $$ComponentProps = {
     active_sites?: number[];
     active_highlight_color?: string;
     rotation?: Vec3;
-    scene?: Scene;
-    camera?: Camera;
     orbit_controls?: ComponentProps<typeof extras.OrbitControls>[`ref`];
     rotation_target_ref?: Vec3;
     initial_computed_zoom?: number;
@@ -105,7 +108,8 @@ type $$ComponentProps = {
     dragging_atoms?: boolean;
     volumetric_data?: VolumetricData;
     isosurface_settings?: IsosurfaceSettings;
+    interactive?: boolean;
 };
-declare const StructureScene: import("svelte").Component<$$ComponentProps, {}, "cursor" | "site_label_offset" | "vector_configs" | "camera" | "scene" | "orbit_controls" | "site_radius_overrides" | "hovered_idx" | "hovered_site" | "camera_is_moving" | "selected_sites" | "measured_sites" | "added_bonds" | "removed_bonds" | "bond_order_overrides" | "bond_edit_mode" | "active_sites" | "rotation_target_ref" | "initial_computed_zoom" | "hidden_elements" | "hidden_prop_vals" | "element_radius_overrides" | "add_atom_mode" | "add_element" | "dragging_atoms">;
+declare const StructureScene: import("svelte").Component<$$ComponentProps, {}, "cursor" | "camera" | "site_label_offset" | "vector_configs" | "orbit_controls" | "hovered_idx" | "hovered_site" | "polyhedra_rendered_elements" | "camera_is_moving" | "selected_sites" | "measured_sites" | "added_bonds" | "removed_bonds" | "bond_order_overrides" | "bond_edit_mode" | "active_sites" | "scene" | "rotation_target_ref" | "initial_computed_zoom" | "hidden_elements" | "hidden_prop_vals" | "element_radius_overrides" | "site_radius_overrides" | "add_atom_mode" | "add_element" | "dragging_atoms">;
 type StructureScene = ReturnType<typeof StructureScene>;
 export default StructureScene;

package/dist/structure/StructureViewport.svelte

@@ -0,0 +1,386 @@
+<script lang="ts">
+  // A single subcanvas (one Threlte <Canvas> + <StructureScene>) used by Structure.svelte
+  // for both the regular single view and each pane of the 2x2 multi-side view.
+  //
+  // Each viewport owns its camera: move tracking, reset (on reset_token), and orbit-target
+  // recentering on structure change. The primary pane (index 0) additionally binds out
+  // scene/camera for the export pane and receives the on_camera_move/on_camera_reset
+  // callbacks so it drives Structure's external camera API. Camera state is per-pane:
+  // the primary pane binds it back to Structure's scene_props, while side panes keep it local.
+  import type { ElementSymbol } from '../element'
+  import type { IsosurfaceSettings, VolumetricData } from '../isosurface/types'
+  import type { Vec3 } from '../math'
+  import type { CameraProjection } from '../settings'
+  import type {
+    AnyStructure,
+    BondEditMode,
+    BondOrder,
+    MeasureMode,
+    StructureBond,
+    StructureHandlerData,
+  } from './'
+  import type { MoyoDataset } from '@spglib/moyo-wasm'
+  import { Canvas } from '@threlte/core'
+  import type { ComponentProps } from 'svelte'
+  import { untrack } from 'svelte'
+  import { SvelteMap, SvelteSet } from 'svelte/reactivity'
+  import { WebGLRenderer, type Camera, type OrthographicCamera, type Scene } from 'three'
+  import type { AtomColorConfig } from './atom-properties'
+  import StructureScene from './StructureScene.svelte'
+
+  // WebGL contexts survive renderer.dispose() unless explicitly released.
+  class StructureRenderer extends WebGLRenderer {
+    constructor(parameters: ConstructorParameters<typeof WebGLRenderer>[0]) {
+      super(parameters)
+      globalThis.addEventListener(`pagehide`, this.release_context, { once: true })
+    }
+
+    private release_context = (): void => {
+      if (!this.getContext().isContextLost()) this.forceContextLoss()
+    }
+
+    override dispose() {
+      globalThis.removeEventListener(`pagehide`, this.release_context)
+      super.dispose()
+      this.release_context()
+    }
+  }
+
+  const create_renderer = (canvas: HTMLCanvasElement) =>
+    new StructureRenderer({
+      canvas,
+      powerPreference: `high-performance`,
+      antialias: true,
+      alpha: true,
+    })
+
+  let {
+    // Multi-view chrome
+    in_grid = false,
+    active = false,
+    label = undefined,
+    reset_token = 0,
+    interactive = true,
+    onactivate = undefined,
+    report_moved = undefined,
+    on_camera_move = undefined,
+    on_camera_reset = undefined,
+
+    // Shared scene inputs (one-way)
+    structure = undefined,
+    base_structure = undefined,
+    scene_props = {},
+    gizmo = false,
+    lattice_props = {},
+    volumetric_data = undefined,
+    isosurface_settings = undefined,
+    bond_edits_enabled = true,
+    bond_edit_order = 1,
+    measure_mode = `distance`,
+    atom_color_config = undefined,
+    sym_data = null,
+    active_sites = [],
+    camera_direction = undefined,
+    camera_projection = `orthographic`,
+    camera_position = $bindable([0, 0, 0]),
+    camera_target = $bindable(undefined),
+
+    // Edit-mode callbacks
+    on_sites_moved = undefined,
+    on_operation_start = undefined,
+    on_bond_edit_start = undefined,
+    on_add_atom = undefined,
+
+    // scene + camera are bound out for the primary pane (consumed by the export pane)
+    scene = $bindable(undefined),
+    camera = $bindable(undefined),
+
+    // Shared two-way scene state
+    selected_sites = $bindable([]),
+    measured_sites = $bindable([]),
+    hovered_site_idx = $bindable(null),
+    hidden_elements = $bindable(new SvelteSet<ElementSymbol>()),
+    hidden_prop_vals = $bindable(new SvelteSet<number | string>()),
+    element_radius_overrides = $bindable({}),
+    site_radius_overrides = $bindable(new SvelteMap<number, number>()),
+    added_bonds = $bindable([]),
+    removed_bonds = $bindable([]),
+    bond_order_overrides = $bindable([]),
+    bond_edit_mode = $bindable(`add`),
+    add_atom_mode = $bindable(false),
+    add_element = $bindable(`C`),
+    dragging_atoms = $bindable(false),
+    polyhedra_rendered_elements = $bindable([]),
+  }: {
+    in_grid?: boolean
+    active?: boolean
+    label?: string
+    reset_token?: number
+    interactive?: boolean
+    onactivate?: () => void
+    report_moved?: (moved: boolean) => void
+    on_camera_move?: (data: StructureHandlerData) => void
+    on_camera_reset?: (data: StructureHandlerData) => void
+    structure?: AnyStructure
+    base_structure?: AnyStructure
+    scene_props?: ComponentProps<typeof StructureScene>
+    gizmo?: boolean | ComponentProps<typeof StructureScene>[`gizmo`]
+    lattice_props?: ComponentProps<typeof StructureScene>[`lattice_props`]
+    volumetric_data?: VolumetricData
+    isosurface_settings?: IsosurfaceSettings
+    bond_edits_enabled?: boolean
+    bond_edit_order?: BondOrder
+    measure_mode?: MeasureMode
+    atom_color_config?: Partial<AtomColorConfig>
+    sym_data?: MoyoDataset | null
+    active_sites?: number[]
+    camera_direction?: Vec3
+    camera_projection?: CameraProjection
+    camera_position?: Vec3
+    camera_target?: Vec3
+    on_sites_moved?: (scene_indices: number[], delta: Vec3) => void
+    on_operation_start?: () => void
+    on_bond_edit_start?: () => void
+    on_add_atom?: (xyz: Vec3, element: ElementSymbol) => void
+    scene?: Scene
+    camera?: Camera
+    selected_sites?: number[]
+    measured_sites?: number[]
+    hovered_site_idx?: number | null
+    hidden_elements?: Set<ElementSymbol>
+    hidden_prop_vals?: Set<number | string>
+    element_radius_overrides?: Partial<Record<ElementSymbol, number>>
+    site_radius_overrides?: Map<number, number> | SvelteMap<number, number>
+    added_bonds?: StructureBond[]
+    removed_bonds?: StructureBond[]
+    bond_order_overrides?: StructureBond[]
+    bond_edit_mode?: BondEditMode
+    add_atom_mode?: boolean
+    add_element?: ElementSymbol
+    dragging_atoms?: boolean
+    polyhedra_rendered_elements?: string[]
+  } = $props()
+
+  // Cell-local dimensions (each pane is responsible for its own zoom sizing) and cursor
+  let width = $state(0)
+  let height = $state(0)
+  let cursor = $state(`default`)
+
+  // Multi-view panes are ~half the viewer, so shrink the (fixed 86px) viewport gizmo to
+  // stay proportional. Single view keeps the default size.
+  let gizmo_prop = $derived.by(() => {
+    if (!gizmo || !in_grid) return gizmo
+    const fifth_of_min_dim = Math.min(width, height) * 0.2
+    const size = Math.round(Math.max(34, Math.min(72, fifth_of_min_dim)))
+    return { ...(typeof gizmo === `object` ? gizmo : {}), size }
+  })
+
+  // Internal orbit controls are bound from StructureScene; camera_position/target are
+  // bindable above so the primary viewport can persist moves into scene_props.
+  let orbit_controls =
+    $state<ComponentProps<typeof StructureScene>[`orbit_controls`]>(undefined)
+  let rotation_target_ref = $state<Vec3 | undefined>(undefined)
+  let initial_computed_zoom = $state<number | undefined>(undefined)
+  let camera_is_moving = $state(false)
+
+  const read_orbit_target = (): Vec3 | undefined => {
+    if (!orbit_controls?.target) return
+    const { x, y, z } = orbit_controls.target
+    return [x, y, z]
+  }
+
+  const read_camera_position = (): Vec3 | undefined =>
+    camera ? [camera.position.x, camera.position.y, camera.position.z] : camera_position
+
+  // Reset this pane's camera. The primary pane is given on_camera_reset, so it also emits.
+  function reset_camera() {
+    camera_position = [0, 0, 0]
+    camera_target = rotation_target_ref
+    report_moved?.(false)
+    if (orbit_controls && camera) {
+      if (`reset` in orbit_controls && typeof orbit_controls.reset === `function`) {
+        orbit_controls.reset()
+      }
+      if (orbit_controls.target && rotation_target_ref) {
+        orbit_controls.target.set(...rotation_target_ref)
+      }
+      if (`zoom` in camera && initial_computed_zoom !== undefined) {
+        const ortho_camera = camera as OrthographicCamera
+        ortho_camera.zoom = initial_computed_zoom
+        ortho_camera.updateProjectionMatrix()
+      }
+      if (typeof orbit_controls.update === `function`) orbit_controls.update()
+      camera_position = read_camera_position() ?? camera_position
+      camera_target = read_orbit_target()
+    }
+    on_camera_reset?.({ structure, camera_has_moved: false, camera_position, camera_target })
+  }
+
+  // Track camera movement: keep camera_target in sync with the orbit controls and emit
+  // on_camera_move (primary pane only) while the controls are active.
+  $effect(() => {
+    if (!camera_is_moving) return
+    report_moved?.(true)
+    const sync = () => {
+      const pos = read_camera_position()
+      if (!pos) return
+      const target = read_orbit_target()
+      camera_position = pos
+      camera_target = target
+      on_camera_move?.({
+        structure,
+        camera_has_moved: true,
+        camera_position: pos,
+        camera_target: target,
+      })
+    }
+    sync()
+    const interval = setInterval(sync, 200)
+    return () => clearInterval(interval)
+  })
+
+  // Reset on parent request (reset-all button bumps reset_token for every pane)
+  let last_reset_token: number | undefined
+  $effect(() => {
+    const token = reset_token
+    if (last_reset_token !== undefined && token !== last_reset_token) {
+      untrack(reset_camera)
+    }
+    last_reset_token = token
+  })
+
+  // Clear stale camera state on structure change so each pane re-frames the new cell
+  // along its configured direction.
+  let viewport_first_run = true
+  $effect(() => {
+    void structure
+    if (viewport_first_run) {
+      viewport_first_run = false
+      return
+    }
+    untrack(() => {
+      // Preserve explicit camera props supplied alongside a structure change.
+      if (camera_target !== undefined || camera_position.some((coord) => coord !== 0)) return
+      camera_position = [0, 0, 0]
+      camera_target = undefined
+    })
+  })
+
+  function handle_dblclick(event: MouseEvent) {
+    const target = event.target
+    if (
+      target instanceof HTMLElement &&
+      [`BUTTON`, `INPUT`, `SELECT`].includes(target.tagName)
+    )
+      return
+    reset_camera()
+  }
+</script>
+
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div
+  class="viewport-cell"
+  class:active
+  class:multi={in_grid}
+  style:--canvas-cursor={cursor}
+  bind:clientWidth={width}
+  bind:clientHeight={height}
+  onpointerenter={onactivate}
+  ondblclick={handle_dblclick}
+>
+  {#if label}<span class="viewport-label">{label}</span>{/if}
+  <Canvas createRenderer={create_renderer}>
+    <StructureScene
+      {structure}
+      {base_structure}
+      {...scene_props}
+      {...in_grid ? { auto_rotate: 0 } : {}}
+      {camera_position}
+      {camera_target}
+      {camera_projection}
+      {camera_direction}
+      {interactive}
+      gizmo={gizmo_prop}
+      {lattice_props}
+      {volumetric_data}
+      {isosurface_settings}
+      bind:camera_is_moving
+      bind:selected_sites
+      {active_sites}
+      bind:hovered_idx={hovered_site_idx}
+      bind:measured_sites
+      bind:scene
+      bind:camera
+      bind:orbit_controls
+      bind:rotation_target_ref
+      bind:initial_computed_zoom
+      bind:hidden_elements
+      bind:hidden_prop_vals
+      bind:element_radius_overrides
+      bind:site_radius_overrides
+      bind:added_bonds
+      bind:removed_bonds
+      bind:bond_order_overrides
+      {bond_edits_enabled}
+      bind:bond_edit_mode
+      {bond_edit_order}
+      {measure_mode}
+      {width}
+      {height}
+      {atom_color_config}
+      {sym_data}
+      {on_sites_moved}
+      {on_operation_start}
+      {on_bond_edit_start}
+      {on_add_atom}
+      bind:add_atom_mode
+      bind:add_element
+      bind:cursor
+      bind:dragging_atoms
+      bind:polyhedra_rendered_elements
+    />
+  </Canvas>
+</div>
+
+<style>
+  .viewport-cell {
+    position: relative;
+    overflow: hidden;
+    box-sizing: border-box;
+    height: 100%;
+    width: 100%;
+    min-width: 0;
+    min-height: 0;
+  }
+  /* In multi-view, give each pane a subtle separator and highlight the active one */
+  .viewport-cell.multi {
+    border: 1px solid var(--struct-viewport-border, rgba(128, 128, 128, 0.35));
+  }
+  /* Let the active pane's hover tooltip overflow into neighboring panes instead of
+    being clipped, and raise it above sibling panes so it paints on top. The WebGL
+    canvas is sized to the cell by JS, so only HTML overlays (the tooltip) overflow. */
+  .viewport-cell.multi.active {
+    border-color: var(--struct-viewport-active-border, var(--accent-color, #4a9eff));
+    overflow: visible;
+    z-index: 1;
+  }
+  .viewport-label {
+    position: absolute;
+    top: 3px;
+    left: 5px;
+    z-index: 1;
+    pointer-events: none;
+    font-size: var(--struct-viewport-label-font-size, 0.8em);
+    font-weight: 500;
+    padding: 1px 5px;
+    border-radius: var(--border-radius, 3pt);
+    color: var(--struct-viewport-label-color, var(--text-color, currentColor));
+    background: var(
+      --struct-viewport-label-bg,
+      color-mix(in srgb, var(--page-bg, Canvas) 65%, transparent)
+    );
+  }
+  .viewport-cell :global(canvas) {
+    cursor: var(--canvas-cursor, default);
+  }
+</style>

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

@@ -0,0 +1,63 @@
+import type { ElementSymbol } from '../element';
+import type { IsosurfaceSettings, VolumetricData } from '../isosurface/types';
+import type { Vec3 } from '../math';
+import type { CameraProjection } from '../settings';
+import type { AnyStructure, BondEditMode, BondOrder, MeasureMode, StructureBond, StructureHandlerData } from './';
+import type { MoyoDataset } from '@spglib/moyo-wasm';
+import type { ComponentProps } from 'svelte';
+import { SvelteMap } from 'svelte/reactivity';
+import { type Camera, type Scene } from 'three';
+import type { AtomColorConfig } from './atom-properties';
+import StructureScene from './StructureScene.svelte';
+type $$ComponentProps = {
+    in_grid?: boolean;
+    active?: boolean;
+    label?: string;
+    reset_token?: number;
+    interactive?: boolean;
+    onactivate?: () => void;
+    report_moved?: (moved: boolean) => void;
+    on_camera_move?: (data: StructureHandlerData) => void;
+    on_camera_reset?: (data: StructureHandlerData) => void;
+    structure?: AnyStructure;
+    base_structure?: AnyStructure;
+    scene_props?: ComponentProps<typeof StructureScene>;
+    gizmo?: boolean | ComponentProps<typeof StructureScene>[`gizmo`];
+    lattice_props?: ComponentProps<typeof StructureScene>[`lattice_props`];
+    volumetric_data?: VolumetricData;
+    isosurface_settings?: IsosurfaceSettings;
+    bond_edits_enabled?: boolean;
+    bond_edit_order?: BondOrder;
+    measure_mode?: MeasureMode;
+    atom_color_config?: Partial<AtomColorConfig>;
+    sym_data?: MoyoDataset | null;
+    active_sites?: number[];
+    camera_direction?: Vec3;
+    camera_projection?: CameraProjection;
+    camera_position?: Vec3;
+    camera_target?: Vec3;
+    on_sites_moved?: (scene_indices: number[], delta: Vec3) => void;
+    on_operation_start?: () => void;
+    on_bond_edit_start?: () => void;
+    on_add_atom?: (xyz: Vec3, element: ElementSymbol) => void;
+    scene?: Scene;
+    camera?: Camera;
+    selected_sites?: number[];
+    measured_sites?: number[];
+    hovered_site_idx?: number | null;
+    hidden_elements?: Set<ElementSymbol>;
+    hidden_prop_vals?: Set<number | string>;
+    element_radius_overrides?: Partial<Record<ElementSymbol, number>>;
+    site_radius_overrides?: Map<number, number> | SvelteMap<number, number>;
+    added_bonds?: StructureBond[];
+    removed_bonds?: StructureBond[];
+    bond_order_overrides?: StructureBond[];
+    bond_edit_mode?: BondEditMode;
+    add_atom_mode?: boolean;
+    add_element?: ElementSymbol;
+    dragging_atoms?: boolean;
+    polyhedra_rendered_elements?: string[];
+};
+declare const StructureViewport: import("svelte").Component<$$ComponentProps, {}, "camera" | "camera_position" | "camera_target" | "polyhedra_rendered_elements" | "selected_sites" | "measured_sites" | "added_bonds" | "removed_bonds" | "bond_order_overrides" | "bond_edit_mode" | "scene" | "hidden_elements" | "hidden_prop_vals" | "element_radius_overrides" | "site_radius_overrides" | "add_atom_mode" | "add_element" | "dragging_atoms" | "hovered_site_idx">;
+type StructureViewport = ReturnType<typeof StructureViewport>;
+export default StructureViewport;

package/dist/structure/atom-label-placement.d.ts

@@ -0,0 +1,18 @@
+import type { Vec3 } from '../math';
+import type { Camera } from 'three';
+import { Matrix4 } from 'three';
+export declare const LABEL_OFFSET_EPS = 1e-9;
+export declare const choose_site_label_offset: (bond_directions: Vec3[], base_offset: Vec3) => Vec3;
+export type LabelPlacement = {
+    x: number;
+    y: number;
+    visible: boolean;
+};
+export declare class LabelProjector {
+    #private;
+    update(camera: Camera, anchor_world_matrix: Matrix4, size: {
+        width: number;
+        height: number;
+    }, margin: number): void;
+    place(position: Vec3, offset: Vec3, visual_radius: number, out: LabelPlacement): void;
+}

package/dist/structure/atom-label-placement.js

@@ -0,0 +1,115 @@
+import * as math from '../math';
+import { Matrix4 } from 'three';
+export const LABEL_OFFSET_EPS = 1e-9;
+const LABEL_OFFSET_DIRECTIONS = [
+    [0, -1, 0],
+    [1, 0, 0],
+    [-1, 0, 0],
+    [1, 1, 0],
+    [-1, 1, 0],
+    [1, -1, 0],
+    [-1, -1, 0],
+    [0, 0, 1],
+    [0, 0, -1],
+];
+const label_direction_score = (direction, bond_directions, preferred_direction) => {
+    let max_bond_alignment = 0;
+    for (const bond_direction of bond_directions) {
+        max_bond_alignment = Math.max(max_bond_alignment, Math.max(0, math.dot(direction, bond_direction)));
+    }
+    const preferred_bonus = Math.max(0, math.dot(direction, preferred_direction)) * 0.05;
+    const screen_plane_bonus = Math.abs(direction[2]) < LABEL_OFFSET_EPS ? 0.02 : 0;
+    return -max_bond_alignment + preferred_bonus + screen_plane_bonus;
+};
+export const choose_site_label_offset = (bond_directions, base_offset) => {
+    const offset_length = Math.hypot(...base_offset);
+    if (offset_length < LABEL_OFFSET_EPS || bond_directions.length === 0) {
+        return base_offset;
+    }
+    const preferred_direction = math.normalize_vec(base_offset, [0, 1, 0]);
+    const repulsion_direction = math.normalize_vec(bond_directions.reduce((offset_sum, bond_direction) => math.subtract(offset_sum, bond_direction), [0, 0, 0]), preferred_direction);
+    let best_direction = preferred_direction;
+    let best_score = -Infinity;
+    for (const candidate_direction of [
+        preferred_direction,
+        repulsion_direction,
+        ...LABEL_OFFSET_DIRECTIONS,
+    ]) {
+        const direction = math.normalize_vec(candidate_direction, preferred_direction);
+        const score = label_direction_score(direction, bond_directions, preferred_direction);
+        if (score <= best_score + LABEL_OFFSET_EPS)
+            continue;
+        best_score = score;
+        best_direction = direction;
+    }
+    return math.scale(best_direction, offset_length);
+};
+// Per-frame screen projector for label overlays. `update()` precomputes the
+// combined model-view-projection once per frame; `place()` then resolves each
+// label with a single clip-space transform and zero allocations (labels run
+// per site per frame, so the old 3-projections-per-label path with fresh
+// Vector3s dominated frame time on large supercells).
+//
+// Placement semantics match the previous label_screen_position helper: the
+// label sits `atom_screen_radius + margin` px from the atom center along the
+// screen direction of its offset. The projected radius is measured along the
+// camera's right axis, which for both projections equals
+// visual_radius * projection[5] * (height/2) / clip_w.
+export class LabelProjector {
+    #mvp = new Matrix4(); // projection * view * anchor (local -> clip space)
+    #view = new Matrix4(); // view * anchor (local -> view space, for behind-camera test)
+    #half_width = 0;
+    #half_height = 0;
+    #radius_scale = 0; // clip-space multiplier for projected atom radius
+    #margin = 0;
+    update(camera, anchor_world_matrix, size, margin) {
+        this.#view.multiplyMatrices(camera.matrixWorldInverse, anchor_world_matrix);
+        this.#mvp.multiplyMatrices(camera.projectionMatrix, this.#view);
+        this.#half_width = size.width / 2;
+        this.#half_height = size.height / 2;
+        // projectionMatrix[5] = cot(fov/2) for perspective, 2/(top-bottom) for ortho
+        this.#radius_scale = camera.projectionMatrix.elements[5] * this.#half_height;
+        this.#margin = margin;
+    }
+    // position + offset: label anchor and preferred direction in anchor-local
+    // space; visual_radius: atom radius in the same units
+    place(position, offset, visual_radius, out) {
+        const [pos_x, pos_y, pos_z] = position;
+        const mvp = this.#mvp.elements;
+        const view = this.#view.elements;
+        // Behind-camera test in view space (camera looks down -z)
+        const view_z = view[2] * pos_x + view[6] * pos_y + view[10] * pos_z + view[14];
+        if (view_z > 0) {
+            out.visible = false;
+            return;
+        }
+        const clip_x = mvp[0] * pos_x + mvp[4] * pos_y + mvp[8] * pos_z + mvp[12];
+        const clip_y = mvp[1] * pos_x + mvp[5] * pos_y + mvp[9] * pos_z + mvp[13];
+        const clip_w = mvp[3] * pos_x + mvp[7] * pos_y + mvp[11] * pos_z + mvp[15];
+        const screen_x = (clip_x / clip_w) * this.#half_width + this.#half_width;
+        const screen_y = (-clip_y / clip_w) * this.#half_height + this.#half_height;
+        // Screen direction of the offset: project position + offset and take the
+        // screen-space delta. Projecting the second point (instead of just rotating
+        // the offset into view space) keeps perspective foreshortening exact for
+        // offsets with a depth component, matching the pre-projector behavior.
+        const [off_x, off_y, off_z] = offset;
+        const end_x = pos_x + off_x;
+        const end_y = pos_y + off_y;
+        const end_z = pos_z + off_z;
+        const end_clip_x = mvp[0] * end_x + mvp[4] * end_y + mvp[8] * end_z + mvp[12];
+        const end_clip_y = mvp[1] * end_x + mvp[5] * end_y + mvp[9] * end_z + mvp[13];
+        const end_clip_w = mvp[3] * end_x + mvp[7] * end_y + mvp[11] * end_z + mvp[15];
+        const delta_x = (end_clip_x / end_clip_w) * this.#half_width + this.#half_width - screen_x;
+        const delta_y = (-end_clip_y / end_clip_w) * this.#half_height + this.#half_height - screen_y;
+        const dir_len = Math.hypot(delta_x, delta_y);
+        // Offsets along the view axis have no screen direction; nudge upward like
+        // the previous implementation (screen y grows downward)
+        const dir_x = dir_len > LABEL_OFFSET_EPS ? delta_x / dir_len : 0;
+        const dir_y = dir_len > LABEL_OFFSET_EPS ? delta_y / dir_len : off_y >= 0 ? -1 : 1;
+        const atom_screen_radius = (visual_radius * this.#radius_scale) / clip_w;
+        const screen_gap = Math.abs(atom_screen_radius) + this.#margin;
+        out.x = screen_x + dir_x * screen_gap;
+        out.y = screen_y + dir_y * screen_gap;
+        out.visible = true;
+    }
+}