fission-core

The runtime, widget system, and action/reducer architecture for the Fission UI framework.

fission-core is the central crate of the Fission toolkit. It provides the declarative widget tree, the unidirectional data-flow architecture (actions, reducers, effects), and the runtime that ties everything together. Applications describe their UI as a Widget tree built from composable widgets, dispatch Action values to modify GlobalState, and let the runtime lower the tree into the intermediate representation consumed by platform renderers.

Architecture overview

  From<Component>          Runtime::dispatch()
       |                        |
  ViewHandle<S> + BuildCtxHandle<S>  ActionEnvelope
       |                        |
Widget tree      Reducer(s)
       |                        |
  internal lowering          mutate GlobalState
       |                    + emit Effects
    CoreIR (fission-ir)          |
       |                   EffectEnvelope
  LayoutEngine                  |
       |                 Platform executor
    Renderer

1. Widget layer -- From<Component> for Widget builds the authored tree. Components that need state or action wiring request scoped ViewHandle<S> and BuildCtxHandle<S> values through fission::build::current::<S>().
2. Internal lowering -- Fission converts Widget values into fission-ir operations (paint ops, layout ops, semantics). This is not part of normal application authoring.
3. Layout -- fission-layout resolves flex, grid, scroll, and absolute positioning.
4. Rendering -- Platform backends (Metal, Skia, HTML Canvas) consume the laid-out IR.
5. Actions -- User interactions produce ActionEnvelope values that the Runtime dispatches to registered reducers.
6. Reducers -- Pure functions that mutate GlobalState and optionally emit side-effects through Effects.
7. Effects -- Asynchronous operations (HTTP, file I/O, alerts) that the platform executor runs outside the deterministic core.

Key concepts

GlobalState

Any Send + Sync + Debug + 'static type that implements GlobalState. The runtime stores one instance per concrete type.

Action / ActionEnvelope

Action is a trait for strongly-typed, serialisable event payloads. Actions are transported as ActionEnvelope (type-erased ID + JSON bytes) so the reducer pipeline stays generic.

BuildCtxHandle

The scoped context handle available during authoring conversion. Use it to:

• Bind actions to handlers: with_reducer!(ctx, MyAction { .. }, my_handler) or #[fission_reducer(MyAction)] for compact one-reducer actions
• Register portals (overlays, modals, toasts)
• Request animations

ViewHandle

Read-only scoped access to GlobalState, the current theme, i18n registry, layout snapshot, and animation values.

Widget

The closed authored widget tree carrier. It has one variant per built-in widget such as Button, Text, Row, and Column; application components produce it with impl From<Component> for Widget.

Effects

Reducers that need async work (network, disk, timers) push EffectEnvelope values through Effects. The platform executor fulfils them and dispatches the on_ok / on_err callbacks back into the action pipeline.

Quick example

use fission::prelude::*;

// 1. Define state
#[derive(Debug, Default)]
struct Counter { count: i32 }
impl GlobalState for Counter {}

// 2. Define a reducer. This also generates the Increment action.
#[fission_reducer(Increment)]
fn handle_increment(state: &mut Counter) {
    state.count += 1;
}

// 3. Build the widget tree
struct CounterWidget;
impl From<CounterWidget> for Widget {
    fn from(_: CounterWidget) -> Self {
        let (ctx, view) = fission::build::current::<Counter>();
        let on_press = with_reducer!(ctx, Increment, handle_increment);
        Column {
            children: vec![
                Text::new(format!("Count: {}", view.state().count)).into(),
                Button {
                    child: Some(Text::new("Add one").into()),
                    on_press: Some(on_press),
                    ..Default::default()
                }.into(),
            ],
            ..Default::default()
        }.into()
    }
}

Crate feature flags

None at this time -- all functionality is included by default.

License

MIT