Pinstar

https://docs.rs/pinstar
Admin
Pinstar is a terminal canvas and diagram editor library and engine for Obsidian-compatible .canvas...
Tokens:208,649
Snippets:1,406
Trust Score:9.1
Update:3 days ago
Show doc for...
Tokens:
Raw
### Grid tests setup

Source: https://docs.rs/pinstar/latest/src/pinstar/grid.rs.html?search=std%3A%3Avec

Test module for grid functionality, including a helper to create projections.

```rust
#[cfg(test)]
mod tests {
    use super::*;
    use ratatui::{Terminal, backend::TestBackend};

    fn projection(
        cols_per_world_x: f64,
        rows_per_world_y: f64,
        step_x: f64,
        step_y: f64,
    ) -> CanvasGridProjection {
        let (world_top, world_bottom) = if rows_per_world_y.is_sign_negative() {
            (-step_y, 0.0)
```

--------------------------------

### ImageCache::install_decoded

Source: https://docs.rs/pinstar/latest/pinstar/image/struct.ImageCache.html

Installs a completed decode result and builds the protocol renderer.

```APIDOC
## ImageCache::install_decoded

### Description
Installs a completed decode result and builds the protocol renderer.

### Method
install_decoded

### Signature
pub fn install_decoded(&mut self, img: DecodedImage, picker: &Picker)

### Parameters
- **img** (DecodedImage) - Required - The decoded image to install.
- **picker** (&Picker) - Required - The picker used to build the protocol renderer.

### Returns
- **()** - No return value.
```

--------------------------------

### ImageCache::install_decoded

Source: https://docs.rs/pinstar/latest/pinstar/image/struct.ImageCache.html?search=

Installs a completed decode result and builds the protocol renderer.

```APIDOC
## ImageCache::install_decoded

### Description
Installs a completed decode result and builds the protocol renderer.

### Method
pub fn install_decoded(&mut self, img: DecodedImage, picker: &Picker)

### Parameters
- **img** (DecodedImage) - Required - The decoded image to install.
- **picker** (&Picker) - Required - The picker used to build the protocol renderer.
```

--------------------------------

### ImageCache::get_proto

Source: https://docs.rs/pinstar/latest/pinstar/image/struct.ImageCache.html?search=

Gets a mutable reference to the protocol for rendering, if ready.

```APIDOC
## ImageCache::get_proto

### Description
Gets a mutable reference to the protocol for rendering, if ready.

### Method
pub fn get_proto(&mut self, key: &PathBuf) -> Option<&mut StatefulProtocol>

### Parameters
- **key** (&PathBuf) - Required - The path to the image file.

### Returns
Option<&mut StatefulProtocol> - A mutable reference to the protocol if ready, otherwise None.
```

--------------------------------

### ImageCache::get_proto

Source: https://docs.rs/pinstar/latest/pinstar/image/struct.ImageCache.html

Gets a mutable reference to the protocol for rendering, if ready.

```APIDOC
## ImageCache::get_proto

### Description
Gets a mutable reference to the protocol for rendering, if ready.

### Method
get_proto

### Signature
pub fn get_proto(&mut self, key: &PathBuf) -> Option<&mut StatefulProtocol>

### Parameters
- **key** (&PathBuf) - Required - The path to the image file.

### Returns
- **Option<&mut StatefulProtocol>** - A mutable reference to the protocol if ready, otherwise None.
```

--------------------------------

### MarqueeState::on_down

Source: https://docs.rs/pinstar/latest/pinstar/overlay/struct.MarqueeState.html

Handles the mouse down event, recording the starting position.

```APIDOC
## MarqueeState::on_down

### Description
Handles the mouse down event, recording the starting position of the marquee selection.

### Method
pub fn on_down(&mut self, x: f64, y: f64)

### Parameters
- **x** (f64) - Required - The x-coordinate of the mouse down position.
- **y** (f64) - Required - The y-coordinate of the mouse down position.
```

--------------------------------

### Test eviction module

Source: https://docs.rs/pinstar/latest/src/pinstar/image.rs.html

Unit test setup for verifying cache eviction behavior.

```rust
139#[cfg(test)]
140mod tests {
141    use super::*;
142
143    #[test]
144    fn test_eviction() {
145        let mut cache = ImageCache::new(2);
146
147        let dir = std::env::temp_dir().join("pinstar_test_img_cache");
```

--------------------------------

### type_id

Source: https://docs.rs/pinstar/latest/pinstar/data/struct.CanvasData.html?search=std%3A%3Avec

Gets the TypeId of self.

```APIDOC
## type_id

### Description
Gets the `TypeId` of `self`.

### Method
fn type_id(&self) -> TypeId

### Returns
- **TypeId** - The type identifier of the value.
```

--------------------------------

### Any::type_id

Source: https://docs.rs/pinstar/latest/pinstar/menu/enum.PinstarMenuType.html?search=std%3A%3Avec

Gets the TypeId of self. This is a standard method from the Any trait.

```APIDOC
## Any::type_id

### Description
Gets the `TypeId` of `self`.

### Method
`fn type_id(&self) -> TypeId`

### Returns
- `TypeId` - The type identifier of the value.
```

--------------------------------

### Pointable::Init

Source: https://docs.rs/pinstar/latest/pinstar/data/struct.LinkNode.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

The type for initializers.

```APIDOC
## Pointable::Init

### Description
The type for initializers.

### Type
type Init = T
```

--------------------------------

### Pointable::init

Source: https://docs.rs/pinstar/latest/pinstar/data/enum.DiagramOrientation.html

