chose iced, documented decision and basics

AGENTS.md

···
 
 key decisions
 -------------
-  2025-10-25: chose dioxus desktop (standalone)
+  2025-10-25: chose iced
     why:
-      - native rendering (not webview/DOM)
-      - react-like syntax (familiar)
-      - no tauri IPC boundary issues
-      - handles large datasets well
-      - windows support + accessibility
+      - TRUE native rendering (no DOM/webview)
+      - elm architecture (clean patterns)
+      - handles 60k items natively
+      - system76 backing (cosmic desktop)
+      - actual GPU performance
 
     rejected:
-      - tauri: IPC boundary loses type safety
-      - egui: immediate mode, less familiar
-      - iced: accessibility gaps
-      - yew: older, heavier
+      - tauri: IPC boundary loses type safety, still DOM
+      - dioxus: discovered it uses webview/DOM anyway
+      - egui: immediate mode, friend suggested iced instead
+      - yew: older, heavier, still web tech
+
+    tradeoffs accepted:
+      - accessibility gaps (screen reader/IME)
+      - we're okay with this for now
 
 
 architecture notes
 ------------------
   tech stack:
-    - dioxus desktop (native rendering)
+    - iced (native GPU rendering)
     - rust for data handling
     - radio4000 API for data source
 
-  getting started:
-    cargo install dioxus-cli --locked
-
-  optional (if we need tauri later):
-    cargo install tauri-cli --version '^2.0.0' --locked
+  structure:
+    /r4  → dioxus prototype (abandoned)
+    TBD  → new iced project
 
 
                     .---.
···
 - changelog format → ~/Notes/changelogs.md
 
 
-last updated: 2025-10-25 (chose dioxus, defined project goal)
+last updated: 2025-10-25 (chose iced after exploring options)

docs/iced.txt

···
+iced reference
+==============
+
+source: https://docs.iced.rs/iced/
+
+
+the elm architecture
+--------------------
+
+iced follows the elm architecture with four core parts:
+
+  state      → the data (struct with fields)
+  messages   → interactions (enum variants)
+  update     → how messages change state (fn)
+  view       → how state dictates widgets (fn)
+
+flow:
+  widgets produce messages
+  messages trigger update
+  update changes state
+  state dictates new view
+  repeat...
+
+
+basic structure
+---------------
+
+pub fn main() -> iced::Result {
+    iced::run(update, view)
+}
+
+fn update(state: &mut State, message: Message) {
+    match message {
+        Message::Increment => state.value += 1,
+    }
+}
+
+fn view(state: &State) -> Element<'_, Message> {
+    button(text(state.value))
+        .on_press(Message::Increment)
+        .into()
+}
+
+#[derive(Debug, Clone)]
+enum Message {
+    Increment,
+}
+
+
+widgets
+-------
+
+widgets are VALUES not side effects
+created with helper functions from iced::widget
+
+  button("+")              → button widget
+  text("hello")            → text widget
+  column![a, b, c]         → vertical layout
+  row![a, b, c]            → horizontal layout
+  container(widget)        → positioning/alignment
+
+configured with builder pattern:
+  button("+")
+      .on_press(Message::Inc)
+      .style(button::primary)
+      .width(Fill)
+
+
+layout
+------
+
+no unified layout system
+each widget has its own strategy
+
+common patterns:
+  - column for vertical stacking
+  - row for horizontal stacking
+  - container for positioning/centering
+  - spacing() for gaps between children
+
+  container(
+      column![
+          "Top",
+          row!["Left", "Right"].spacing(10),
+          "Bottom"
+      ].spacing(10)
+  )
+  .padding(10)
+  .center_x(Fill)
+  .center_y(Fill)
+
+
+sizing
+------
+
+Length enum controls widget dimensions:
+
+  Fill      → take all available space
+  Shrink    → use intrinsic size (default)
+  Pixels(n) → fixed size
+
+  container("text")
+      .height(300)
+      .width(Fill)
+
+
+styling
+-------
+
+each widget has .style() method
+takes closure: (theme, status) -> style
+
+  button("Click")
+      .style(|theme: &Theme, status| {
+          match status {
+              button::Status::Active => {
+                  button::Style::default()
+                      .with_background(theme.palette().primary)
+              }
+              _ => button::primary(theme, status)
+          }
+      })
+
+convenience functions:
+  - container::rounded_box
+  - button::primary
+  - text::danger
+
+
+theming
+-------
+
+use application builder for custom theme:
+
+  iced::application(new, update, view)
+      .theme(theme)
+      .run()
+
+  fn theme(state: &State) -> Theme {
+      Theme::TokyoNight
+  }
+
+built-in themes:
+  - Theme::Dark
+  - Theme::Light
+  - Theme::TokyoNight
+  - etc
+
+
+tasks (async work)
+------------------
+
+update can return Task<Message>
+used for async operations
+
+  fn update(state: &mut State, msg: Message) -> Task<Message> {
+      match msg {
+          Message::Fetch => {
+              Task::perform(fetch_data(), Message::Fetched)
+          }
+          Message::Fetched(data) => {
+              state.data = Some(data);
+              Task::none()
+          }
+      }
+  }
+
+tasks can:
+  - run futures/streams
+  - interact with runtime (window, focus, etc)
+  - be mapped, chained, batched, canceled
+
+
+subscriptions (passive data)
+-----------------------------
+
+subscribe to external events:
+  - time ticks
+  - window resize
+  - keyboard events
+
+  fn subscription(state: &State) -> Subscription<Message> {
+      window::resize_events()
+          .map(|(_, size)| Message::Resized(size))
+  }
+
+subscriptions are declarative
+only what's returned is active (like view)
+
+
+scaling apps
+------------
+
+update/view/message compose nicely
+common pattern: split into screens
+
+  enum Screen {
+      Contacts(Contacts),
+      Chat(Chat),
+  }
+
+  enum Message {
+      Contacts(contacts::Message),
+      Chat(chat::Message),
+  }
+
+each screen has own update/view
+parent coordinates via Action enum
+use .map() to compose messages
+
+  screen.view().map(Message::Contacts)
+
+
+key principles
+--------------
+
+- widgets are values, no side effects
+- state is application-specific
+- type system prevents invalid states
+- messages are pure data (derive Debug, Clone)
+- view is pure function of state
+- leverages rust: ownership, traits, enums, etc
+
+
+important types
+---------------
+
+Element<'a, Message>  → generic widget
+Task<Message>         → async work
+Subscription<Message> → passive events
+Length                → Fill, Shrink, Pixels(n)
+Theme                 → appearance

