nuspace 0.5.2__tar.gz → 0.5.4__tar.gz

{nuspace-0.5.2 → nuspace-0.5.4}/CHANGELOG.md

@@ -2,14 +2,38 @@
 
 ## Packages shipped from this repo
 
-- **nuspace** (the runtime, the `nuspace` command) — 0.5.2
-- **nuspace-ui** (the compiled web bundle) — 0.5.2
-- **nuverse** (the Planes and snippets a space ships with) — 0.3.1
+- **nuspace** (the runtime, the `nuspace` command) — 0.5.3
+- **nuspace-ui** (the compiled web bundle) — 0.5.3
 
 Below is the changelog for **nuspace** - the full commit stream. Newest first.
 The `nuspace-ui` wheel is the same source tree's vite output and is not tracked
 separately here.
 
+## Unreleased
+
+## 0.5.4 — 2026-10-17
+
+- Point the demos extra at nudemos, the renamed home of the demo spaces
+- Add light and dark hero demo GIFs to the README
+- Trim the README header spacing above the navbar
+- Add the square logo to the README header
+
+## 0.5.3 — 2026-10-14
+
+- Release nuspace 0.5.3, built on nu 0.6.3 and UI kit 0.3.3
+- Search popup folds snippets into groups, ticks a group or everything at once
+- One run command opens a space in a browser, or headless with nothing drawn
+- Try a Nu demo in a throwaway space with one command
+- Make a directory a space without opening it to run
+- Doctor reports versions, missing pieces, extras and installed extensions
+- Empty cell pinned atop the / menu, starting from a program that runs
+- A dismissed cell menu leaves its cell selected, controls shown while open
+- Extensions get their own home; commands map one to one onto host presets
+- nuspace stands alone: no nuverse dependency, extensions come only from install
+- Park the agent and its Claude Code chats in the archive for now
+- Sidebar and panes resize and fold on the kit's split panels
+- nuverse Config sections open again, paired with their body by id
+
 ## 0.5.2 — 2026-10-12
 
 - Release nuspace 0.5.2, built on nu 0.6.2 and UI kit 0.3.2