Initializes a with the given initializer.

```APIDOC
## Pointable::init

### Description
Initializes a with the given initializer.

### Method
init

### Signature
unsafe fn init(init: <T as Pointable>::Init) -> usize

### Parameters
- **init** (<T as Pointable>::Init) - Required - The initializer value.

### Returns
- **usize** - The pointer to the initialized value.
```

--------------------------------

### ThemeColors style and color helper methods

Source: https://docs.rs/pinstar/latest/src/pinstar/theme.rs.html?search=std%3A%3Avec

Provides methods on ThemeColors for generating styles with background colors, deriving preview and hint line colors, and parsing color codes from optional strings.

```Rust
51impl ThemeColors {
52    pub fn bg_style(&self) -> Style {
53        Style::default().bg(self.bg)
54    }
55
56    pub fn hover_style(&self) -> Style {
57        Style::default().bg(self.highlight_bg).fg(self.highlight_fg)
58    }
59
60    pub fn preview_bg(&self) -> Color {
61        derive_color(self.bg, -15).unwrap_or(self.bg)
62    }
63
64    pub fn hint_line_bg(&self) -> Color {
65        derive_color(self.bg, -8).unwrap_or(self.bg)
66    }
67
68    pub fn preview_bg_style(&self) -> Style {
69        Style::default().bg(self.preview_bg())
70    }
71
72    pub fn hint_line_bg_style(&self) -> Style {
73        Style::default().bg(self.hint_line_bg())
74    }
75
76    pub fn parse_color(color_code: Option<&str>, theme: &ThemeColors) -> Color {
77        match color_code {
78            Some(s) if s.starts_with('#') => parse_hex_color(s).unwrap_or(theme.accent),
79            _ => get_node_color(color_code, theme),
80        }
81    }
82}
```

--------------------------------

### Hex color parsing

Source: https://docs.rs/pinstar/latest/src/pinstar/theme.rs.html

Parses a string starting with '#' into a Color::Rgb.

```rust
pub fn parse_hex_color(s: &str) -> Option<Color> {
    let s = s.strip_prefix('#')?;
    if s.len() == 6 {
        let r = u8::from_str_radix(&s[0..2], 16).ok()?;
        let g = u8::from_str_radix(&s[2..4], 16).ok()?;
        let b = u8::from_str_radix(&s[4..6], 16).ok()?;
        return Some(Color::Rgb(r, g, b));
    }
    None
}
```

--------------------------------

### MarqueeState::clear

Source: https://docs.rs/pinstar/latest/pinstar/overlay/struct.MarqueeState.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Clears the marquee state, resetting start and end points.

```APIDOC
## MarqueeState::clear

### Description
Clears the marquee state, resetting start and end points.

### Method
clear

### Signature
pub fn clear(&mut self)

### Parameters
None

### Returns
void
```

--------------------------------

### help_content

Source: https://docs.rs/pinstar/latest/pinstar/help/fn.help_content.html?search=u32+-%3E+bool

Generates help content lines for a given help tab, theme, and maximum width. Returns a vector of Line<'static> objects.

```APIDOC
## help_content

### Description
Generates help content lines for a given help tab, theme, and maximum width. Returns a vector of Line<'static> objects.

### Function Signature
pub fn help_content(
    tab: PinstarHelpTab,
    theme: &ThemeColors,
    max_width: u16,
) -> Vec<Line<'static>>

### Parameters
- **tab** (PinstarHelpTab) - Required - The help tab for which to generate content.
- **theme** (&ThemeColors) - Required - The theme colors to use for styling.
- **max_width** (u16) - Required - The maximum width for the content lines.

### Returns
- **Vec<Line<'static>>** - A vector of Line objects representing the help content.
```

--------------------------------

### MarqueeState::clear

Source: https://docs.rs/pinstar/latest/pinstar/overlay/struct.MarqueeState.html

Clears the marquee state, resetting start and end positions.

```APIDOC
## MarqueeState::clear

### Description
Clears the marquee state, resetting the start and end positions to None.

### Method
pub fn clear(&mut self)
```

--------------------------------

### pub fn help_content(tab: PinstarHelpTab, theme: &ThemeColors, max_width: u16) -> Vec<Line<'static>>

Source: https://docs.rs/pinstar/latest/pinstar/help/fn.help_content.html

Generates help content lines for the specified help tab, using the given theme and maximum width. Returns a vector of Line objects.

```APIDOC
## Function help_content

### Description
Generates help content lines for the specified help tab, using the given theme and maximum width.

### Signature
pub fn help_content(
    tab: PinstarHelpTab,
    theme: &ThemeColors,
    max_width: u16,
) -> Vec<Line<'static>>

### Parameters
- **tab** (PinstarHelpTab) - Required - The help tab for which to generate content.
- **theme** (&ThemeColors) - Required - The theme colors to use for styling.
- **max_width** (u16) - Required - The maximum width for the content lines.

### Returns
- **Vec<Line<'static>>** - A vector of Line objects containing the help content.
```

--------------------------------

### execute_menu_action

Source: https://docs.rs/pinstar/latest/pinstar/input/fn.execute_menu_action.html

Executes a context-menu item by label. Returns a host request for 'Add Image Node'.

