Build apps for SmileyOS.

your app  =  a struct implementing AppContext   (apps/yourapp.rs)
           +  one AppInfo entry in the registry   (apps/registry.rs)

pub trait AppContext {
    fn handle_keyboard(&mut self, key: u8) -> AppAction;
 
    // Typed non-ASCII text (e.g. Cyrillic). Default: ignore.
    fn handle_text(&mut self, _cp: u32) -> AppAction { AppAction::Continue }
 
    // Whether this app currently wants free-text input (a focused field).
    fn wants_text_input(&self) -> bool { false }
 
    fn handle_mouse(&mut self, mouse: &MouseState) -> AppAction;
    fn update(&mut self) -> AppAction;
    fn draw(&mut self, buffer: &mut [u8], stride: usize,
            bytes_per_pixel: usize, gfx: &Graphics) -> AppAction;
    fn needs_redraw(&self) -> bool;
 
    // SDK hook: open a file's bytes (see Capabilities). Default: no-op.
    fn open_file(&mut self, _filename: &str, _content: &[u8]) {}
 
    // SDK hook: handle a deeplink (see Capabilities). Default: no-op.
    fn accept_deeplink(&mut self, _scheme: &str, _arg: &str) {}
}

use crate::apps::framework::{AppAction, AppContext, Window};
use crate::drivers::mouse::MouseState;
use crate::graphics::graphics::Graphics;
 
pub struct YourApp {
    window: Window,
    pub needs_redraw: bool,
}
 
impl YourApp {
    pub fn new(screen_width: usize, screen_height: usize, _initial_left_button: bool) -> Self {
        // Some(w)/Some(h) = centered window; None/None = fullscreen below the menu bar.
        let window = Window::new("Your App", screen_width, screen_height, Some(400), Some(300));
        Self { window, needs_redraw: true }
    }
 
    pub fn set_needs_redraw(&mut self) { self.needs_redraw = true; }
    pub fn cleanup(&mut self) {}
}
 
impl AppContext for YourApp {
    fn handle_keyboard(&mut self, key: u8) -> AppAction {
        // Window handles ESC = minimize, Shift+ESC = quit.
        if let Some(action) = self.window.handle_keyboard(key) { return action; }
        AppAction::Continue
    }
 
    fn handle_mouse(&mut self, mouse: &MouseState) -> AppAction {
        if let Some(action) = self.window.handle_mouse(mouse) { return action; }
        AppAction::Continue
    }
 
    fn update(&mut self) -> AppAction { AppAction::Continue }
 
    fn draw(&mut self, buffer: &mut [u8], stride: usize,
            bytes_per_pixel: usize, gfx: &Graphics) -> AppAction {
        if self.needs_redraw {
            self.window.draw(buffer, stride, bytes_per_pixel, gfx);
            self.needs_redraw = false;
        }
        AppAction::Continue
    }
 
    fn needs_redraw(&self) -> bool { self.needs_redraw }
}

// (a) define_apps! — generates the AppInstance/AppId variants + dispatch:
YourApp(YourApp) {
    create: |ctx| YourApp::new(ctx.screen_width, ctx.screen_height, ctx.mouse_left_button),
    commands: ["yourapp"]
},
 
// (b) APP_REGISTRY — the manifest (ALL fields are required):
AppInfo {
    name: "Your App Name",
    command: "yourapp",
    alt_command: None,                  // or Some("alias")
    app_type: AppType::Ui,              // or AppType::Game
    show_in_menu: true,
    menu_category: MenuCategory::Main,  // or System / Hidden
    separator_before: false,            // draw a menu separator above this item
    aliases: &[],                       // extra command/search aliases
    file_extensions: &[],               // e.g. &[".foo"]
    deeplink_schemes: &[],              // e.g. &["foo"]
    spotlight_name: None,               // Some("Your App") to show in Spotlight
    spotlight_rank: 0,                  // launcher order when shown
},

pub struct Counter {
    window: Window,
    value: i32,
    step: i32,
    card: Card,            // raised container for the big value
    progress: ProgressBar, // value clamped to 0..100
    step_stepper: Stepper, // picks the +/- step size
    even_badge: Badge,     // "EVEN" pill
    odd_badge: Badge,      // "ODD" pill
    plus_button: Button,
    minus_button: Button,
    reset_button: Button,
    last_mouse_button: bool,
    pub needs_redraw: bool,
}

// In Counter::new(...) — construct the widgets once and keep them in fields.
let card = Card::new(inner_x, card_y, inner_w, card_h, "Value");
let progress = ProgressBar::new(inner_x, prog_y, inner_w, "Progress to 100", 0);
let step_stepper = Stepper::new(inner_x, step_y, "Step size", 1, 100, 1, 1);
 
// Two pills at the same spot; visibility toggles by parity (value 0 = even).
let even_badge = Badge::info(inner_x, badge_y, "EVEN");
let mut odd_badge = Badge::warning(inner_x, badge_y, "ODD");
odd_badge.set_visible(false);
 
let minus_button = Button::new(start_x, btn_y, 70, 48, "-")
    .with_style(ButtonStyle::Danger);