nuspace-0.5.4/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: nuspace
+Version: 0.5.4
+Summary: Nu runtime built on Nu. A self-hosted programmable space that runs Nu programs as a tree of planes and cells.
+Project-URL: Repository, https://github.com/nustackdev/nuspace
+Author-email: Gor Arakelyan <gorarkln@gmail.com>
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE.md
+Keywords: nu,nuspace,nustack,python,runtime,self-hosted,ui
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: nucore>=0.6.3
+Requires-Dist: nuspace-ui>=0.5.3
+Requires-Dist: nustd[kv,mp-pool,proxy,ui,valkey]>=0.6.3
+Requires-Dist: rich-click>=1.6
+Requires-Dist: rich>=10.7
+Requires-Dist: typing-extensions>=4.7.0
+Requires-Dist: virtuals-py[redis]>=0.1.10
+Provides-Extra: all
+Requires-Dist: nustd[all]>=0.6.3; extra == 'all'
+Provides-Extra: demos
+Requires-Dist: nudemos; extra == 'demos'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img width="128" alt="nuspace" src="https://nustack.dev/brand/logo-square-512@2x.png" />
+  <h3>
+    nuspace - your computational space
+  </h3>
+  For everything you work with: notes, data, tools, agents. Open-source, self-hosted, your data stays local.
+</div>
+
+<br/>
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nustackdev/nuspace/main/.github/media/hero-dark.gif">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/nustackdev/nuspace/main/.github/media/hero-light.gif">
+    <img alt="nuspace demo" src="https://raw.githubusercontent.com/nustackdev/nuspace/main/.github/media/hero-light.gif" />
+  </picture>
+</p>
+
+<br/>
+
+<div align="center">
+
+  [![Discord](https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/tCa8YE7XVr)
+  [![Twitter Follow](https://img.shields.io/twitter/follow/nustackdev?style=social)](https://twitter.com/nustackdev)
+
+  [![Platform Support](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-blue)]()
+  [![PyPI - Python Version](https://img.shields.io/badge/python-%3E%3D%203.10-blue)](https://pypi.org/project/nuspace/)
+  [![PyPI Package](https://img.shields.io/pypi/v/nuspace?color=yellow)](https://pypi.org/project/nuspace/)
+  [![License](https://img.shields.io/badge/License-AGPL%20v3-orange.svg)](https://www.gnu.org/licenses/agpl-3.0)
+  [![PyPI Downloads](https://img.shields.io/pypi/dw/nuspace?color=green)](https://pypi.org/project/nuspace/)
+
+</div>
+
+---
+
+<h3 align="center">
+  <a href="#ℹ️-about"><b>About</b></a> &bull;
+  <a href="#quickstart"><b>Quickstart</b></a> &bull;
+  <a href="#community"><b>Community</b></a>
+</h3>
+
+---
+
+# ℹ️ About
+
+Build your computational space for everything you work with: notes, data, tools, agents.
+
+Elsewhere, a note is a dead document, data is scattered, tools are siloed and an agent's work is lost in chat. In nuspace, they're all connected cells: living programs that hold data, logic and look in one form.
+
+- **Cell**: the one building block. A note, a table, a chart, a job, an agent at work.
+- **Living program**: every cell runs. It keeps its state, reacts to the rest of the space and draws itself on screen.
+- **Connected**: change one cell and everything that depends on it follows, live, in every open tab.
+
+> **Program anything.** The data, the logic, the look, even the space itself. You and your agents shape it together, on your machine.
+
+> Early. Things move fast and the store format is not frozen yet.
+
+## What it can do
+
+Every cell gets all of it, nothing to wire up.
+
+- **Any data.** A note, a table, a song, a billion-entry log, a genome.
+- **Any logic.** Summarize your inbox, dim the lights at sunset, render a video.
+- **Any UI.** A cell draws itself. Text, tables, charts, forms.
+- **It's live.** Change one cell and everything that depends on it follows live. UI too.
+- **Work scales.** The same cell runs in a worker, across processes or on a cluster.
+- **Data scales.** A counter or a billion rows, same cell. Storage shards underneath.
+- **It's made of itself.** The space has the same shape as its cells, so you and your agents can program it too.
+
+
+## Quickstart
+
+### Install
+
+Python 3.10 or newer.
+
+```bash
+pip install nuspace
+```
+
+### Run
+
+```bash
+nuspace run my.nuspace
+```
+
+A browser opens on http://127.0.0.1:8080 and your space is live. Press `/` on a plane to add a cell. `--headless` runs it with nothing drawn.
+
+### Try a demo
+
+A throwaway space with a full app in it.
+
+```bash
+pip install "nuspace[demos]"
+nuspace demo movies
+```
+
+`nuspace demo` lists them all.
+
+### Next
+
+- `nuspace doctor` checks the install: versions, extras, extensions.
+- Planes and snippets are extensions, found on install through the `nuspace.extensions` entry point. Bring your own and they live in the space like everything else.
+- Your space is a directory on your machine. All state lives in that one folder.
+
+## Community
+
+### Badge
+
+Building on nuspace? Add the badge to your README:
+
+[![nuspace](https://img.shields.io/badge/built%20with-nuspace-%237A4CE0)](https://github.com/nustackdev/nuspace)
+
+```
+[![nuspace](https://img.shields.io/badge/built%20with-nuspace-%237A4CE0)](https://github.com/nustackdev/nuspace)
+```
+
+### Questions
+
+1. [Visit the website](https://nustack.dev)
+2. [Open a feature request or report a bug](https://github.com/nustackdev/nuspace/issues)
+3. [Join the Discord](https://discord.gg/tCa8YE7XVr)
+
+## License
+
+GNU Affero General Public License v3.0. See [LICENSE.md](LICENSE.md).

nuspace-0.5.4/README.md

@@ -0,0 +1,126 @@
+<div align="center">
+  <img width="128" alt="nuspace" src="https://nustack.dev/brand/logo-square-512@2x.png" />
+  <h3>
+    nuspace - your computational space
+  </h3>
+  For everything you work with: notes, data, tools, agents. Open-source, self-hosted, your data stays local.
+</div>
+
+<br/>
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nustackdev/nuspace/main/.github/media/hero-dark.gif">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/nustackdev/nuspace/main/.github/media/hero-light.gif">
+    <img alt="nuspace demo" src="https://raw.githubusercontent.com/nustackdev/nuspace/main/.github/media/hero-light.gif" />
+  </picture>
+</p>
+
+<br/>
+
+<div align="center">
+
+  [![Discord](https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/tCa8YE7XVr)
+  [![Twitter Follow](https://img.shields.io/twitter/follow/nustackdev?style=social)](https://twitter.com/nustackdev)
+
+  [![Platform Support](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-blue)]()
+  [![PyPI - Python Version](https://img.shields.io/badge/python-%3E%3D%203.10-blue)](https://pypi.org/project/nuspace/)
+  [![PyPI Package](https://img.shields.io/pypi/v/nuspace?color=yellow)](https://pypi.org/project/nuspace/)
+  [![License](https://img.shields.io/badge/License-AGPL%20v3-orange.svg)](https://www.gnu.org/licenses/agpl-3.0)
+  [![PyPI Downloads](https://img.shields.io/pypi/dw/nuspace?color=green)](https://pypi.org/project/nuspace/)
+
+</div>
+
+---
+
+<h3 align="center">
+  <a href="#ℹ️-about"><b>About</b></a> &bull;
+  <a href="#quickstart"><b>Quickstart</b></a> &bull;
+  <a href="#community"><b>Community</b></a>
+</h3>
+
+---
+
+# ℹ️ About
+
+Build your computational space for everything you work with: notes, data, tools, agents.
+
+Elsewhere, a note is a dead document, data is scattered, tools are siloed and an agent's work is lost in chat. In nuspace, they're all connected cells: living programs that hold data, logic and look in one form.
+
+- **Cell**: the one building block. A note, a table, a chart, a job, an agent at work.
+- **Living program**: every cell runs. It keeps its state, reacts to the rest of the space and draws itself on screen.
+- **Connected**: change one cell and everything that depends on it follows, live, in every open tab.
+
+> **Program anything.** The data, the logic, the look, even the space itself. You and your agents shape it together, on your machine.
+
+> Early. Things move fast and the store format is not frozen yet.
+
+## What it can do
+
+Every cell gets all of it, nothing to wire up.
+
+- **Any data.** A note, a table, a song, a billion-entry log, a genome.
+- **Any logic.** Summarize your inbox, dim the lights at sunset, render a video.
+- **Any UI.** A cell draws itself. Text, tables, charts, forms.
+- **It's live.** Change one cell and everything that depends on it follows live. UI too.
+- **Work scales.** The same cell runs in a worker, across processes or on a cluster.
+- **Data scales.** A counter or a billion rows, same cell. Storage shards underneath.
+- **It's made of itself.** The space has the same shape as its cells, so you and your agents can program it too.
+
+
+## Quickstart
+
+### Install
+
+Python 3.10 or newer.
+
+```bash
+pip install nuspace
+```
+
+### Run
+
+```bash
+nuspace run my.nuspace
+```
+
+A browser opens on http://127.0.0.1:8080 and your space is live. Press `/` on a plane to add a cell. `--headless` runs it with nothing drawn.
+
+### Try a demo
+
+A throwaway space with a full app in it.
+
+```bash
+pip install "nuspace[demos]"
+nuspace demo movies
+```
+
+`nuspace demo` lists them all.
+
+### Next
+
+- `nuspace doctor` checks the install: versions, extras, extensions.
+- Planes and snippets are extensions, found on install through the `nuspace.extensions` entry point. Bring your own and they live in the space like everything else.
+- Your space is a directory on your machine. All state lives in that one folder.
+
+## Community
+
+### Badge
+
+Building on nuspace? Add the badge to your README:
+
+[![nuspace](https://img.shields.io/badge/built%20with-nuspace-%237A4CE0)](https://github.com/nustackdev/nuspace)
+
+```
+[![nuspace](https://img.shields.io/badge/built%20with-nuspace-%237A4CE0)](https://github.com/nustackdev/nuspace)
+```
+
+### Questions
+
+1. [Visit the website](https://nustack.dev)
+2. [Open a feature request or report a bug](https://github.com/nustackdev/nuspace/issues)
+3. [Join the Discord](https://discord.gg/tCa8YE7XVr)
+
+## License
+
+GNU Affero General Public License v3.0. See [LICENSE.md](LICENSE.md).

{nuspace-0.5.2 → nuspace-0.5.4}/examples/space.py

@@ -1,7 +1,7 @@
-"""A space in the browser, with nuverse and nothing else.
+"""A space in the browser, with whatever extensions are installed.
 
-Every Plane and snippet comes from nuverse, found through its entry point. The
-space is the directory ``examples/example.nuspace``, kept between runs.
+Every Plane and snippet comes from an extension, found through its entry point.
+The space is the directory ``examples/example.nuspace``, kept between runs.
 
 Run it::
 

{nuspace-0.5.2 → nuspace-0.5.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nuspace"
-version = "0.5.2"
+version = "0.5.4"
 description = "Nu runtime built on Nu. A self-hosted programmable space that runs Nu programs as a tree of planes and cells."
 readme = "README.md"
 license = "AGPL-3.0-or-later"
@@ -14,19 +14,14 @@ dependencies = [
     # The fabrics a space runs on, nothing more: kv for the store, valkey for
     # its change notifications, ui for the browser, mp_pool for the workers,
     # proxy (invisibles) for the worker's session.
-    "nucore>=0.6.2",
-    "nustd[kv,ui,valkey,mp_pool,proxy]>=0.6.2",
+    "nucore>=0.6.3",
+    "nustd[kv,ui,valkey,mp_pool,proxy]>=0.6.3",
     # The store's change notifications run over virtuals' redis backend.
     "virtuals-py[redis]>=0.1.10",
     # The compiled web bundle. A separate distribution only because PyPI caps
     # project size and a SPA rebuilt on every UI tweak would eat the quota --
     # not optional. `pip install nuspace` gives you the browser.
-    "nuspace-ui>=0.5.2",
-    # The extensions a space offers out of the box: Planes, snippets. Always
-    # pulled, split into extras when its deps grow. nuspace never imports it:
-    # it is found through the `nuspace.extensions` entry point, like any
-    # third party.
-    "nuverse>=0.3.1",
+    "nuspace-ui>=0.5.3",
     "typing-extensions>=4.7.0",
     "click>=8.0",
     "rich>=10.7",
@@ -39,7 +34,6 @@ keywords = [
     "runtime",
     "self-hosted",
     "python",
-    "ai-agents",
     "ui",
 ]
 classifiers = [
@@ -55,40 +49,35 @@ classifiers = [
 [project.optional-dependencies]
 # Every nustd fabric and kv backend, for cells that reach past the defaults.
 all = [
-    "nustd[all]>=0.6.2",
+    "nustd[all]>=0.6.3",
+]
+# The Nu demos as Planes, for `nuspace demo` and the `+` picker.
+demos = [
+    "nudemos",
 ]
 
 [project.urls]
 Repository = "https://github.com/nustackdev/nuspace"
 
 [project.scripts]
-nuspace = "nuspace.host.cli:main"
+nuspace = "nuspace._cli:main"
 
 [tool.hatch.build.targets.wheel]
-# Whole directories, not python files: the agent's system prompt is prose in
-# `nuspace/agent/prompt/text/*.md`, read at runtime through
-# importlib.resources. hatchling ships every file under a listed package, so
-# this needs no data entry of its own -- but adding an `include` or
-# `only-include` here would drop the prose and leave a wheel whose chats
-# raise on their first message. Don't.
 packages = ["src/nuspace"]
 
 [tool.hatch.build.targets.sdist]
-# pkgs/ holds the sibling distributions (nuverse, nuspace-ui), each shipped
-# from its own directory on its own tag.
+# pkgs/ holds the sibling nuspace-ui distribution, shipped from its own
+# directory on its own tag.
 exclude = [
     "pkgs",
+    ".github",
 ]
 
-[tool.uv.workspace]
-members = ["pkgs/nuverse"]
-
 [tool.uv.sources]
-nuverse = { workspace = true }
 nuspace-ui = { path = "./pkgs/ts/nuspace-ui", editable = true }
 nucore = { path = "../nu", editable = true }
 nustd = { path = "../nu/pkgs/nustd", editable = true }
-nucli = { path = "../nu/pkgs/nucli", editable = true }
+nudemos = { path = "../nuverse/pkgs/nudemos", editable = true }
 
 [tool.uv]
 default-groups = ["dev"]
@@ -153,7 +142,6 @@ line-length = 100
 target-version = "py310"
 src = [
     "src",
-    "pkgs/nuverse/src",
 ]
 extend-exclude = [".venv", "build", "dist", "*.egg-info"]
 
@@ -196,10 +184,9 @@ convention = "google"
 [tool.ruff.lint.isort]
 known-first-party = [
     "nuspace",
-    "nuverse",
     "nu",
     "nustd",
-    "nucli",
+    "nudemos",
 ]
 force-single-line = false
 lines-after-imports = 2

{nuspace-0.5.2 → nuspace-0.5.4}/src/nuspace/__init__.py

@@ -15,8 +15,9 @@ Workers import this package: nothing here may pull in a server.
 """
 
 from nuspace import ops, shapes
-from nuspace.host import Extension, open_space
-from nuspace.ops import TEXT, Plane, Snippet, env
+from nuspace.ext import TEXT, Extension, Plane, Snippet
+from nuspace.host import open_space
+from nuspace.ops import env
 from nuspace.shapes import CellState, PlaneState, Space, States
 from nuspace.system.services import (
     boot,

nuspace-0.5.4/src/nuspace/_cli/__init__.py

@@ -0,0 +1,12 @@
+"""The ``nuspace`` command: run a space, try a demo, make one, check the install.
+
+Pure command line, not an API: nothing imports it, workers least of all.
+
+A space is a directory one process locks at a time, so a command that opens
+one holds it for as long as it is up.
+"""
+
+from .main import cli, main
+
+
+__all__ = ["cli", "main"]

{nuspace-0.5.2/src/nuspace/host/cli → nuspace-0.5.4/src/nuspace/_cli}/__main__.py

@@ -1,4 +1,4 @@
-"""Enables ``python -m nuspace.host.cli``.
+"""Enables ``python -m nuspace._cli``.
 
 The guard is load bearing: workers are spawned, and a child re-imports
 whatever ``__main__`` is. Without it, opening a space forks forever.

nuspace-0.5.4/src/nuspace/_cli/_meta.py

@@ -0,0 +1,78 @@
+"""What the commands share: the console, the versions, and how a space is held open."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any, TypeVar
+
+import rich_click as click
+from rich.console import Console
+from rich.text import Text
+
+import nu
+from nu._branding import PURPLE
+from nuspace import _telemetry
+from nuspace.system.kernel import NotASpace
+
+
+__all__ = [
+    "STORE_ENV",
+    "announce",
+    "console",
+    "hold",
+    "opened",
+    "path_argument",
+    "version_of",
+]
+
+
+#: The environment variable naming the space directory when no path is given.
+STORE_ENV = "NUSPACE_STORE"
+
+console = Console()
+
+_F = TypeVar("_F", bound=Callable[..., Any])
+
+
+def version_of(package: str) -> str:
+    """The installed version of ``package``, or a dev marker when it is not installed."""
+    try:
+        return version(package)
+    except PackageNotFoundError:
+        return "0.0.0+dev"
+
+
+def path_argument(fn: _F) -> _F:
+    """The space directory a command takes, from :data:`STORE_ENV` when absent."""
+    return click.argument("path", required=False, envvar=STORE_ENV)(fn)
+
+
+def announce(path: str | None, how: str) -> None:
+    """Say which space this is and how it is open."""
+    where = path or "Throwaway space, gone at close"
+    console.print(Text.assemble(("nuspace", f"bold {PURPLE}"), ("  ", ""), (where, "dim")))
+    console.print(f"[dim]{how}, Ctrl+C to stop[/dim]")
+
+
+def opened(preset: Callable[..., nu.Nu], *args: object, **kwargs: object) -> nu.Nu:
+    """What ``preset`` opens, or a short error when the path is not a space."""
+    try:
+        return preset(*args, **kwargs)
+    except NotASpace as e:
+        raise click.ClickException(str(e)) from None
+
+
+def hold(term: nu.Nu) -> None:
+    """Run a space until interrupted, then let the brackets reap the fleet.
+
+    The user's first run event goes out here (see :mod:`nuspace._telemetry`):
+    on opening a space, never on import. Compiled and evaluated without law
+    validation: the space program is ours and tested, and validating its
+    whole tree costs seconds per start.
+    """
+    _telemetry.first_run()
+    try:
+        nu.eval_in_loop(nu.compile(term), nu.Context())
+    except KeyboardInterrupt:
+        console.print("[dim]Stopped[/dim]")

nuspace-0.5.4/src/nuspace/_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""The commands of the ``nuspace`` group, one module each."""

nuspace-0.5.4/src/nuspace/_cli/commands/demo.py

@@ -0,0 +1,93 @@
+"""``nuspace demo``: list the demos, or open one in a space.
+
+The demos are the Planes ``nudemos`` registers, an optional extra
+(``nuspace[demos]``). Installed, it registers them for ``+`` in every space
+too; this command opens one straight away through the
+:func:`~nuspace.host.demo` preset. The space is a throwaway one unless PATH
+is given, and not ``$NUSPACE_STORE``: a demo never lands in your space
+unless you name it.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+import rich_click as click
+from rich.table import Table
+from rich.text import Text
+
+from nu._branding import BLUE, PURPLE
+from nuspace.host import presets
+
+from .._meta import announce, console, hold, opened
+
+
+if TYPE_CHECKING:
+    from nuspace.ext import Plane
+
+
+__all__ = ["INSTALL_HINT", "demo", "demos"]
+
+
+#: What to run when the demos are not installed.
+INSTALL_HINT = 'pip install "nuspace[demos]"'
+
+
+def demos() -> dict[str, Plane] | None:
+    """The demo Planes by name, in the order registered. None when the extra is missing."""
+    try:
+        from nudemos import extension
+    except ImportError:
+        return None
+    return {spec.name: spec for spec in extension().planes}
+
+
+def _missing() -> None:
+    console.print("[yellow]The demos are not installed.[/yellow]")
+    console.print(Text.assemble(("install with: ", "dim"), (INSTALL_HINT, f"bold {BLUE}")))
+    sys.exit(1)
+
+
+def _list(found: dict[str, Plane]) -> None:
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column(style=f"bold {BLUE}")
+    table.add_column(style="dim")
+    for name, spec in found.items():
+        table.add_row(name, spec.description)
+    console.print(Text("demos", style=f"bold {PURPLE}"))
+    console.print(table)
+    console.print(
+        Text.assemble(("open one with: ", "dim"), ("nuspace demo <name>", f"bold {BLUE}"))
+    )
+
+
+@click.command(
+    short_help="List the demos, or open one in a space.",
+    help=(
+        "List the demos, or open the one named NAME in a space: a throwaway one,"
+        f" or PATH. Needs the demos extra: {INSTALL_HINT}"
+    ),
+)
+@click.argument("name", required=False)
+@click.argument("path", required=False)
+@click.option("--host", default="127.0.0.1", show_default=True, help="Interface to bind.")
+@click.option("-p", "--port", default=8080, show_default=True, help="Port to bind.")
+@click.option("--no-browser", is_flag=True, help="Do not open a browser tab on the way up.")
+def demo(name: str | None, path: str | None, host: str, port: int, no_browser: bool) -> None:
+    """No name: list. A name: serve that demo until Ctrl+C."""
+    found = demos()
+    if found is None:
+        _missing()
+        return
+    if name is None:
+        _list(found)
+        return
+    if name not in found:
+        console.print(f"[red]Unknown demo:[/red] [bold]{name}[/bold]", highlight=False)
+        console.print(Text.assemble(("available: ", "dim"), (", ".join(found) or "(none)", BLUE)))
+        sys.exit(2)
+    spec = found[name]
+    term = opened(presets.demo, spec, path, host=host, port=port, open_browser=not no_browser)
+    announce(path, f"http://{host}:{port}/{presets.demo_id(spec)}")
+    hold(term)