> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryoku.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugins

> Shell plugins are small desktop widgets and frame popouts; you write the logic and one view, and Ryoku owns their look, motion, sizing, and placement.

A **plugin** is a small **widget** you place on your desktop: a stock ticker on
the wallpaper, a photo beside the clock, a panel that melts out of the screen
edge on hover. The author writes the *logic and one view*; Ryoku owns *where it
lives, how it looks, how it moves, and how it sizes*. That split is the whole
point, a plugin always looks and behaves like a native part of the shell,
because the shell draws the surface around it.

<Note>
  Plugins are **widgets**, not applications. To install real software (game
  launchers, dev stacks, security tools), use [Extras](/docs/extras) bundles, a
  separate system.
</Note>

## The two hosts

When you enable a plugin you pick **one** host for it. The same widget can run in
either; Ryoku just renders it differently.

<Tabs>
  <Tab title="Desktop widget">
    A tile on the wallpaper, next to the clock and weather, with the same
    machinery they have:

    * **Left-drag** to move it (snaps to a grid).
    * **Right-click** for its menu: **Lock** to freeze it in place, **Hide** to
      turn it off.
    * **Drag the bottom-right corner** to resize, live, from 50% to 250%.
    * It rides on a card (rounded, translucent, soft shadow) that matches the
      clock and weather.

    You arrange desktop widgets directly on the wallpaper, not from Settings.
  </Tab>

  <Tab title="Frame popout">
    A panel that melts out of the [frame](/docs/tour) border on hover, fused into
    the same blob as the volume mixer and power menu.

    * You pick the **edge** it grows from (top, right, bottom, or left) and which
      **end** of that edge it aligns to (**start** or **end**; the centre of each
      edge is reserved for the shell's own island and mixer).
    * Ryoku handles the hover trigger, the open and close animation, and the fuse
      into the frame. The popout grows to fit the widget, you never set its size.
    * Toggle it open from a key with `ryoku-shell plugin <id>` (bind it in
      [Customize](/docs/customize)).
  </Tab>
</Tabs>

<Note>
  Island, top-bar glyph, and window hosts are planned but not built yet. Today a
  plugin declares `desktopWidget`, `framePopout`, or both.
</Note>

## Install, enable, place

<Steps>
  <Step title="Install from the Store">
    Press `Mod + ,` for Ryoku Settings and open **Store** (under **Add-ons**). It
    opens on a grid of plugin cards with live previews; open one and choose
    **Install**. The source downloads to `~/.local/share/ryoku/plugins/<id>/`.
  </Step>

  <Step title="Enable it">
    Switch to **Installed** (also under **Add-ons**) and toggle the plugin
    **Enabled**.
  </Step>

  <Step title="Pick a host and place it">
    In the same panel choose the host. For a **frame popout**, set the edge and
    alignment there. A **desktop widget** appears on the wallpaper, where you
    drag, corner-resize, lock, or hide it directly.
  </Step>
</Steps>

Placement and settings persist to `~/.config/ryoku/plugins.json`. The shell
watches that file and retunes every surface **live**, no reload, no restart.
Removing a plugin (from **Installed**) deletes its files but keeps your
placement, so reinstalling drops it back where you had it.

## Example plugins

Ryoku ships two official plugins in the catalogue, both desktop widgets:

<CardGroup cols={2}>
  <Card title="Market" icon="chart-line">
    Track any Yahoo Finance symbol, a crypto pair (`BTC-USD`), a stock (`AAPL`),
    or an index (`^GSPC`), with live price, change, and history in one of four
    faces: dossier, line, area, or minimal.
  </Card>

  <Card title="Photo Frame" icon="image">
    Pin any photo to your wallpaper in a chosen style (rounded, square, polaroid,
    framed, or film) with a tunable drop shadow and colour filters. Ships with a
    sample photo so it looks right the moment you enable it.
  </Card>
</CardGroup>

Each plugin's own options (Market's symbol and face, Photo Frame's style and
filter) live in its settings, edited from **Installed** or the desktop widget's
right-click menu.

## From a terminal

The Hub is the normal path, but the same actions have commands. Ids are the ones
in the [`ryoku-extras`](https://github.com/neur0map/ryoku-extras) plugin
catalogue (`market`, `photo-frame`).

```bash theme={"dark"}
# Install a plugin from the catalogue (fetches into ~/.local/share/ryoku/plugins).
ryoku-hub extras plugin market

# Remove a plugin's files (your placement in plugins.json is kept).
ryoku-hub extras pluginremove market

# Enable it and place it as a desktop widget (writes plugins.json; retunes live).
ryoku-plugins-place market enabled true
ryoku-plugins-place market host desktopWidget
ryoku-plugins-place market desktopWidget 120 80      # x y [scale] [locked]

# For a frame-popout plugin: set the edge and alignment, then toggle it open.
ryoku-plugins-place <id> framePopout top end         # edge align [hoverW] [hoverH]
ryoku-shell plugin <id>
```

## Write your own

Yes, Ryoku has a plugin SDK. A plugin is a folder with a `manifest.json`, a
non-visual `service/Main.qml` (your logic and state), and one `content/Widget.qml`
(your view), installed to `~/.local/share/ryoku/plugins/<id>/`. Your view imports
the `Ryoku.PluginKit` deck kit, so it picks up the shell's colours, type, and
motion automatically.

<Warning>
  **The golden rule:** never set your own position, never draw your own window
  chrome, never assume your size. You report your content's natural
  `implicitWidth` and `implicitHeight`; Ryoku sizes the card or grows the popout
  around it. Break this rule and your plugin looks bolted-on instead of native.
</Warning>

The full authoring guide, the manifest schema, the three densities (`glyph`,
`compact`, `full`), and the settings schema live in the repo:

* [`docs/plugins.md`](https://github.com/neur0map/ryoku-arch/blob/main/docs/plugins.md) in `ryoku-arch`, the canonical guide.
* [`plugins/AUTHORING.md`](https://github.com/neur0map/ryoku-extras/blob/main/plugins/AUTHORING.md) in `ryoku-extras`, alongside a `template/` plugin to copy.

## See also

<CardGroup cols={2}>
  <Card title="Extras" icon="cubes" href="/docs/extras">
    Software bundles, the other half of how Ryoku grows beyond its core.
  </Card>

  <Card title="Ryoku Settings" icon="sliders" href="/docs/settings">
    The Store and Installed panels, and everything else the Hub tunes.
  </Card>
</CardGroup>