let plus_button = Button::new(plus_x, btn_y, 70, 48, "+")
    .with_style(ButtonStyle::Primary);

// One place changes the value and refreshes the widgets that depend on it.
fn set_value(&mut self, value: i32) {
    self.value = value;
    self.progress.set_value(self.value.clamp(0, 100) as u8); // 0..=100 bar
    let is_even = self.value % 2 == 0;
    self.even_badge.set_visible(is_even);                     // EVEN / ODD pill
    self.odd_badge.set_visible(!is_even);
    self.needs_redraw = true;
}

fn draw(&mut self, buffer: &mut [u8], stride: usize,
        bytes_per_pixel: usize, gfx: &Graphics) -> AppAction {
    if self.needs_redraw {
        self.window.draw(buffer, stride, bytes_per_pixel, gfx);
        // ...clear background, draw the keyboard hints...
        self.card.dirty = true;      // on a full redraw, mark every widget
        self.progress.dirty = true;  // (Card / ProgressBar / Stepper / Badge / Buttons)
        self.needs_redraw = false;
    }
    // Draw each widget only when dirty — draw() clears its own dirty flag.
    if self.card.is_dirty() {
        self.card.draw(buffer, stride, bytes_per_pixel, gfx);
        self.draw_value_number(buffer, stride, bytes_per_pixel);
    }
    if self.progress.is_dirty() { self.progress.draw(buffer, stride, bytes_per_pixel, gfx); }
    // ...badges, stepper, buttons...
    AppAction::Continue
}

// 1. construct (store in an app field)
let mut volume = Slider::new(x, y, 200, "Volume", 0, 100, 5, 50);
 
// 2. input (edge-triggered click for Button; other widgets debounce internally)
let clicked = self.save_btn.handle_mouse(mouse, button_pressed);
if self.volume.handle_mouse(mouse) {
    // slider value changed -> react to self.volume.value
}
 
// 3. draw the ones that need it (draw() clears the dirty flag)
if self.volume.is_dirty() {
    self.volume.draw(buffer, stride, bytes_per_pixel, gfx);
}

pub struct AppInfo {
    // ...identity / menu fields...
 
    // ---- Capability manifest ----
    // Extra command/search aliases (shell recognition + Spotlight search).
    pub aliases: &'static [&'static str],
    // File extensions this app opens, incl. the dot, e.g. &[".smy", ".smproj"].
    // Empty = claims none (the text editor is the fallback for unknown types).
    pub file_extensions: &'static [&'static str],
    // Deeplink schemes handled, without the ':' — &["geo"] => geo:<arg>.
    pub deeplink_schemes: &'static [&'static str],
 
    // ---- Spotlight launcher ----
    // Some(name) shows the app in Spotlight with that name; None hides it.
    pub spotlight_name: Option<&'static str>,
    // Display order in the Spotlight launcher (lower = earlier).
    pub spotlight_rank: u8,
}

// Open a file's bytes in this app. Override if you register file_extensions.
fn open_file(&mut self, _filename: &str, _content: &[u8]) {}
 
// Handle a deeplink aimed at this app, e.g. scheme "geo", arg "Paris".
// Override if you register deeplink_schemes.
fn accept_deeplink(&mut self, _scheme: &str, _arg: &str) {}

AppInfo {
    name: "Counter",
    command: "counter",
    alt_command: Some("count"),
    app_type: AppType::Ui,
    show_in_menu: true,
    menu_category: MenuCategory::Main,
    separator_before: false,
    aliases: &["count"],            // searchable / typeable alias
    file_extensions: &[".cnt"],     // Counter opens .cnt files
    deeplink_schemes: &["count"],   // count:<n> deeplink
    spotlight_name: None,
    spotlight_rank: 0,
},
 
// ...and add the alias to its define_apps! entry so it's constructible by name:
Counter(Counter) {
    create: |ctx| Counter::new(ctx.screen_width, ctx.screen_height, ctx.mouse_left_button),
    commands: ["counter", "count"]
},

impl AppContext for Counter {
    // ...handle_keyboard / handle_mouse / update / draw / needs_redraw...
 
    // A .cnt file is just the saved counter value as text (e.g. "42").
    fn open_file(&mut self, _filename: &str, content: &[u8]) {
        if let Some(value) = core::str::from_utf8(content)
            .ok()
            .and_then(|s| s.trim().parse::<i32>().ok())
        {
            self.set_value(value);
        }
    }
 
    // count:42  ->  set the counter to 42
    fn accept_deeplink(&mut self, _scheme: &str, arg: &str) {
        if let Ok(value) = arg.trim().parse::<i32>() {
            self.set_value(value);
        }
    }
}

const UPDATE_MS: u32 = 100; // 10 updates/sec
 
pub struct MyGame { base: GameBase, player_x: usize, player_y: usize }
 
impl MyGame {
    pub fn new(width: usize, height: usize) -> Self {
        let base = GameBase::with_controls("My Game", width, height, b"WASD - Move");
        let area_h = base.game_height.saturating_sub(INFO_BAR_HEIGHT);
        Self { base, player_x: base.game_width / 2, player_y: area_h / 2 }
    }
    pub fn set_needs_redraw(&mut self) { self.base.needs_redraw = true; }
    pub fn cleanup(&mut self) {}
}
 
