unicycle 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Uplift Systems Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,463 @@
+# Unicycle
+
+Unicycle is a lightweight, routed model-view-intent (MVI) plus sinks framework built on top of [Cycle.js](https://cycle.js.org), [Vite](https://vite.dev), and [xstream](https://github.com/staltz/xstream).
+
+It assumes that you use the aforementioned tooling. This framework is very opinionated in that way.
+
+## Table of Contents
+
+1. [Getting Started](#getting-started)
+    1. [Installation](#installation)
+    2. [Project Structure](#project-structure)
+2. [Model-View-Intent Basics](#model-view-intent-basics)
+    1. [App-Level MVI](#app-level-mvi)
+    2. [Route-Level MVI](#route-level-mvi)
+3. [Wrapping it Up](#wrapping-it-up)
+
+## Getting Started
+
+### Installation
+
+First, install the Unicycle package.
+
+```bash
+npm install unicycle
+```
+
+Next, install core dependencies.
+
+```bash
+npm install @cycle/dom xstream
+npm install -D vite
+```
+
+When you set up your package, it assumes it is of type `module`.
+
+This is the bare minimum of what your `package.json` should look like:
+
+```JSON
+{
+  "name": "your-package",
+  "version": "x.x.x",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "type": "module",
+  "dependencies": {
+    "@cycle/dom": "x.x.x",
+    "unicycle": "x.x.x",
+    "xstream": "x.x.x"
+  },
+  "devDependencies": {
+    "vite": "x.x.x"
+  }
+}
+```
+
+### Project Structure
+
+A Unicycle project takes the following structure:
+
+```
+project-root/
+├─src/
+| ├─app/
+| | ├─app.client.js
+| | ├─app.intent.js
+| | ├─app.model.js
+| | └─app.view.js
+| ├─components/
+| ├─routes/
+| | └─route_name
+| | | ├─route_name.intent.js
+| | | ├─route_name.model.js
+| | | ├─route_name.route.js
+| | | └─route_name.view.js
+| ├─static/
+| └─utils/
+├─index.html
+├─package.json
+└─vite.config.js
+```
+
+The `/src/app` folder contains your application-level code, which includes model, view, intent, and other sinks, which runs for every route.
+
+The `/src/routes` folder contains each route as a sub-folder. Those contain your route-specific models, views, intents, and sinks.
+
+Other optional folders for organization include a `/src/components` folder to store your view components. The `/src/static` folder can contain your static assets. The `/src/utils` can organize other utilities and helpers.
+
+## Model-View-Intent Basics
+
+For example, one can create a simple "cookie clicker" application where clicking a button increments a counter and tells how many times the button has been clicked.
+
+Although one can design this app non-routed, this example will show it routed to cover the entire Unicycle framework.
+
+### App-Level MVI
+
+Starting at the app level, create `/src/app/app.client.js`. This provides application-level configuration.
+
+#### App Configuration
+
+```JavaScript
+// app.client.js
+
+export default () => ({
+  drivers: {
+    // ... Additional drivers
+  },
+  defaults: {
+    // ... Default streams for each driver
+  },
+  state: {
+    // ... Initial app state
+  },
+});
+```
+
+The app-level configuration should export a function that returns an object which can contain drivers, defaults, and state.
+
+Drivers are key-value pairs of the sink name to the `makeDriver` functions provided by any driver packages you install (e.g. [@cycle/http](https://cycle.js.org/api/http.html)).
+
+Defaults is an object of key-value pairs of the sink name and the default stream you wish to be used if the route does not provide a sink.
+
+For instance, if every route does not provide an `http` sink, you can define the default as `http: xs.empty()`.
+
+This is necessary for every driver you use.
+
+Finally, state defines the initial app-level (or global) state.
+
+Since this application is simple, we can even omit creating this file entirely.
+
+#### App View
+
+The next file is the view. This file is named `/src/app/app.view.js`.
+
+```JavaScript
+// app.view.js
+
+import { h1, main, p } from "@cycle/dom";
+
+export default (dom, global) => main([
+  h1(["Cookie Clicker"]),
+  dom ?? p(["Page not found"]),
+]);
+```
+
+This view is rather simplistic. The app-level view should export a function that returns virtual DOM.
+
+It takes in two parameters, `dom` and `global`.
+
+The `dom` parameter is the route-level virtual DOM which can be "wrapped" by your app skeleton.
+
+The `global` parameter is the app-level state.
+
+Notice how we conditionally check if the `dom` is undefined, we supply a default which could be a page-not-found message.
+
+This pretty much sums it up for the app-level files to create. But you can create other files like intent, model, and sinks for any of the drivers you've installed.
+
+### Route-Level MVI
+
+Next, routes can be created, which are specific portions of your app that are accessed via its unique URL. Hence, why it's routed.
+
+For our example cookie clicker project, we just need one route.
+
+#### Example Route Definition
+
+Create a folder under `/src/routes` to make a route. By nature, each route name (or id) must be unique.
+
+For example, one can name this route `index`. So create a folder called `/src/routes/index`.
+
+The required file for a route is the route definition. This file will be called `index.route.js`.
+
+By convention, file names follow this pattern: `[route_name].[file_type].js`.
+
+```JavaScript
+// index.route.js
+
+export default () => ({
+  path: "/",
+  state: {
+    count: 0,
+  },
+});
+```
+
+This configuration allows you to specify two things. First, the path for the route can be specified either as a string, or an array of strings if the route has multiple paths.
+
+You can also specify route parameters by prefixing any part of the slug with `:parameter_name`. So, `parameter_name` will be automatically made available under `global.parameters` in the model, for instance.
+
+Second, the initial state can be defined for the route.
+
+For our cookie clicker, we're interested in how many times the button is clicked, so we'll store a `count` value.
+
+#### Intent Semantics
+
+Next, one can write the intent. We'll name this file `/src/routes/index/index.intent.js`.
+
+```JavaScript
+// index.intent.js
+
+export default (on, global$) => ({
+  increment: on.click({
+    intent: "increment-count",
+  }),
+});
+```
+
+An intent file should export a function that returns an object representing an intent definition.
+
+Intents can be described as a key-value pair of intent names to the intent listeners.
+
+We provide two parameters to this function, `on` and `global$`.
+
+The `on` parameter is an object already instantiated with the `sources` that come in from the drivers. This is a helper with easy, short-hand ways of writing intents.
+
+For our application, we're interested to listen to when the button is clicked. So we simply define it as `on.click({})`.
+
+We want to target a button with a data attribute of `data-intent="increment-count"`.
+
+Other event handlers are available as follows:
+
+```JavaScript
+on.click() // Targets click events.
+on.change() // Targets change events.
+on.input() // Targets input events.
+on.submit() // Targets submit events.
+on.focusin() // Targets focusin events.
+on.focusout() // Targets focusout events.
+on.scroll() // Targets scroll events.
+on.dblclick() // Targets dblclick events.
+on.pointerdown() // Targets pointerdown events.
+on.pointerup() // Targets pointerup events.
+on.pointermove() // Targets pointermove events.
+on.dragstart() // Targets dragstart events.
+on.drag() // Targets drag events.
+on.dragend() // Targets dragend events.
+on.drop() // Targets drop events.
+on.dragover() // Targets dragover events.
+on.keydown().key("Enter") // Targets keydown events. Under the key, we can either provide a string, or an array of strings to match keys.
+on.select() // Allows you to specify a target definition and returns the selection from the DOM driver.
+on.sources // Returns the sources object passed in from the drivers.
+```
+
+In terms of target definitions, there are standard semantics:
+
+```JavaScript
+{
+  intent: "some-intent" // Targets an element with data-intent="some-intent"
+}
+
+{
+  field: "some-field" // Targets an element with data-field="some-field"
+}
+
+{
+  id: "some-id" // Targets an element with data-id="some-id"
+}
+
+{
+  index: "0" // Targets an element with data-index="0"
+}
+
+{
+  object: "some-object" // Targets an element with data-object="some-object"
+}
+
+{
+  accept: "some-accept" // Targets an element with data-accept="some-accept"
+}
+```
+
+You can even provide strings as literal query strings.
+
+Targeting parents and children is possible too, by defining/nesting `parent` or `child` to other target definitions.
+
+In summary, for a complex example, this is what a target definition/intent helper translates to:
+
+```JavaScript
+
+on.click({
+  intent: "increment-count",
+  parent: "main",
+})
+
+// Is equivalent to...
+
+sources.DOM.select("main [data-intent='increment-count']").events("click").filter((event) => event.currentTarget.ariaDisabled !== "true")
+```
+
+Furthermore, when writing intents, either they can terminate in streams, or nested objects, or arrays of streams.
+
+For our application, defining the one intent is sufficient.
+
+#### Model Semantics
+
+Next, a model can be created to translate intents into state changes.
+
+We can create our model at `/src/routes/index/index.model.js`.
+
+```JavaScript
+// index.model.js
+
+export default (change) => ({
+  increment: ({state, action, global}) => {
+    const c = change();
+    const current_count = c.at("count").get(state);
+    c.at("count").set(current_count + 1);
+    return c;
+  },
+});
+```
+
+As you can see, our model for this application is trivial.
+
+The model structure mirrors the intent. So whenever any intent fires, the corresponding model reducer definition is executed.
+
+Models should export a function that returns an object containing its model definition. It accepts a parameter of `change`, which is a factory function for instantiating a change description to immutably modify state.
+
+For our corresponding model to intent, `increment`, we supply a function that takes in a destructured object of `state`, `action`, and `global`.
+
+The `state` parameter is the route's current state.
+
+The `action` parameter is the value returned by the intent stream.
+
+The `global` parameter is the app-level current state.
+
+We initialize our change description by setting a variable to `change()`. Our model reducer should return that value. Conventionally, we can call this `c`.
+
+And then we can apply any business logic and make changes to our state. We wish to do so immutably, so something like `state.count++` would go against the grain of our pattern and potentially introduce hard-to-debug bugs.
+
+So we immutably describe our changes and Unicycle takes care of applying them.
+
+Our change operator has three main functions: `get`, `set`, and `delete` (as well as `at`).
+
+First, we call the `at` function to specify a path to the state we wish to modify.
+
+It can either be a string that can be dot-separated to target nested values. Or it can be an array of strings. For instance, `c.at("nested.field")` is equal to `c.at(["nested", "field"])`, which targets `{nested: {field: "This Value"}}`.
+
+Then, we can use an operator to describe our change. The `get` operator takes in the object we wish to traverse (which is `state` in this case) for the value we want to know. This is just an accessor function, not a modification function.
+
+The `set` operator overwrites the value of the path to the one we supply. In this case, we're changing `count` to the new value.
+
+Finally, the `delete` operator removes the field from the state. It takes no parameters.
+
+A note on nested intents, if we have an intent such as:
+
+```JavaScript
+{
+  ...
+  edit: {
+    first_name: on.input({
+      field: "first_name",
+    }).map((event) => event.target.value),
+  },
+  ...
+}
+```
+
+We can represent the model as such:
+
+```JavaScript
+{
+  ...
+  edit: {
+    _: ({state, action, global}) => {...},
+    first_name: ({state, action, global}) => {...},
+  },
+  ...
+}
+```
+
+The `_` function is a special function that allows in nested intents, for the parent intent to fire any time a child intent fires. In this example, if the `edit.first_name` intent fires, the `_` fires for any nested `edit` intent.
+
+In summary, model definitions allow us to define changes to state in a structured way that mirrors the intent definition, and terminates in functions that return change descriptions.
+
+#### Route Features
+
+As an aside, there may be cases in real applications where the intent and model files grow where it makes sense to split them apart. This is what route features accomplish.
+
+So we could have expressed our cookie clicker as a feature instead.
+
+Features actually co-locate related intents and models. Features are placed under the route's folder.
+
+So we can make a `/src/routes/index/features` folder and put an `increment.js` file as our increment feature.
+
+```JavaScript
+// increment.js
+
+export default () => ({
+  intent: (on, global$) => ({
+    increment: on.click({
+      intent: "increment-count",
+    }),
+  }),
+  model: (change) => ({
+    increment: ({state, action, global}) => {
+      const c = change();
+      const current_count = c.at("count").get(state);
+      c.at("count").set(current_count + 1);
+      return c;
+    },
+  }),
+});
+```
+
+It exports a function that returns an object which contains the intent and model definitions. The semantics for intents and models are the same here, and it combines it with the route's intent and model structure.
+
+#### Route View
+
+Finally, we can render our view. The view translates state into the visual interface.
+
+We can create it at `/src/routes/index/index.view.js`.
+
+```JavaScript
+// index.view.js
+import { article, button } from "@cycle/dom";
+
+export default (state, global) => article([
+  button({
+    dataset: {
+      intent: "increment-count",
+    },
+  }, `This button was clicked ${state.count} time${state.count !== 1 ? "s" : ""}`),
+]);
+```
+
+As you can see, the view should export a function that takes in `state` and `global`, which are the route's state and app's state respectively, and returns virtual DOM.
+
+Our example is simple just returning a button showing how many times it was clicked.
+
+And remember, this is combined with our app-level view we created earlier.
+
+#### Route Sinks
+
+If we had other drivers, we can also create other sink files. These should export functions that return streams.
+
+So typically, it could take this structure:
+
+```JavaScript
+import xs from "xstream";
+
+export default ({on, action$, state$, global$} = {}) => xs.merge(
+  // ... Your streams
+);
+```
+
+The `on` function is the same from the intent.
+
+The `action$` stream is the stream of actions coming from your intents.
+
+The `state$` stream is the stream of your route's state.
+
+The `global$` stream is the stream of your app's state.
+
+## Wrapping it Up
+
+This is a lightweight model-view-intent framework that brings structure to Cycle.js applications and allows them to be written with consistent semantics.
+
+We hope this simple framework can serve you and your projects well by providing conventions and structure on top of what Vite and Cycle.js already offer.
+
+Made with ❤️ by Uplift Systems Inc.
+
+Copyright (c) 2025-2026 Uplift Systems Inc. All rights reserved.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "unicycle",
+  "version": "1.0.0",
+  "description": "Model-view-intent framework built on top of Vite and Cycle.js.",
+  "type": "module",
+  "author": "Uplift Systems Inc.",
+  "license": "MIT",
+  "main": "./src/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Uplift-Systems/unicycle.git"
+  },
+  "homepage": "https://github.com/Uplift-Systems/unicycle#readme",
+  "bugs": {
+    "url": "https://github.com/Uplift-Systems/unicycle/issues"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.js"
+    },
+    "./vite": {
+      "import": "./src/plugin.js"
+    }
+  },
+  "peerDependencies": {
+    "@cycle/dom": "^23.1.0",
+    "@cycle/history": "^9.0.0",
+    "@cycle/run": "^5.7.0",
+    "xstream": "^11.14.0"
+  }
+}

package/src/drivers/title.driver.js

@@ -0,0 +1,14 @@
+export default function makeTitleDriver() {
+  function titleDriver(title$) {
+    title$.addListener({
+      next: (title) => {
+        if (typeof title === "string") {
+          document.title = title;
+        }
+      },
+      error: () => {},
+      complete: () => {},
+    });
+  };
+  return titleDriver;
+};

package/src/index.js

@@ -0,0 +1,319 @@
+import { makeDOMDriver } from "@cycle/dom";
+import { makeHistoryDriver } from "@cycle/history";
+import makeTitleDriver from "./drivers/title.driver.js";
+import run from "@cycle/run";
+import xs from "./utils/xs.js";
+import sampleCombineImport from "xstream/extra/sampleCombine";
+const sampleCombine = sampleCombineImport?.default ?? sampleCombineImport;
+import { detailsFromFilePath } from "./utils/detailsFromFilePath.js";
+import { routeMatches } from "./utils/routeMatches.js";
+import { routeParameters } from "./utils/routeParameters.js";
+import { routeQuery } from "./utils/routeQuery.js";
+import { intentToActions } from "./mvi/intentToActions.js";
+import { applyReducers } from "./mvi/applyReducers.js";
+import { applyChanges } from "./mvi/applyChanges.js";
+import { mergeIntents } from "./mvi/mergeIntents.js";
+import { mergeModels } from "./mvi/mergeModels.js";
+import { on } from "./mvi/on.js";
+import { change } from "./mvi/change.js";
+
+const clientConfig = Object.values(
+  import.meta.glob("/src/app/app.client.js", {
+    eager: true,
+  })
+)?.[0]?.default ?? (() => ({}));
+
+if (typeof clientConfig !== "function") {
+  throw new TypeError("Default export for app client configuration at /src/app/app.client.js is expected to be a function.");
+}
+
+const config = clientConfig();
+
+const drivers = {
+  DOM: makeDOMDriver(document.body),
+  history: makeHistoryDriver(),
+  title: makeTitleDriver(),
+  ...(config?.drivers ?? {}),
+};
+
+const defaults = {
+  DOM: xs.of(undefined),
+  history: xs.empty(),
+  title: xs.of("Application"),
+  ...(config?.defaults ?? {}),
+};
+
+const app = {
+  sinks: {},
+};
+
+for (const [path, d] of Object.entries(import.meta.glob("/src/app/*.js", {eager: true}))) {
+
+  const { type } = detailsFromFilePath(path);
+  const data = d?.default;
+
+  if (typeof data !== "function") {
+    throw new TypeError(`Default export for ${type} for app at ${path} is expected to be a function.`);
+  }
+
+  if (["intent", "model", "view"].includes(type)) {
+    app[type] = data;
+  } else if (type !== "client") {
+    app.sinks[type] = data;
+  }
+
+}
+
+const features = {};
+
+for (const [path, feature] of Object.entries(import.meta.glob("/src/routes/*/features/*.js", {eager: true}))) {
+
+  const parts = path.split("/");
+  const filename = parts.at(-1);
+  const name = filename.split(".").at(-2);
+  const route = parts.at(-3);
+  const data = feature?.default;
+
+  if (typeof data !== "function") {
+    throw new TypeError(`Default export for feature ${name} in ${route} route at ${path} is expected to be a function.`);
+  }
+
+  if (!(route in features)) {
+    features[route] = {};
+  }
+
+  features[route][name] = data();
+
+}
+
+const routes = {};
+
+for (const [path, route] of Object.entries(import.meta.glob("/src/routes/*/*.js", {eager: true}))) {
+
+  const { id, type } = detailsFromFilePath(path);
+  const data = route?.default;
+
+  if (typeof data !== "function") {
+    throw new TypeError(`Default export for ${type} for ${id} route at ${path} is expected to be a function.`);
+  }
+
+  if (!(id in routes)) {
+    routes[id] = {
+      id,
+      sinks: {},
+    };
+  }
+
+  if (type === "route") {
+    routes[id].config = data();
+  } else if (["intent", "model", "view"].includes(type)) {
+    routes[id][type] = data;
+  } else {
+    routes[id].sinks[type] = data;
+  }
+
+}
+
+for (const route of Object.values(routes)) {
+
+  route.render = (sources, {appState$}) => {
+
+    const sinks = {};
+
+    const routeFeatures = features?.[route.id] ?? {};
+
+    const action$ = intentToActions(
+      Object.entries(routeFeatures).reduce((intents, [_, feature]) => mergeIntents(
+        intents,
+        (feature?.intent ?? (() => ({})))(on(sources), appState$)
+      ),
+      (route?.intent ?? (() => ({})))(on(sources), appState$))
+    );
+
+    const state$ = action$.compose(sampleCombine(appState$)).fold((state, [axn, global]) => {
+
+      const previous = route?.state ?? state;
+      const operations = applyReducers(
+        Object.entries(routeFeatures).reduce((models, [_, feature]) => mergeModels(
+          models,
+          (feature?.model ?? (() => ({})))(change)
+        ),
+        (route?.model ?? (() => ({})))(change)
+        ),
+        previous,
+        axn,
+        global,
+      );
+      const next = applyChanges(previous, operations);
+
+      route.state = next;
+
+      return next;
+
+    }, route?.state ?? route?.config?.state ?? {});
+
+    const vdom$ = xs.combine(state$, appState$).map(([state, global]) => {
+      return (route?.view ?? (() => undefined))(state, global);
+    });
+
+    sinks.DOM = vdom$;
+
+    for (const [sink, fn] of Object.entries(route.sinks)) {
+      const sink$ = fn({
+        on: on(sources),
+        action$,
+        state$,
+        global$: appState$,
+      });
+      sinks[sink] = sink$;
+    }
+
+    return sinks;
+
+  };
+
+}
+
+const getIDFromPathname = (pathname) => {
+
+  for (const [id, route] of Object.entries(routes)) {
+
+    const path = route?.config?.path ?? "";
+
+    if ((Array.isArray(path) ? path.some((p) => routeMatches(pathname, p)) : routeMatches(pathname, path))) {
+      return id;
+    }
+
+  }
+
+};
+
+const render = (sources, {appAction$, appState$} = {}) => sources.history.map((history) => {
+
+  const { pathname } = history;
+
+  const id = getIDFromPathname(pathname);
+
+  const route = routes[id] ?? {
+    render: () => ({}),
+  };
+
+  const sinks = {
+    ...defaults,
+    ...route.render({
+      ...sources,
+    }, {
+      appState$,
+    }),
+  };
+
+  const vdom$ = xs.combine(sinks.DOM, appState$).map(([dom, global]) => {
+    return (app?.view ?? ((dom) => dom ?? "Page not found."))(dom, global);
+  });
+
+  for (const [sink, fn] of Object.entries(app.sinks)) {
+    const sink$ = fn({
+      on: on(sources),
+      action$: appAction$,
+      state$: appState$,
+    });
+    sinks[sink] = xs.merge(
+      ...(sink in sinks ? [
+        sinks[sink],
+      ] : []),
+      sink$,
+    );
+  }
+
+  return {
+    ...sinks,
+    DOM: vdom$,
+  };
+
+});
+
+app.render = (() => {
+
+  const streams = {};
+
+  return (sources) => {
+
+    if (streams?.action$ === undefined) {
+      streams.action$ = intentToActions({
+        route: sources.history,
+        ...(app?.intent ?? (() => ({})))(on(sources)),
+      });
+    }
+
+    if (streams?.state$ === undefined) {
+      streams.state$ = streams.action$.fold((state, axn) => {
+
+        const operations = applyReducers(
+          {
+            route: ({action}) => {
+              const c = change();
+              const route_id = getIDFromPathname(action.pathname);
+              const path = route_id ? (Array.isArray(routes?.[route_id]?.config?.path) ? routes[route_id].config.path.find((p) => routeMatches(action.pathname, p)) : routes[route_id].config.path) : action.pathname;
+              c.at(["route_id"]).set(route_id ?? null);
+              c.at(["pathname"]).set(action.pathname);
+              c.at(["parameters"]).set(routeParameters(action.pathname, path));
+              c.at(["query"]).set(routeQuery(action.search));
+              return c;
+            },
+            ...(app?.model ?? (() => ({})))(change),
+          },
+          state,
+          axn,
+          state,
+        );
+        return applyChanges(state, operations);
+
+      }, {
+        route_id: null,
+        pathname: "/",
+        parameters: {},
+        query: {},
+        ...(config?.state ?? {}),
+      }).remember();
+    }
+
+    return {
+      appAction$: streams.action$,
+      appState$: streams.state$,
+    };
+
+  };
+
+})();
+
+const application = (sources) => {
+
+  const sinks = {};
+
+  const { appAction$, appState$ } = app.render(sources);
+
+  const route$ = render(sources, {appAction$, appState$});
+
+  for (const sink of Object.keys(defaults)) {
+
+    if (sink === "history") {
+      sinks[sink] = xs.merge(
+        route$.map((route) => route[sink]).flatten(),
+        sources.DOM.select("a").events("click").filter((event) => {
+          event.preventDefault();
+          return event.currentTarget.ariaDisabled !== "true" && event.currentTarget.href !== "";
+        }).map((event) => {
+          return event.currentTarget.href;
+        }),
+      );
+    } else {
+      sinks[sink] = route$.map((route) => route[sink]).flatten();
+    }
+
+  }
+
+  return sinks;
+
+};
+
+run(application, drivers);

package/src/mvi/applyChanges.js

@@ -0,0 +1,55 @@
+/**
+ * Returns a new object given an operation.
+ * @param {Object} object - Object for operations to be applied to.
+ * @param {Object} operation - An operation describing a single mutation.
+ * @returns {Object} The resulting object after patching the operation.
+ */
+const applyOperation = (object, operation = {}) => {
+
+  const { type, path, value } = operation;
+
+  if (Array.isArray(path) && path.length === 0) {
+
+    if (type === "set") {
+      return value;
+    }
+
+    return object;
+
+  }
+
+  const [key, ...rest] = path;
+
+  if (type === "delete" && rest.length === 0) {
+    if (!object) {
+      return object;
+    }
+
+    const {
+      [key]: _,
+      ...restObject
+    } = object;
+
+    return restObject;
+  }
+
+  return {
+    ...object,
+    [key]: applyOperation(object?.[key], {
+      type,
+      path: rest,
+      value,
+    }),
+  };
+
+};
+
+/**
+ * Applies a collection of operations to state to get new state.
+ * @param {Object} state - The state to be changed.
+ * @param {Array} operations - A collection of operations to be applied.
+ * @returns {Object} New state after applying the collection of operations.
+ */
+const applyChanges = (state, operations) => operations.reduce((s, operation) => applyOperation(s, operation), state);
+
+export { applyChanges };

package/src/mvi/applyReducers.js

@@ -0,0 +1,58 @@
+/**
+ * Recursively walks a model and calls reducer functions given an action and accumulates changes.
+ * @param {Object} model - A model containing reducers.
+ * @param {*} state - The current state.
+ * @param {*} action - The action being applied.
+ * @param {*} global - The global state.
+ * @returns {Array} An array of changes as supplied by the model and action.
+ */
+const applyReducers = (model, state, action, global) => {
+
+  const ops = [];
+
+  const walk = (node, axn) => {
+    
+    if (typeof node === "function") {
+      const result = node({
+        state,
+        action: axn,
+        global
+      });
+      if (Array.isArray(result?.operations)) {
+        ops.push(...result.operations);
+        return;
+      }
+    }
+    
+    if (!node || typeof node !== "object") {
+      return;
+    }
+
+    if (typeof node?._ === "function") {
+      const result = node._({
+        state,
+        action: axn,
+        global
+      });
+      if (Array.isArray(result?.operations)) {
+        ops.push(...result.operations);
+      }
+    }
+
+    for (const key in axn) {
+      if (key === "_" || !node[key]) {
+        continue;
+      }
+      
+      walk(node[key], axn[key]);
+    }
+
+  };
+
+  walk(model, action);
+
+  return ops;
+
+};
+
+export { applyReducers };

package/src/mvi/change.js

@@ -0,0 +1,56 @@
+/**
+ * A factory to describe state changes.
+ * @returns {object} An instance of change operations and operators.
+ */
+const change = () => {
+  const operations = [];
+
+  return {
+    /**
+     * Returns operators targeting a field path.
+     * @param {Array|string} path - A path to the desired field for modification.
+     * @returns {object} Operators.
+     */
+    at: (path) => {
+      const _path = Array.isArray(path) ? path : typeof path === "string" ? path.split(".") : undefined;
+      if (!Array.isArray(_path)) {
+        throw new TypeError("Invalid change path. Must be either an array of strings or a string.");
+      }
+      return {
+        set: (value) => operations.push({
+          type: "set",
+          path: _path,
+          value,
+        }),
+        delete: (value) => operations.push({
+          type: "delete",
+          path: _path,
+        }),
+        get: (state) => {
+
+          const walk = (node, path) => {
+
+            if (node === undefined) {
+              return node;
+            }
+
+            if (Array.isArray(path) && path.length === 0) {
+              return node;
+            }
+
+            const [key, ...rest] = path;
+
+            return walk(node?.[key], rest);
+
+          };
+
+          return walk(state, path);
+
+        },
+      };
+    },
+    operations,
+  };
+};
+
+export { change };

package/src/mvi/intentToActions.js

@@ -0,0 +1,44 @@
+import xs from "../utils/xs.js";
+import { isStream } from "./isStream.js";
+
+/**
+ * Transforms intentions into a single stream of actions to be reduced.
+ * @param {object} intentions Key-value pairs of intents and their streams, sub-intentions, or array of streams.
+ * @returns {Stream} Stream of actions.
+ */
+const intentToActions = (intentions = {}) => {
+
+  if (typeof intentions !== "object" || intentions === null) {
+    throw new TypeError("Intentions must be an object.");
+  }
+
+  return xs.merge(
+    ...Object.entries(intentions).map(([intent, affordance]) => {
+
+      if (isStream(affordance)) {
+
+        return affordance.map((value) => ({
+          [intent]: value,
+        }));
+
+      } else if (Array.isArray(affordance) && affordance.every(isStream)) {
+
+        return xs.merge(...affordance).map((value) => ({
+          [intent]: value,
+        }));
+
+      } else if (typeof affordance === "object" && affordance !== null) {
+
+        return intentToActions(affordance).map((value) => ({
+          [intent]: value,
+        }));
+
+      }
+
+      return xs.empty();
+
+    }),
+  );
+
+};
+export { intentToActions };

package/src/mvi/isStream.js

@@ -0,0 +1,7 @@
+/**
+ * Determines whether the input value is a stream.
+ * @param {*} value - The value to test whether it is a stream.
+ * @returns {Boolean} Whether the input value is a stream.
+ */
+const isStream = (value) => typeof value === "object" && typeof value?.addListener === "function" && typeof value?.removeListener === "function" && typeof value?.map === "function";
+export { isStream };

package/src/mvi/mergeIntents.js

@@ -0,0 +1,29 @@
+import { isStream } from "./isStream.js";
+
+/**
+ * Merges two intent definitions.
+ * @param {Object} a - Intent object.
+ * @param {Object} b - Intent object.
+ * @returns {Object} Merged intents.
+ */
+const mergeIntents = (a = {}, b = {}) => {
+
+  const result = {
+    ...a,
+  };
+
+  for (const [key, value] of Object.entries(b)) {
+
+    if (Array.isArray(value) || isStream(value)) {
+      result[key] = value;
+    } else {
+      result[key] = mergeIntents(a?.[key] ?? {}, value);
+    }
+
+  }
+
+  return result;
+
+};
+
+export { mergeIntents };

package/src/mvi/mergeModels.js

@@ -0,0 +1,27 @@
+/**
+ * Merges two model definitions.
+ * @param {Object} a - Model definition.
+ * @param {Object} b - Model definition.
+ * @returns {Object} - Merged model definition.
+ */
+const mergeModels = (a = {}, b = {}) => {
+
+  const result = {
+    ...a,
+  };
+
+  for (const [key, value] of Object.entries(b)) {
+
+    if (typeof value === "function") {
+      result[key] = value;
+    } else {
+      result[key] = mergeModels(a?.[key] ?? {}, value);
+    }
+
+  }
+
+  return result;
+
+};
+
+export { mergeModels };

package/src/mvi/on.js

@@ -0,0 +1,99 @@
+const TARGETS = ["intent", "field", "id", "index", "object", "accept"];
+
+/**
+ * Recursively converts DOM selection query (target) objects into a query selector string.
+ * @param {string|object} target Either a literal string selector, or an object specifying an intent, field, id, parent, or child.
+ * @returns {string} Returns the literal HTML query selector.
+ */
+const query = (target) => {
+  
+  const result = [];
+
+  if (typeof target === "string") {
+    return target;
+  } else if (typeof target === "object") {
+
+    for (const type of TARGETS) {
+
+      if (type in target) {
+        const value = target[type];
+        result.push(`[data-${type}="${value}"]`);
+      }
+
+    }
+
+    if ("inert" in target) {
+      if (target["inert"] === true) {
+        result.push("[inert]");
+      } else if (target["inert"] === false) {
+        result.push(":not([inert])");
+      }
+    }
+
+    if ("child" in target) {
+      return [result.join(""), query(target.child)].join(" ");
+    } else if ("parent" in target) {
+      return [query(target.parent), result.join("")].join(" ");
+    }
+
+  }
+
+  return result.join("");
+
+};
+
+const select = (sources, target) => sources.DOM.select(query(target));
+
+/**
+ * Determines whether an event's target is enabled aria-wise.
+ * @param {Event} event An event object.
+ * @returns {Boolean} Whether the target is enabled or not via aria-disabled.
+ */
+const isEnabled = (event) => event.currentTarget.ariaDisabled !== "true";
+
+/**
+ * Prevents default on event.
+ * @param {Event} event An event object.
+ * @returns {Event} The event.
+ */
+const preventDefault = (event) => {
+  event.preventDefault();
+  return event;
+};
+
+/**
+ * Determines whether one is typing in the active element during a particular event.
+ * @param {Event} event An event object.
+ * @returns {Boolean} Whether one is typing during the event.
+ */
+const isTyping = (event) => {
+  const element = document.activeElement;
+
+  if (!element) {
+    return false;
+  }
+
+  return (element.tagName === "TEXTAREA" || element.tagName === "INPUT" || element.isContentEditable);
+};
+
+/**
+ * Determines whether one is not typing in the active element during a particular event.
+ * @param {Event} event An event object.
+ * @returns {Boolean} Whether one is not typing during the event.
+ */
+const isNotTyping = (event) => !isTyping(event);
+
+const on = (sources) => ({
+  click: (target) => select(sources, target).events("click").filter(isEnabled),
+  ...["change", "input", "submit", "focusin", "focusout", "scroll", "dblclick", "pointerdown", "pointerup", "pointermove", "dragstart", "drag", "dragend", "drop", "dragover"].reduce((events, event) => ({
+    ...events,
+    [event]: (target) => select(sources, target).events(event),
+  }), {}),
+  keydown: (target) => ({
+    key: (key) => select(sources, target).events("keydown").filter((event) => Array.isArray(key) ? key.includes(event.key) : key === event.key),
+  }),
+  select: (target) => select(sources, target),
+  sources,
+});
+
+export { on };

package/src/plugin.js

@@ -0,0 +1,25 @@
+function UnicyclePlugin() {
+  return {
+    name: "unicycle",
+    transformIndexHtml: {
+      order: "pre",
+      handler(html) {
+        return {
+          html,
+          tags: [
+            {
+              tag: "script",
+              attrs: {
+                type: "module",
+              },
+              injectTo: "head",
+              children: `import "unicycle";`,
+            },
+          ],
+        };
+      }
+    },
+  };
+};
+
+export default UnicyclePlugin;

package/src/utils/detailsFromFilePath.js

@@ -0,0 +1,30 @@
+/**
+ * Converts a file path to its id and type.
+ * @param {string} path - A file path.
+ * @returns {object} An object containing an id and type.
+ * @example
+ * const { id, type } = detailsFromFilePath("/src/routes/dashboard/dashboard.view.js");
+ * console.log(id); // Outputs "dashboard".
+ * console.log(type); // Outputs "view".
+ */
+const detailsFromFilePath = (path) => {
+
+  if (typeof path === "string") {
+
+    const parts = path.split("/");
+    const id = parts.at(-2);
+    const filename = parts.at(-1);
+    const type = filename.split(".").at(-2);
+
+    return {
+      id,
+      type,
+    }
+
+  }
+
+  return {};
+
+};
+
+export { detailsFromFilePath };

package/src/utils/routeMatches.js

@@ -0,0 +1,33 @@
+/**
+ * Determines whether the pathname matches the supplied path pattern.
+ * @param {string} pathname - The literal history path.
+ * @param {string} path - The path pattern to match.
+ * @returns {Boolean} Whether the pathname matches the supplied path.
+ */
+const routeMatches = (pathname, path) => {
+
+  const names = pathname.split("/").filter((part, i, parts) => !((i === 0 || i === parts.length - 1) && part === ""));
+
+  const paths = path.split("/").filter((part, i, parts) => !((i === 0 || i === parts.length - 1) && part === ""));
+
+  if (names.length !== paths.length) {
+    return false;
+  }
+
+  for (const [index, slug] of paths.entries()) {
+
+    if (names[index] === undefined) {
+      return false;
+    }
+
+    if (names[index] !== slug && !slug.startsWith(":")) {
+      return false;
+    }
+
+  }
+
+  return true;
+
+};
+
+export { routeMatches };

package/src/utils/routeParameters.js

@@ -0,0 +1,27 @@
+/**
+ * Gets route parameters from pathname and path pattern.
+ * @param {string} pathname - The history pathname.
+ * @param {string} path - A path pattern.
+ * @returns {object} An object with route parameters from path pattern.
+ */
+const routeParameters = (pathname, path) => {
+
+  const result = {};
+
+  const names = pathname.split("/").filter((part, i, parts) => !((i === 0 || i === parts.length - 1) && part === ""));
+
+  const paths = path.split("/").filter((part, i, parts) => !((i === 0 || i === parts.length - 1) && part === ""));
+
+  for (const [index, slug] of paths.entries()) {
+
+    if (names[index] !== undefined && slug.startsWith(":")) {
+      result[slug.slice(1)] = names[index];
+    }
+
+  }
+
+  return result;
+
+};
+
+export { routeParameters };

package/src/utils/routeQuery.js

@@ -0,0 +1,20 @@
+/**
+ * Converts history query string to key-value object.
+ * @param {string} query - The history query string.
+ * @returns {object} An object containing route query.
+ */
+const routeQuery = (query) => {
+  
+  const result = {};
+
+  const params = new URLSearchParams(query);
+
+  for (const [key, value] of params) {
+    result[key] = value;
+  }
+
+  return result;
+
+};
+
+export { routeQuery };

package/src/utils/xs.js

@@ -0,0 +1,4 @@
+import xstream from "xstream";
+const xs = xstream?.default ?? xstream;
+
+export default xs;