Motrix Download Manager

Motrix is designed as a decoupled system where the download core is independent of the UI. Communication between the core and external clients (like browser extensions or CLI tools) happens via MDXP (Motrix Download eXchange Protocol), an open protocol based on JSON-RPC 2.0.

Key Ecosystem Components:

• @motrix/mdxp: npm package defining the JSON-RPC 2.0 wire schemas and Zod types for MDXP.
• @motrix/cli: The official command-line client.
• Browser Extensions: Chrome and Firefox extensions (Manifest V3) that hand off downloads to the desktop app via native messaging.
• Plugin SDK: A suite of four npm packages (@motrix/plugin-manifest-schema, @motrix/plugin-api, @motrix/plugin-cli, and create-motrix-plugin) for building sandboxed extensions.
• Plugin Registry: A public JSON feed at dl.motrix.app/registry/plugins.json used by the in-app marketplace.

Motrix Turbo uses a four-layer architecture designed to decouple the UI from the download engine. This structure allows the core to be reused across both Electron desktop apps and Node.js headless servers.

The Layers:

1. Renderer: The React-based user interface.
2. Core: The application logic (independent of the download engine). It manages tasks, settings, plugins, and the bridge. It communicates with the renderer via IPC (window.motrix).
3. Engine Adapter: An abstraction layer within the Core that interfaces with the download engine.
4. Aria2: The actual download engine (a maintained fork of aria2).

Key Design Principles:

• Shared Core: The same Core logic is used in both Desktop and Headless environments.
• Capability-based Security: Plugins must request specific host capabilities (like notifications or secret storage) which are implemented differently depending on the environment (Desktop vs. Headless) but exposed via a consistent API.

Desktop Kit is a desktop interaction component library for Motrix 2.0 that provides virtual scrolling, marquee selection (box selection), and multi-selection capabilities for any data type.

Architecture

The library is built on a decoupled three-layer architecture connected by a single "glue" hook:

1. SelectionEngine: A pure logic Zustand store with zero DOM/React dependencies. It manages the selection state.
2. VirtualList: A wrapper around @tanstack/react-virtual that handles rendering but remains unaware of selection logic.
3. MarqueeOverlay: A UI overlay for box selection that only outputs the range of indices selected.
4. useSelectableList (Glue Hook): The primary integration point that connects the three modules.

Design Principles

• Three-layer Decoupling: SelectionEngine is logic-only, VirtualList is rendering-only, and MarqueeOverlay is index-output only.
• Generic Adaptation: Uses <T> and a getId function to support any data structure.
• Mathematical Indexing: Uses Math.floor(offset / rowHeight) for box selection instead of DOM queries, ensuring compatibility with virtualization.
• Fixed Row Height: Requires a fixed row height to ensure $O(1)$ index calculation.
• $O(1)$ ID Lookup: Maintains an internal Map<id, index> to avoid linear scans during selection/toggling.

Motrix's Flatpak browser integration uses a two-layer architecture to maintain security boundaries:

1. motrix-flatpak-native-host (Outside Sandbox): Runs as the browser's Native Messaging host on the host machine. It manages the browser manifest, launches the Motrix Flatpak application, and forwards paired requests with frame boundaries.
2. motrix-native-host-broker (Inside Sandbox): Runs within the Motrix Flatpak sandbox. It handles parsing the Bridge endpoint, performing localhost health checks, and obtaining a one-time nonce.

Important Security Notes:

• The companion only registers the official built-in Motrix extension IDs. Custom extension IDs added within the Flatpak app are not synchronized to the host companion and will not be registered.
• If your browser is also running in a sandbox, you may need a Native Messaging proxy provided by your browser's distribution; installing this companion alone may not be sufficient to bridge the connection.

To implement a selectable virtual list, use the useSelectableList hook to coordinate the VirtualList and MarqueeOverlay components. You must provide items, a getId function, and rowHeight.

import { useSelectableList } from './hooks/use-selectable-list'
import { VirtualList } from './virtual-list/virtual-list'
import { MarqueeOverlay } from './marquee-selection/marquee-overlay'

interface Task {
  id: string
  name: string
}

function TaskList({ tasks }: { tasks: Task[] }) {
  const {
    listRef,
    listProps,
    marqueeProps,
    getRowProps,
    headerCheckbox,
    onKeyDown,
  } = useSelectableList({
    items: tasks,
    getId: (t) => t.id,
    rowHeight: 40,
  })

  return (
    <div onKeyDown={onKeyDown} tabIndex={0} style={{ position: 'relative' }}>
      <VirtualList
        ref={listRef}
        {...listProps}
        style={{ height: 500 }}
        renderHeader={() => (
          <div>
            <input
              type="checkbox"
              checked={headerCheckbox.checked}
              ref={(el) => {
                if (el) el.indeterminate = headerCheckbox.indeterminate
              }}
              onChange={headerCheckbox.onChange}
            />
            Name
          </div>
        )}
        renderRow={({ item, index }) => {
          const rp = getRowProps(index)
          return (
            <div
              style={{ background: rp.selected ? '#dbeafe' : 'transparent' }}
              onClick={rp.onClick}
            >
              <input
                type="checkbox"
                checked={rp.selected}
                onChange={() => {}}
                onClick={(e) => {
                  e.stopPropagation()
                  rp.onCheckboxChange()
                }}
              />
              {item.name}
            </div>
          )
        }}
      />
      <MarqueeOverlay {...marqueeProps} />
    </div>
  )
}