```APIDOC
## execute_menu_action

### Description
Executes a context-menu item by label. Returns a host request for 'Add Image Node'.

### Function Signature
pub fn execute_menu_action(
    state: &mut PinstarState,
    label: &str,
    menu_type: PinstarMenuType,
    menu_x: u16,
    menu_y: u16,
) -> ActionOutcome

### Parameters
- **state** (&mut PinstarState) - Required - Mutable reference to the application state.
- **label** (&str) - Required - The label of the context-menu item to execute.
- **menu_type** (PinstarMenuType) - Required - The type of the context menu.
- **menu_x** (u16) - Required - The x-coordinate of the menu.
- **menu_y** (u16) - Required - The y-coordinate of the menu.

### Returns
- **ActionOutcome** - The outcome of the action, including a host request for 'Add Image Node'.
```

--------------------------------

### execute_menu_action

Source: https://docs.rs/pinstar/latest/pinstar/input/fn.execute_menu_action.html?search=std%3A%3Avec

Executes a context-menu item by label. Returns a host request for 'Add Image Node'.

```APIDOC
## execute_menu_action

### Description
Executes a context-menu item by label. Returns a host request for 'Add Image Node'.

### Function Signature
pub fn execute_menu_action(
    state: &mut PinstarState,
    label: &str,
    menu_type: PinstarMenuType,
    menu_x: u16,
    menu_y: u16,
) -> ActionOutcome

### Parameters
- **state** (&mut PinstarState) - Required - Mutable reference to the Pinstar state.
- **label** (&str) - Required - The label of the context-menu item to execute.
- **menu_type** (PinstarMenuType) - Required - The type of the context menu.
- **menu_x** (u16) - Required - The x-coordinate of the menu.
- **menu_y** (u16) - Required - The y-coordinate of the menu.

### Returns
- **ActionOutcome** - The outcome of the action, including a host request for 'Add Image Node'.
```

--------------------------------

### execute_menu_action

Source: https://docs.rs/pinstar/latest/pinstar/input/fn.execute_menu_action.html?search=u32+-%3E+bool

Executes a context-menu item by label. Returns a host request for 'Add Image Node'.

```APIDOC
## execute_menu_action

### Description
Executes a context-menu item by label. Returns a host request for 'Add Image Node'.

### Function Signature
```rust
pub fn execute_menu_action(
    state: &mut PinstarState,
    label: &str,
    menu_type: PinstarMenuType,
    menu_x: u16,
    menu_y: u16,
) -> ActionOutcome
```

### Parameters
- **state** (`&mut PinstarState`) - Required - Mutable reference to the application state.
- **label** (`&str`) - Required - The label of the context-menu item to execute.
- **menu_type** (`PinstarMenuType`) - Required - The type of the context menu.
- **menu_x** (`u16`) - Required - The x-coordinate of the menu.
- **menu_y** (`u16`) - Required - The y-coordinate of the menu.

### Return Value
- **ActionOutcome** - The outcome of the action, including a host request for 'Add Image Node'.
```

--------------------------------

### Full hex color parsing

Source: https://docs.rs/pinstar/latest/src/pinstar/theme.rs.html

Helper to parse a hex color string if it starts with '#'.

```rust
fn parse_hex_color_full(s: &str) -> Option<Color> {
    if s.starts_with('#') {
        parse_hex_color(s)
    } else {
        None
    }
}
```

--------------------------------

### MarqueeState::on_down

Source: https://docs.rs/pinstar/latest/pinstar/overlay/struct.MarqueeState.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Handles the mouse down event, setting the start point of the marquee selection.

```APIDOC
## MarqueeState::on_down

### Description
Handles the mouse down event, setting the start point of the marquee selection.

### Method
on_down

### Signature
pub fn on_down(&mut self, x: f64, y: f64)

### Parameters
- **x** (f64) - Required - The x-coordinate of the mouse down event.
- **y** (f64) - Required - The y-coordinate of the mouse down event.

### Returns
void
```

--------------------------------

### Initialize CanvasGridProjection

Source: https://docs.rs/pinstar/latest/src/pinstar/grid.rs.html?search=

Constructs a CanvasGridProjection instance with specified world coordinates and grid scaling factors.

```rust
CanvasGridProjection {
            world_left: 0.0,
            world_right: step_x,
            world_top,
            world_bottom,
            origin_col: 0.0,
            origin_row: 0.0,
            cols_per_world_x,
            rows_per_world_y,
        }
```

--------------------------------

### MarqueeState::is_dragging_screen

Source: https://docs.rs/pinstar/latest/pinstar/overlay/struct.MarqueeState.html

Determines whether the screen is being dragged based on the current and start positions.

```APIDOC
## MarqueeState::is_dragging_screen

### Description
Checks if the screen is being dragged by comparing the current and start screen coordinates.

### Method
pub fn is_dragging_screen(&self, sx_now: u16, sy_now: u16, sx_start: u16, sy_start: u16) -> bool

### Parameters
- **sx_now** (u16) - Required - The current x-coordinate on screen.
- **sy_now** (u16) - Required - The current y-coordinate on screen.
- **sx_start** (u16) - Required - The starting x-coordinate on screen.
- **sy_start** (u16) - Required - The starting y-coordinate on screen.

### Returns
- **bool** - True if the screen is being dragged, false otherwise.
```

--------------------------------

### zoom_step

Source: https://docs.rs/pinstar/latest/pinstar/camera/index.html?search=std%3A%3Avec

Performs a zoom step. Input is zoom*factor, output is zoom/factor floored at `min`. Rejects non-finite input.

```APIDOC
## Function: zoom_step

### Description
Performs a zoom step. Input is zoom*factor, output is zoom/factor floored at `min`. Rejects non-finite input.

### Signature
`zoom_step`

### Parameters
- `zoom` (number) - Required - The current zoom value.
- `factor` (number) - Required - The zoom factor.
- `min` (number) - Required - The minimum zoom value.

### Returns
- The new zoom value, floored at `min`.
```