impl AppContext for MyGame {
    fn update(&mut self) -> AppAction {
        if !self.base.should_update(UPDATE_MS) { return AppAction::Continue; }
        // ...advance game state... (only runs while playing)
        AppAction::Continue
    }
 
    fn handle_keyboard(&mut self, key: u8) -> AppAction {
        // F1 pause, SPACE/ENTER start, ESC minimize, Shift+ESC quit:
        if let Some(action) = self.base.handle_common_input(key) { return action; }
        if self.base.game_over || self.base.game_won {
            if GameBase::is_restart_key(key) { self.reset(); }
            return AppAction::Continue;
        }
        if !self.base.paused && !self.base.showing_start_menu {
            match key {
                b'W' | b'w' => self.player_y = self.player_y.saturating_sub(4),
                b'S' | b's' => self.player_y += 4,
                b'A' | b'a' => self.player_x = self.player_x.saturating_sub(4),
                b'D' | b'd' => self.player_x += 4,
                _ => {}
            }
        }
        AppAction::Continue
    }
 
    fn handle_mouse(&mut self, _mouse: &MouseState) -> AppAction { AppAction::Continue }
    fn needs_redraw(&self) -> bool { true }
}

fn render(&mut self, buffer: &mut [u8], stride: usize, bpp: usize, gfx: &Graphics) {
    let c = self.base.window.content_rect();
    let area_y = c.y + INFO_BAR_HEIGHT;
 
    if self.base.first_render {
        self.base.window.draw(buffer, stride, bpp, gfx);
        self.base.draw_background(gfx, buffer, stride, c.x, c.y, c.width, c.height);
        self.base.draw_info_bar(gfx, buffer, stride, bpp, c.x, c.y, c.width,
                                b"WASD | F1 pause | ESC quit");
        self.base.first_render = false;
        self.base.overlay_drawn = false;
    }
 
    if self.base.showing_start_menu { self.base.draw_start_menu(/* ... */); return; }
    if self.base.paused            { self.base.draw_pause_overlay(/* ... */); return; }
 
    // ...clear the old player cell, draw the new one...
    gfx.fill_rect(buffer, stride, c.x + self.player_x, area_y + self.player_y,
                  16, 16, &Color::GREEN);
 
    if self.base.game_over { self.base.draw_game_over_overlay(/* "GAME OVER!" */); }
}

pub fn handle_command<'a>(&self, command: &'a str) -> CommandResult<'a> {
    let parts: [&str; 10] = /* split on whitespace, up to 10 tokens */;
    if parts[0].is_empty() { return CommandResult::Empty; }
 
    // App commands win first — registry-driven, no per-app code here.
    if registry::is_app_command(parts[0]) {
        return CommandResult::LaunchApp(parts[0]);
    }
 
    match parts[0] {
        "help"  => CommandResult::Help,
        "clear" => CommandResult::Clear,
        "echo"  => CommandResult::Echo(command.strip_prefix("echo").unwrap_or("").trim()),
        "ls"    => CommandResult::Ls,
        "cat"   => CommandResult::Cat(parts[1]),
        // ...~40 more...
        _ => CommandResult::Unknown(parts[0]),
    }
}

@core
@shell
// Comments start with //  ·  every shell program opens with directives:
//   @core  = variables, conditions, loops, functions
//   @shell = text in/out  (add @system for rand/sleep/dates/files)
 
outLine("Hello, World!");
outLine("Welcome to Smilium!");

gfx.fill_rect(buffer, stride, x, y, width, height, &color);
gfx.draw_rect(buffer, stride, x, y, width, height, &color);   // 1px outline
gfx.fill_circle(buffer, stride, center_x, center_y, radius, &color);
gfx.draw_pixel(buffer, stride, x, y, &color);
 
// Color is crate::graphics::color::Color:
let c = Color::new(r, g, b);   // plus consts like Color::WHITE, Color::GREEN

use crate::graphics::text::{draw_text, draw_char_scaled};
 
// A text run (8px font). text is &[u8] — use a byte string b"...".
draw_text(buffer, stride, bytes_per_pixel, x, y, b"Hello", &Color::WHITE);
 
// One character scaled up (e.g. a big counter readout at 5x):
draw_char_scaled(buffer, stride, bytes_per_pixel, x, y, b'7', &Color::GREEN, 5);

use crate::graphics::theme::get_theme;
 
let theme = get_theme();              // &'static ThemeColors
let bg     = theme.bg_primary;
let panel  = theme.bg_secondary;
let text   = theme.text_primary;
let dim    = theme.text_secondary;
let accent = theme.accent;
let border = theme.window_border;

menu click / terminal command
        |
        v
registry::is_app_command(word)              // is it an app?
        | yes
        v
mode_transitions::launch_app_by_command(...)
        |
        v
AppInstance::from_command(cmd, ctx)         // built by the define_apps! macro
        |
        v
ModeManager launches it; the main loop then
dispatches handle_keyboard / handle_mouse / update / draw to your app