docs/workflow.txt

···
+workflow
+========
+
+principles
+----------
+- docs are for agents to rebuild context quickly
+- AGENTS.md is the entry point for new sessions
+- todo.txt tracks current work
+- CHANGELOG.md tracks what's done
+- jj for version control (see ~/Notes/jj.md)
+
+
+onboarding new context
+----------------------
+when starting fresh:
+  1. read AGENTS.md (or CLAUDE.md symlink)
+  2. read todo.txt to see current tasks
+  3. check relevant docs/ files as needed
+  4. check CHANGELOG.md for recent history
+
+
+docs structure
+--------------
+  AGENTS.md         → main context file for AI agents
+  CLAUDE.md         → symlink to AGENTS.md
+  README.md         → project overview
+  todo.txt          → current work, backlog
+  CHANGELOG.md      → completed work history
+
+  docs/
+    README.md       → docs folder overview
+    iced.txt        → iced framework reference
+    workflow.txt    → this file
+
+
+working with jj
+---------------
+use freely:
+  jj describe -m "message"   → describe current change
+  jj new                     → start new change
+
+see ~/Notes/jj.md for full reference
+
+
+completing tasks
+----------------
+1. do the work
+2. update CHANGELOG.md with what changed
+3. check off in todo.txt or move to backlog
+4. jj describe + jj new
+5. update AGENTS.md if decisions made
+
+
+context files to read first
+---------------------------
+always start with:
+  - AGENTS.md (decisions, status, references)
+  - todo.txt (what's next)
+
+read as needed:
+  - docs/iced.txt (framework reference)
+  - docs/workflow.txt (this file)
+  - CHANGELOG.md (history)
+
+
+keeping context fresh
+---------------------
+update AGENTS.md when:
+  - making architecture decisions
+  - learning something important
+  - changing approach
+
+keep it concise, use our ascii style
+future you (or other agent) will thank you

todo.txt

···
 
 next
 ----
-[ ] install dioxus-cli
-[ ] create initial dioxus desktop project
+[ ] create iced project
+[ ] hello world in iced
 [ ] fetch radio4000 data structure