--------------------------------

### zoom_step

Source: https://docs.rs/pinstar/latest/pinstar/camera/index.html

Applies a zoom step. Input: zoom * factor. Output: zoom / factor floored at `min`. Rejects non-finite input.

```APIDOC
## zoom_step

### Description
Applies a zoom step. Input: zoom * factor. Output: zoom / factor floored at `min`. Rejects non-finite input.

### Function
zoom_step

### Parameters
- **zoom** - Current zoom value.
- **factor** - Zoom factor.
- **min** - Minimum zoom value.

### Returns
Zoom value after applying the step, floored at `min`.
```

--------------------------------

### help_content

Source: https://docs.rs/pinstar/latest/pinstar/help/fn.help_content.html?search=std%3A%3Avec

Generates help content lines for a specified help tab, using the provided theme colors and maximum width. Returns a vector of Line<'static> objects.

```APIDOC
## help_content

### Description
Generates help content lines for a specified help tab, using the provided theme colors and maximum width. Returns a vector of Line<'static> objects.

### Function Signature
pub fn help_content(
    tab: PinstarHelpTab,
    theme: &ThemeColors,
    max_width: u16,
) -> Vec<Line<'static>>

### Parameters
- **tab** (PinstarHelpTab) - Required - The help tab for which to generate content.
- **theme** (&ThemeColors) - Required - The theme colors to use for styling the content.
- **max_width** (u16) - Required - The maximum width for the content lines.

### Returns
- **Vec<Line<'static>>** - A vector of Line objects containing the generated help content.
```

--------------------------------

### Selection::new

Source: https://docs.rs/pinstar/latest/pinstar/selection/struct.Selection.html?search=u32+-%3E+bool

Creates a new empty Selection instance.

```APIDOC
## Selection::new

### Description
Creates a new empty Selection instance.

### Method
new

### Signature
pub fn new() -> Self

### Parameters
None

### Returns
Self - A new Selection with primary set to None and extra as an empty HashSet.
```

--------------------------------

### MarqueeState::is_dragging_screen

Source: https://docs.rs/pinstar/latest/pinstar/overlay/struct.MarqueeState.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Determines whether the user is dragging the screen based on current and start screen coordinates.

```APIDOC
## MarqueeState::is_dragging_screen

### Description
Determines whether the user is dragging the screen based on current and start screen coordinates.

### Method
is_dragging_screen

### Signature
pub fn is_dragging_screen(&self, sx_now: u16, sy_now: u16, sx_start: u16, sy_start: u16) -> bool

### Parameters
- **sx_now** (u16) - Required - The current x-coordinate on screen.
- **sy_now** (u16) - Required - The current y-coordinate on screen.
- **sx_start** (u16) - Required - The starting x-coordinate on screen.
- **sy_start** (u16) - Required - The starting y-coordinate on screen.

### Returns
bool - True if the screen is being dragged, false otherwise.
```

--------------------------------

### MarqueeState struct and implementation

Source: https://docs.rs/pinstar/latest/src/pinstar/overlay.rs.html

Defines the state for a marquee selection, including start and end coordinates and a threshold for drag detection.

```rust
pub struct MarqueeState {
    pub start: Option<(f64, f64)>,
    pub end: Option<(f64, f64)>,
    pub threshold_cells: u32,
}

impl MarqueeState {
    pub fn new(threshold_cells: u32) -> Self {
        Self {
            start: None,
            end: None,
            threshold_cells,
        }
    }

    pub fn on_down(&mut self, x: f64, y: f64) {
        self.start = Some((x, y));
        self.end = Some((x, y));
    }

    pub fn on_drag(&mut self, x: f64, y: f64) {
        self.end = Some((x, y));
    }

    pub fn is_dragging_screen(
        &self,
        sx_now: u16,
        sy_now: u16,
        sx_start: u16,
        sy_start: u16,
    ) -> bool {
        let dx = sx_now.abs_diff(sx_start);
        let dy = sy_now.abs_diff(sy_start);
        u32::from(dx) + u32::from(dy) > self.threshold_cells
    }

    pub fn commit_rect(&self) -> Option<(f64, f64, f64, f64)> {
        let (sx, sy) = self.start?;
        let (ex, ey) = self.end?;
        Some((sx.min(ex), sy.min(ey), sx.max(ex), sy.max(ey)))
    }

    pub fn clear(&mut self) {
        self.start = None;
        self.end = None;
    }
}
```

--------------------------------

### PinstarHelpTab::prev

Source: https://docs.rs/pinstar/latest/pinstar/state/enum.PinstarHelpTab.html

Returns the previous help tab in the sequence.

```APIDOC
## PinstarHelpTab::prev

### Description
Returns the previous help tab in the sequence.

### Signature
pub fn prev(self) -> Self

### Parameters
- self (PinstarHelpTab) - The current help tab.

### Returns
The previous PinstarHelpTab variant.
```

--------------------------------

### Build menu item specifications

Source: https://docs.rs/pinstar/latest/src/pinstar/menu.rs.html?search=

Constructs a list of menu item specifications based on the menu type, selection state, format, and image support.

```rust
pub fn menu_specs(
    kind: PinstarMenuType,
    selected_node: bool,
    format: SupportedFormat,
    images_enabled: bool,
) -> Vec<MenuItemSpec> {
    let labels: Vec<&'static str> = match kind {
        PinstarMenuType::Canvas => {
            let mut items = if selected_node {
                vec![
                    "Create Connection",
                    "Delete Connection",
                    "Rename Node",
                    "Resize Node",
                    "Set Shape...",
                    "Set Color...",
                    "Delete All Connections",
                    "Delete Node",
                ]
            } else {
                let mut v = vec!["Add Text Node"];
```

--------------------------------

### MouseTextSelection::begin

Source: https://docs.rs/pinstar/latest/pinstar/textsel/struct.MouseTextSelection.html

Begins a mouse text selection on the given text area. This method should be called when the user starts a selection action.

```APIDOC
## MouseTextSelection::begin

### Description
Begins a mouse text selection on the given text area. This method should be called when the user starts a selection action.

### Method
begin

### Signature
pub fn begin(&mut self, textarea: &mut TextArea<'static>)

### Parameters
- **textarea** (&mut TextArea<'static>) - Required - The text area on which the selection is initiated.

### Returns
No return value.
```

--------------------------------

### MouseTextSelection::begin

Source: https://docs.rs/pinstar/latest/pinstar/textsel/struct.MouseTextSelection.html?search=std%3A%3Avec

Begins a mouse text selection operation on the given text area. This method is called when the user starts a selection with the mouse.

```APIDOC
## MouseTextSelection::begin

### Description
Begins a mouse text selection operation on the given text area. This method is called when the user starts a selection with the mouse.

### Method
pub fn begin(&mut self, textarea: &mut TextArea<'static>)

### Parameters
- **self** (&mut MouseTextSelection) - The mutable reference to the selection state.
- **textarea** (&mut TextArea<'static>) - The text area on which the selection begins.

### Returns
No return value.
```

--------------------------------

### From and Into Methods

Source: https://docs.rs/pinstar/latest/pinstar/input/struct.ActionOutcome.html

Standard conversion methods between types.

```APIDOC
## From and Into Methods

### Description
Standard conversion methods that allow converting between types.

### Methods

#### fn from(t: T) -> T
- Returns the argument unchanged.

#### fn into(self) -> U
- Calls `U::from(self)`. This conversion is whatever the implementation of `From<T> for U` chooses to do.
```

--------------------------------

### ImageCache structure and methods

Source: https://docs.rs/pinstar/latest/src/pinstar/image.rs.html?search=

Defines the ImageCache for managing decoded images and protocol renderers, including methods for requesting images and installing decoded results.

```rust
pub struct ImageCache {
    map: lru::LruCache<PathBuf, ImageEntry>,
}

struct ImageEntry {
    /// Created lazily from decoded + picker; `None` while decode pending.
    proto: Option<StatefulProtocol>,
}

impl ImageCache {
    pub fn new(limit: usize) -> Self {
        Self {
            map: lru::LruCache::new(NonZeroUsize::new(limit.max(1)).expect("limit >= 1")),
        }
    }

    /// Request an image for display. If the key is absent, sends a decode job
    /// to the worker. Call `install_decoded` when the result arrives.
    pub fn request(&mut self, key: PathBuf, max_dim: u32, tx: &Sender<ImageJob>) {
        if self.map.contains(&key) {
            // Touch existing entry
            let _ = self.map.get_mut(&key);
            return;
        }
        let _ = tx.send(ImageJob {
            key: key.clone(),
            max_dim,
        });
        self.map.put(key, ImageEntry { proto: None });
    }

    /// Install a completed decode result and build the protocol renderer.
    pub fn install_decoded(&mut self, img: DecodedImage, picker: &Picker) {
        if let Some(entry) = self.map.get_mut(&img.key) {
            let proto = picker.new_resize_protocol(img.image);
            entry.proto = Some(proto);
        }
    }

    /// Get a mutable reference to the protocol for rendering, if ready.
    pub fn get_proto(&mut self, key: &PathBuf) -> Option<&mut StatefulProtocol> {
        self.map.get_mut(key).and_then(|entry| entry.proto.as_mut())
    }
}
```

--------------------------------

### PinstarHelpTab::next

Source: https://docs.rs/pinstar/latest/pinstar/state/enum.PinstarHelpTab.html

Returns the next help tab in the sequence.

```APIDOC
## PinstarHelpTab::next

### Description
Returns the next help tab in the sequence.

### Signature
pub fn next(self) -> Self

### Parameters
- self (PinstarHelpTab) - The current help tab.

### Returns
The next PinstarHelpTab variant.
```

--------------------------------

### zoom_step

Source: https://docs.rs/pinstar/latest/pinstar/camera/index.html?search=u32+-%3E+bool

In: zoom*factor. Out: zoom/factor floored at `min`. Rejects non-finite.

```APIDOC
## zoom_step

### Description
In: zoom*factor. Out: zoom/factor floored at `min`. Rejects non-finite.

### Function
zoom_step

### Parameters
- `zoom` - Input zoom value.
- `factor` - Zoom factor.
- `min` - Minimum zoom value.

### Returns
Zoom value divided by factor, floored at `min`.
```

--------------------------------

### PinstarHelpTab enum with ALL, title, next, and prev methods

Source: https://docs.rs/pinstar/latest/src/pinstar/state.rs.html?search=

Defines the help tab navigation enum with Keyboard, Mouse, Menus, and Formats variants. Provides methods for cycling through tabs and getting display titles.

```rust
pub enum PinstarHelpTab {
    Keyboard,
    Mouse,
    Menus,
    Formats,
}

impl PinstarHelpTab {
    pub const ALL: [PinstarHelpTab; 4] = [
        PinstarHelpTab::Keyboard,
        PinstarHelpTab::Mouse,
        PinstarHelpTab::Menus,
        PinstarHelpTab::Formats,
    ];

    pub fn title(self) -> &'static str {
        match self {
            PinstarHelpTab::Keyboard => "Keyboard",
            PinstarHelpTab::Mouse => "Mouse",
            PinstarHelpTab::Menus => "Menus",
            PinstarHelpTab::Formats => "Formats",
        }
    }

    pub fn next(self) -> Self {
        match self {
            PinstarHelpTab::Keyboard => PinstarHelpTab::Mouse,
            PinstarHelpTab::Mouse => PinstarHelpTab::Menus,
            PinstarHelpTab::Menus => PinstarHelpTab::Formats,
            PinstarHelpTab::Formats => PinstarHelpTab::Keyboard,
        }
    }

    pub fn prev(self) -> Self {
        match self {
            PinstarHelpTab::Keyboard => PinstarHelpTab::Formats,
            PinstarHelpTab::Mouse => PinstarHelpTab::Keyboard,
            PinstarHelpTab::Menus => PinstarHelpTab::Mouse,
            PinstarHelpTab::Formats => PinstarHelpTab::Menus,
        }
    }
}
```

--------------------------------

### Selection struct implementation in Rust

Source: https://docs.rs/pinstar/latest/src/pinstar/selection.rs.html?search=std%3A%3Avec

Defines a generic Selection<Id> struct with a primary optional item and a HashSet of extra items. Provides methods to select only one item, clear selections, manage the extra set, add items, check selection status, get all selected items, check emptiness, and count selections. Implements Default for Selection.

```Rust
1//! Multi-select state for canvas nodes (ported from clin's `ui::CanvasSelection`).
2
3use std::collections::HashSet;
4use std::hash::Hash;
5
6pub struct Selection<Id: Eq + Hash + Clone> {
7    pub primary: Option<Id>,
8    pub extra: HashSet<Id>,
9}
10
11impl<Id: Eq + Hash + Clone> Selection<Id> {
12    pub fn new() -> Self {
13        Self {
14            primary: None,
15            extra: HashSet::new(),
16        }
17    }
18
19    pub fn select_only(&mut self, id: Id) {
20        self.primary = Some(id);
21        self.extra.clear();
22    }
23
24    pub fn clear(&mut self) {
25        self.primary = None;
26        self.extra.clear();
27    }
28
29    pub fn clear_set(&mut self) {
30        self.extra.clear();
31    }
32
33    pub fn replace_set(&mut self, set: HashSet<Id>, primary: Option<Id>) {
34        self.extra = set;
35        self.primary = primary;
36    }
37
38    pub fn add(&mut self, id: Id) {
39        self.extra.insert(id);
40    }
41
42    pub fn is_selected(&self, id: &Id) -> bool {
43        self.primary.as_ref().is_some_and(|p| p == id) || self.extra.contains(id)
44    }
45
46    pub fn all(&self) -> HashSet<Id> {
47        let mut out = self.extra.clone();
48        if let Some(p) = &self.primary {
49            out.insert(p.clone());
50        }
51        out
52    }
53
54    pub fn is_empty(&self) -> bool {
55        self.primary.is_none() && self.extra.is_empty()
56    }
57
58    pub fn count(&self) -> usize {
59        self.extra.len() + usize::from(self.primary.is_some())
60    }
61}
62
63impl<Id: Eq + Hash + Clone> Default for Selection<Id> {
64    fn default() -> Self {
65        Self::new()
66    }
67}
```

--------------------------------

### Implement Default Settings

Source: https://docs.rs/pinstar/latest/src/pinstar/lib.rs.html?search=std%3A%3Avec

Provides default values for the Pinstar Settings configuration.

```rust
impl Default for Settings {
    fn default() -> Self {
        Self {
            enable_image_nodes: false,
            image_cache_size: 32,
            rename_uses_id: false,
            show_hints: true,
        }
    }
}
```

--------------------------------

### help_content

Source: https://docs.rs/pinstar/latest/pinstar/help/fn.help_content.html?search=

Generates help content lines for a given help tab, theme, and maximum width. Returns a vector of Line items for rendering.

```APIDOC
## help_content

### Description
Generates help content lines for a given help tab, theme, and maximum width. Returns a vector of Line items for rendering.

### Function Signature
pub fn help_content(
    tab: PinstarHelpTab,
    theme: &ThemeColors,
    max_width: u16,
) -> Vec<Line<'static>>

### Parameters
- **tab** (PinstarHelpTab) - Required - The help tab to generate content for.
- **theme** (&ThemeColors) - Required - The theme colors to use for styling.
- **max_width** (u16) - Required - The maximum width for the content lines.

### Return Value
- **Vec<Line<'static>>** - A vector of Line items representing the help content.
```

--------------------------------

### Unit Tests for Camera Utilities

Source: https://docs.rs/pinstar/latest/src/pinstar/camera.rs.html

Verification tests for zoom bounds, coordinate clamping, and directional search logic.

```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn zoom_in_out_bounds() {
        assert!(zoom_step(1.0, 1.1, ZoomDir::In, 0.0).unwrap() > 1.0);
        assert!(zoom_step(1.0, 1.1, ZoomDir::Out, 0.05).unwrap() < 1.0);
        assert_eq!(zoom_step(0.04, 1.1, ZoomDir::Out, 0.05).unwrap(), 0.05);
        assert!(zoom_step(f64::NAN, 1.1, ZoomDir::In, 0.0).is_none());
    }

    #[test]
    fn clamp_world_nonfinite() {
        assert_eq!(clamp_world(f64::NAN), 0.0);
        assert_eq!(clamp_world(5.0), 5.0);
    }

    #[test]
    fn nearest_in_cone_prefers_straightest() {
        let cands = [(1.0, 0.0), (1.0, 0.4)];
        let idx = nearest_in_dir(&cands, (0.0, 0.0), (1.0, 0.0), std::f64::consts::FRAC_PI_3);
        assert_eq!(idx, Some(0));
    }
}
```

--------------------------------

### zoom_step(zoom: f64, factor: f64, dir: ZoomDir, min: f64) -> Option<f64>

Source: https://docs.rs/pinstar/latest/pinstar/camera/fn.zoom_step.html?search=u32+-%3E+bool

Computes the next zoom value based on the given direction. For In, returns zoom * factor; for Out, returns zoom / factor floored at min. Returns None if any input is non-finite.

```APIDOC
## Function: zoom_step

### Description
Computes the next zoom value based on the given direction. For In, returns zoom * factor; for Out, returns zoom / factor floored at min. Returns None if any input is non-finite.

### Signature
pub fn zoom_step(zoom: f64, factor: f64, dir: ZoomDir, min: f64) -> Option<f64>

### Parameters
- **zoom** (f64) - Required - The current zoom value.
- **factor** (f64) - Required - The zoom factor to apply.
- **dir** (ZoomDir) - Required - The zoom direction (In or Out).
- **min** (f64) - Required - The minimum zoom value for the Out direction.

### Return Value
- **Option<f64>** - Some(f64) if all inputs are finite, otherwise None. For In, returns zoom * factor. For Out, returns zoom / factor floored at min.

### Behavior
- If dir is In, returns Some(zoom * factor).
- If dir is Out, returns Some(max(zoom / factor, min)).
- Rejects non-finite inputs (NaN or infinity) by returning None.
```

--------------------------------

### TryInto::try_into

Source: https://docs.rs/pinstar/latest/pinstar/data/struct.TextNode.html?search=std%3A%3Avec

Performs the conversion.

```APIDOC
## TryInto::try_into

### Description
Performs the conversion.

### Method
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

### Parameters
- **self** (Self) - The value to convert.

### Returns
- **Result<U, <U as TryFrom<T>>::Error>** - The converted value or an error.
```

--------------------------------

### ThemeColors::preview_bg_style

Source: https://docs.rs/pinstar/latest/pinstar/theme/struct.ThemeColors.html

Returns a Style for preview backgrounds.

```APIDOC
## ThemeColors::preview_bg_style

### Description
Returns a Style for preview backgrounds.

### Method
pub fn preview_bg_style(&self) -> Style

### Parameters
None

### Returns
- **Style** - The style for preview backgrounds.
```

--------------------------------

### help_content(PinstarHelpTab, &ThemeColors, u16) -> Vec<Line<'static>>

Source: https://docs.rs/pinstar/latest/pinstar/help/fn.help_content.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Generates help content lines for the specified help tab, using the provided theme and maximum width. This function is part of the pinstar crate's public API.

```APIDOC
## Function help_content

### Description
Generates help content lines for a given help tab, using the provided theme and maximum width.

### Signature
pub fn help_content(
    tab: PinstarHelpTab,
    theme: &ThemeColors,
    max_width: u16,
) -> Vec<Line<'static>>

### Parameters
- **tab** (PinstarHelpTab) - Required - The help tab for which to generate content.
- **theme** (&ThemeColors) - Required - The theme colors to use for styling the content.
- **max_width** (u16) - Required - The maximum width for the content lines.

### Returns
- **Vec<Line<'static>>** - A vector of lines representing the help content.
```

--------------------------------

### Map menu items to keyboard shortcuts

Source: https://docs.rs/pinstar/latest/src/pinstar/menu.rs.html

Provides a single source of truth for keyboard shortcuts across different menu types, used for both hint display and input handling.

```rust
pub fn menu_item_shortcut_char(menu_type: PinstarMenuType, item: &str) -> Option<char> {
    match menu_type {
        PinstarMenuType::Canvas => match item {
            "Create Connection" => Some('c'),
            "Delete Connection" => Some('d'),
            "Rename Node" => Some('r'),
            "Resize Node" => Some('s'),
            "Set Shape..." => Some('p'),
            "Set Color..." => Some('o'),
            "Delete All Connections" => Some('b'),
            "Delete Node" => Some('x'),
            "Add Text Node" => Some('t'),
            "Add Group" => Some('g'),
            "Add Image Node" => Some('m'),
            _ => None,
        },
        PinstarMenuType::Editor => match item {
            "Copy" => Some('c'),
            "Cut" => Some('x'),
            "Paste" => Some('v'),
            "Select All" => Some('a'),
            _ => None,
        },
        PinstarMenuType::EdgeMenu => match item {
            "Set Color..." => Some('o'),
            "Set Style..." => Some('s'),
            _ => None,
        },
        PinstarMenuType::ShapePicker => match item {
            "Rectangle" => Some('r'),
            "Diamond" => Some('d'),
            "Circle" => Some('c'),
            "Cylinder" => Some('y'),
            "Stadium" => Some('s'),
            _ => None,
        },
        PinstarMenuType::ColorPicker | PinstarMenuType::EdgeColorPicker => match item {
            "Default" => Some('d'),
            "Red" => Some('r'),
            "Orange" => Some('o'),
            "Yellow" => Some('y'),
            "Green" => Some('g'),
            "Cyan" => Some('c'),
            "Purple" => Some('p'),
            "Blue" => Some('b'),
            "Magenta" => Some('m'),
            "White" => Some('w'),
            _ => None,
        },
        PinstarMenuType::EdgeStylePicker => match item {
            "Solid" => Some('s'),
            "Dashed" => Some('d'),
            "Dotted" => Some('t'),
            _ => None,
        },
        PinstarMenuType::OrientationPicker => match item {
            "Top-Down" => Some('t'),
            "Left-Right" => Some('l'),
            "Right-Left" => Some('r'),
            "Bottom-Up" => Some('b'),
            _ => None,
        },
    }
}
```

--------------------------------

### TryFrom::try_from

Source: https://docs.rs/pinstar/latest/pinstar/data/struct.TextNode.html?search=std%3A%3Avec

Performs the conversion.

```APIDOC
## TryFrom::try_from

### Description
Performs the conversion.

### Method
fn try_from(value: U) -> Result<T, !>

### Parameters
- **value** (U) - The value to convert.

### Returns
- **Result<T, !>** - The converted value or an error.
```

--------------------------------

### zoom_step

Source: https://docs.rs/pinstar/latest/pinstar/camera/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Applies a zoom step. Input is zoom multiplied by factor, output is zoom divided by factor, floored at the minimum zoom. Rejects non-finite input.

```APIDOC
## zoom_step

### Description
Applies a zoom step. Input is zoom multiplied by factor, output is zoom divided by factor, floored at the minimum zoom. Rejects non-finite input.

### Function
zoom_step

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Pointable::init

Source: https://docs.rs/pinstar/latest/pinstar/data/struct.LinkNode.html

Initializes a pointer with the given initializer. This is an unsafe function.

```APIDOC
## Pointable::init

### Description
Initializes a pointer with the given initializer. This is an unsafe function.

### Method
init

### Signature
unsafe fn init(init: <T as Pointable>::Init) -> usize

### Parameters
- **init** (<T as Pointable>::Init) - Required - The initializer value.

### Returns
- **usize** - The initialized pointer.
```

--------------------------------

### Build menu item specifications

Source: https://docs.rs/pinstar/latest/src/pinstar/menu.rs.html

Constructs a list of menu item specifications based on the menu type and current application state, such as selection status and format capabilities.

```rust
pub fn menu_specs(
    kind: PinstarMenuType,
    selected_node: bool,
    format: SupportedFormat,
    images_enabled: bool,
) -> Vec<MenuItemSpec> {
    let labels: Vec<&'static str> = match kind {
        PinstarMenuType::Canvas => {
            let mut items = if selected_node {
                vec![
                    "Create Connection",
                    "Delete Connection",
                    "Rename Node",
                    "Resize Node",
                    "Set Shape...",
                    "Set Color...",
                    "Delete All Connections",
                    "Delete Node",
                ]
            } else {
```

--------------------------------

### zoom_step(zoom: f64, factor: f64, dir: ZoomDir, min: f64) -> Option<f64>

Source: https://docs.rs/pinstar/latest/pinstar/camera/fn.zoom_step.html

Computes the next zoom value based on the given direction and factor. If dir is In, returns zoom * factor; if dir is Out, returns zoom / factor floored at min. Returns None for non-finite inputs.

```APIDOC
## Function: zoom_step

### Description
Computes the next zoom value based on the given direction and factor. If dir is In, returns zoom * factor; if dir is Out, returns zoom / factor floored at min. Returns None for non-finite inputs.

### Signature
pub fn zoom_step(zoom: f64, factor: f64, dir: ZoomDir, min: f64) -> Option<f64>

### Parameters
- **zoom** (f64) - Required - The current zoom value.
- **factor** (f64) - Required - The factor by which to multiply or divide the zoom.
- **dir** (ZoomDir) - Required - The direction of zoom: In or Out.
- **min** (f64) - Required - The minimum value for the zoom when zooming out.

### Return Value
- **Option<f64>** - Returns Some(f64) with the new zoom value, or None if any input is non-finite.

### Behavior
- If dir is In: returns zoom * factor.
- If dir is Out: returns zoom / factor, floored at min.
- Rejects non-finite inputs (NaN or infinity) by returning None.
```

--------------------------------

### MenuItemSpec::new

Source: https://docs.rs/pinstar/latest/pinstar/menu/struct.MenuItemSpec.html

Creates a new MenuItemSpec with the given label. The shortcut and color_hint fields are initialized to None.

```APIDOC
## MenuItemSpec::new

### Description
Creates a new MenuItemSpec with the given label. The shortcut and color_hint fields are initialized to None.

### Method
pub const fn new(label: &'static str) -> Self

### Parameters
- **label** (&'static str) - Required - The label for the menu item.

### Returns
- **Self** - A new MenuItemSpec instance.

```

--------------------------------

### pinstar::execute_menu_action

Source: https://docs.rs/pinstar/latest/pinstar/index.html?search=std%3A%3Avec

Executes a menu action.

```APIDOC
## Function: execute_menu_action

### Description
Executes a menu action.

### Signature
`pub fn execute_menu_action(state: &mut PinstarState, action: PinstarAction) -> ActionOutcome`

### Parameters
- **state** (`&mut PinstarState`) - Required - The editor state.
- **action** (`PinstarAction`) - Required - The action to execute.

### Returns
- `ActionOutcome` - The outcome of executing the action.
```
Tokens:
Raw