All three are extensions, written against the interfaces we publish. I have said that before, and it is easy to write and hard to believe. So the repository now carries five sample layouts that make the case the only way it can be made: installable from NuGet, on the public interfaces, turning a notebook into something you would not guess it could be.

All five published 1.2.2 on 2026-09-04, all MIT, each referencing Verso.Abstractions and nothing else. Installed, they show up in the View panel beside the three built-ins, with nothing marking them as newcomers.

Two ways a layout draws

A layout picks one of two renderer modes and stays on it.

An inline layout returns HTML from RenderLayoutAsync with a placeholder where each cell goes. The host matches every [data-cell-slot] element to a cell and mounts the real cell component into the slot. That is why the editor in a Slide Studio deck is the same Monaco editor, run button and all.

An isolated layout draws its own surface instead. It sets RendererIsolation to Isolated and returns its own bundle from GetRendererPackageAsync, and the host mounts that in a sandboxed iframe with a window.verso bridge as the only channel out.

The frame is sandboxed with scripts allowed and nothing else, and the base policy sets connect-src 'none', so an isolated layout cannot fetch anything. Data arrives the other way: read from a kernel variable on the C# side, pushed into the live frame, with edits coming back as interactions.

What each one shows

DAG Notebook links cells by the variables they share, marks a cell stale when its inputs have run more recently, and with auto-run on re-runs a finished cell's dependents in dependency order. The graph is a heuristic scan of the source rather than a proof: a name written by two cells gets warning chips and no edges, and cycles stay out of the cascade. It makes the biggest claim of the five: a layout can change execution semantics, not just how things look. We walked a notebook driven this way in a dial at the top.

Slide Studio is a deck editor: a filmstrip of cell previews, the selected cell's live editor and rendered output behind a draggable splitter, and a full-screen presenter mode. Three checkboxes per cell decide whether a slide is included and whether it shows source, output, or both, and presenting never re-executes anything. It declares cell editing and execution but not insert, delete, or reorder: a deck is arranged here and restructured in the notebook layout.

Grid Studio binds a kernel variable to an editable, Excel-like grid. The schema drives the columns, so numbers edit as numbers and booleans as checkboxes, and committing an edit writes a rebuilt DataBlock back to the same variable. A System.Data.DataTable, such as the results a SQL cell shared, is read-only on purpose: a DataTable can be wired to a data adapter, so writing edits back could prime a database update nobody asked for.

Form Studio is a drag-and-drop dashboard builder. Sliders, dropdowns, toggles, text fields, labels, and charts drop onto a canvas, each input binds to a kernel variable by name, and with auto-run on it re-runs the notebook and pushes fresh data into the charts. The compute cell reads its inputs with Variables.Get<T>("name"), which returns a default before any widget is bound, so the notebook still runs on its own.

Image Studio is a layered compositor: canvas in the middle, layer stack on the right, tools on the left. Layers can be solids, gradients, patterns, text, or procedural, and a procedural layer defers its drawing to a kernel variable, so re-running a code cell repaints it. While it is active it adds PNG Image and SVG Image to the host's Export menu, absent everywhere else.

The habits they share

They theme through the host's --verso-* CSS variables rather than asking what the theme is, so they re-color on a switch without knowing a palette by name. A canvas is the exception, so Form Studio reads the tokens into its chart options.

They persist their own state through layout metadata: a dashboard's widgets, a deck's slide flags, a compositor's layer stack, and a grid's binding all travel in the .verso file, with no sidecar files.

And they read data by reflection rather than by reference. Grid Studio and Form Studio work with DataBlock values from Datafication.Core without referencing that package, reading whichever assembly the kernel loaded with #r "nuget: ...".

Opening one, and building one

Each sample has a notebook beside it naming its package in extensions.required, so the host fetches, loads, and activates the layout before the first render, and an activeLayout entry opens the file straight into it. For a notebook of your own, search Verso.Showcase in the Extensions pane, which finds all five, install one, and trust it when asked, per notebook and pinned to that version.

To write your own, work in the build loop instead. Each sample builds standalone against the local Verso.Abstractions project, then loads with a #!extension line naming the built assembly.

dotnet build samples/showcase/grid-studio/src/Verso.Showcase.GridStudio

#!extension ./src/Verso.Showcase.GridStudio/bin/Debug/net8.0/Verso.Showcase.GridStudio.dll

Why I built five of them

The layout system arrived with 1.1, and the test of an extension surface is whether someone outside the team could build something surprising on it. A spreadsheet with write-back, a presenter, and an image editor with its own document model usually need a fork. Here they are five packages, and the host does not know they are special.

They are samples, not products, each small enough to read in an afternoon. Install one, open a notebook you already have in it, and tell me what the layout gets wrong about your file. The Showcase Extensions pages cover all five, and the Layout Authoring Guide covers the interfaces underneath them.

I wanted to see how small that gets when the languages share memory instead of a folder, so I built a small analysis of the Palmer Penguins dataset inside one Verso notebook. C# parses the table once. Python groups it. SQL aggregates it. PowerShell draws the final table. Three languages do the analysis, a fourth renders it, and none of them exports anything for the next one.

Verso 1.2.2 ships today, and one of the things in it is Verso.DataFrame, a formatter that renders a Microsoft.Data.Analysis.DataFrame as a scrollable table with column names and types. That was the last piece I was missing, so today's the day to write the whole thing down. The formatter and the Palmer Penguins sample notebook it was built against both came from @eosfor, in #94 and #95.

The dataset

Palmer Penguins is body-measurement data for 344 penguins observed on three islands in the Palmer Archipelago, Antarctica, over three field seasons. The palmerpenguins project publishes it as a plain CSV. I like it for the same reason teachers like it: it's small enough to read, it has an obvious grouping, and it has holes in it, which is where real analysis spends its time.

One header row, 344 data rows, and missing values written as the literal text NA.

Eleven rows are missing something. Two of them are missing every measurement and their sex on top of that, and the other nine are missing only sex. That distinction comes back in a few minutes. A count and a mean over the same column can disagree about how many birds there are, and you want to know why before you find it in a chart.

Every cell below reads the file straight from this URL:

https://raw.githubusercontent.com/allisonhorst/palmerpenguins/main/inst/extdata/penguins.csv

Setting up

Install the command line tool and start the browser editor:

dotnet tool install -g Verso.Cli
verso serve

verso serve opens a notebook editor on port 5050. If you'd rather work in VS Code, everything below runs there too: both hosts run the same engine and the same kernels, and the notebook has no idea which one is in front of it.

Two cells want something extra. The SQL step writes to SQLite, so a C# cell pulls the provider in with #!nuget Microsoft.Data.Sqlite. The last cell uses the DataFrame PowerShell module, which the sample notebook installs from a regular PowerShell terminal before you start Verso:

Install-Module DataFrame -Scope CurrentUser

Nothing else gets installed, and no dataset file gets committed anywhere.

Cell 1: fetch and parse, in C

using System.Globalization;
using System.Net.Http;

record Penguin(
    string Species, string Island,
    double? BillLengthMm, double? BillDepthMm,
    double? FlipperLengthMm, double? BodyMassG,
    string Sex, int Year);

double? Number(string field) =>
    field is "NA" or "" ? null : double.Parse(field, CultureInfo.InvariantCulture);

var url = "https://raw.githubusercontent.com/allisonhorst/palmerpenguins/main/inst/extdata/penguins.csv";
var csv = await new HttpClient().GetStringAsync(url);

var penguins = csv
    .Split('\n', StringSplitOptions.RemoveEmptyEntries)
    .Skip(1)
    .Select(line => line.Trim().Split(','))
    .Select(f => new Penguin(
        f[0], f[1],
        Number(f[2]), Number(f[3]), Number(f[4]), Number(f[5]),
        f[6] == "NA" ? null : f[6],
        int.Parse(f[7], CultureInfo.InvariantCulture)))
    .ToList();

penguins.Count

344

Look at what isn't in that cell: a sharing step. When a cell finishes, the kernel walks its own state and publishes what it found into the notebook's variable store. The C# kernel reads Roslyn's script state variables, so csv and penguins are in the store the moment the cell returns, under exactly the names they have in the code. You can put something there by hand with Variables.Set("name", value), but for ordinary top-level variables you never have to.

One store per session, no per-kernel isolation. Every cell that runs after this one, in any language, can see both names.

Cell 2: group it, in Python

Python runs out of process, against the CPython you already have on your machine, so the rows reach it as data instead of as .NET objects. A record shows up as a mapping that answers both spellings, p.Species and p["Species"], so a list of records reads like a list of small objects on the Python side.

import pandas as pd

df = pd.DataFrame([
    {
        "species": p.Species,
        "island": p.Island,
        "bill_length_mm": p.BillLengthMm,
        "flipper_length_mm": p.FlipperLengthMm,
        "body_mass_g": p.BodyMassG,
        "sex": p.Sex,
    }
    for p in penguins
])

for (species, island), group in df.groupby(["species", "island"]):
    print(f"{species:<10} {island:<10} {len(group):>4}  {group['body_mass_g'].mean():>8.1f}")

minMass = int(df["body_mass_g"].median())
print(f"\nmedian body mass: {minMass} g")

Adelie     Biscoe       44    3709.7
Adelie     Dream        56    3688.4
Adelie     Torgersen    52    3706.4
Chinstrap  Dream        68    3733.1
Gentoo     Biscoe      124    5076.0

median body mass: 4050 g

Two things fall out of that. The shape of the data is the easy one: Adelie penguins are on all three islands, Chinstrap only on Dream, Gentoo only on Biscoe, and Gentoo outweigh the other two by well over a kilogram.

The second is the null handling, and it's the kind of thing I like catching early. Adelie on Torgersen counts 52 birds and averages 51 masses. One of the two rows with no measurements is a Torgersen Adelie, and pandas leaves it out of the mean without warning you. A C# double? with no value arrives in Python as None, pandas turns a numeric column containing None into float64 with NaN, and mean quietly ignores it while len does not. Which of the two you want is your call. Noticing you have a call to make is the part that gets easier here, because the C# cell that produced the nulls is right above this one.

The last line assigns minMass. Work you do in Python comes back when you assign a name, so minMass is now in the same store as penguins and csv, ready for the next language. The one thing that doesn't come back is modifying a shared collection in place, so assign your result to a name instead of appending to a list that came from another language.

Cell 3: put the same rows in a database, in C

The SQL kernel talks to a database over ADO.NET, so it needs a real one. This cell writes the rows that are already in memory into a SQLite file. It's the only cell in the notebook that writes a file, and it does that because a database is the point of the next two cells, not because the table had to be handed over.

#!nuget Microsoft.Data.Sqlite

using Microsoft.Data.Sqlite;
using System.IO;

var dbPath = Path.Combine(Path.GetTempPath(), "penguins.db");
File.Delete(dbPath);

var db = new SqliteConnection($"Data Source={dbPath}");
db.Open();

var ddl = db.CreateCommand();
ddl.CommandText = @"CREATE TABLE penguins (
    species TEXT, island TEXT,
    bill_length_mm REAL, bill_depth_mm REAL,
    flipper_length_mm REAL, body_mass_g REAL,
    sex TEXT, year INTEGER)";
ddl.ExecuteNonQuery();

var tx = db.BeginTransaction();
var insert = db.CreateCommand();
insert.Transaction = tx;
insert.CommandText =
    "INSERT INTO penguins VALUES (@species, @island, @billLength, @billDepth, @flipper, @mass, @sex, @year)";
foreach (var name in new[]
    { "@species", "@island", "@billLength", "@billDepth", "@flipper", "@mass", "@sex", "@year" })
    insert.Parameters.Add(new SqliteParameter(name, DBNull.Value));

foreach (var p in penguins)
{
    object[] values =
        { p.Species, p.Island, p.BillLengthMm, p.BillDepthMm, p.FlipperLengthMm, p.BodyMassG, p.Sex, p.Year };
    for (var i = 0; i < values.Length; i++)
        insert.Parameters[i].Value = values[i] ?? DBNull.Value;
    insert.ExecuteNonQuery();
}

tx.Commit();
db.Close();

$"{penguins.Count} rows written"

344 rows written

#!nuget resolves the package for the session before the cell body runs, which is why the using on the very next line works in the same cell. The path lands in dbPath, which goes into the store with everything else. That turns out to matter one cell later.

Cell 4: connect

#!sql-connect --name penguins --connection-string "Data Source=$var:dbPath" --provider Microsoft.Data.Sqlite

A $var: token in a connection string is replaced with a variable from the notebook's store, and $env: does the same for an environment variable. So the string doesn't have to repeat a path a cell already computed, and it doesn't have to carry a password in the notebook file either. When it connects, the output names the connection, the provider, and the database, with the connection string redacted.

You can leave --provider off here. A connection string pointing at a .db file is detected as SQLite on its own. I still name it, because sooner or later somebody else reads this.

Cell 5: aggregate, in SQL

-- --name heavyBirds
SELECT species,
       island,
       COUNT(*)                   AS n,
       ROUND(AVG(body_mass_g), 1) AS mean_mass_g
FROM penguins
WHERE body_mass_g > @minMass
GROUP BY species, island
ORDER BY mean_mass_g DESC

Two things in that cell are not SQL. The first line, the comment starting with --, is read as cell directives. --name heavyBirds puts the result in the store under that name instead of the default lastSqlResult. The other flags you can put on that line are --connection to target a named connection, --page-size, --no-display, and --timeout.

The second is @minMass, which you never declared as a SQL parameter anywhere. SQL cells resolve @name bindings from the same variable store, matching case-insensitively, and the kernel maps the .NET type to a DbType for you. So minMass was computed by pandas three cells ago and it's now the filter in a SQLite query. If you want the whole argument of this post in one line, that's it.

Use the bind syntax your database uses. @name is right for SQL Server, PostgreSQL, MySQL, and SQLite, and Oracle uses :name. A query copied out of another client runs unchanged.

Cell 6: the result comes back to Python

heavy = pd.DataFrame(heavyBirds)
above = int(heavy["n"].sum())
print(f"{above} of {len(df)} birds are above the median ({above / len(df):.1%})")

166 of 344 birds are above the median (48.3%)

On the .NET side a SQL result is a System.Data.DataTable. In Python it arrives as a list of row mappings, which is exactly the shape pd.DataFrame builds a frame from, so there is no conversion step to write. Date columns arrive as real datetime values, and a NULL arrives as None.

Notice df is still around. This is the same Python session as cell 2, so the frame built up there is still in memory and I can compare the two results without rebuilding either one.

Cell 7: render it, in PowerShell

The last cell goes back to csv, the raw string the C# cell downloaded, and loads it into a Microsoft.Data.Analysis.DataFrame with explicit column types. PowerShell sees shared variables as ordinary variables, so $csv is just there.

Import-Module DataFrame

$columnTypes = @(
    [string],   # species
    [string],   # island
    [double],   # bill_length_mm
    [double],   # bill_depth_mm
    [double],   # flipper_length_mm
    [double],   # body_mass_g
    [string],   # sex
    [int]       # year
)

$frame = Import-DataFrame -String ($csv -replace '(?m)(^|,)NA(?=,|$)', '$1') -ColumnType $columnTypes
$frame

Microsoft.Data.Analysis reads an empty numeric field as a null, so the NA markers get blanked out before the import. The regular expression only touches a field that is exactly NA, which is why it's anchored on a comma or a line boundary at both ends.

The last line returns the frame, and as of today it renders as a table.

The header carries the column name and the column's type, it stays put while the body scrolls, and a null renders as the word null rather than an empty cell. The table is a bounded preview on purpose: the first 100 rows and the first 50 columns, the frame's real totals in the footer, and any single value longer than 200 characters shortened. A wide or long frame can't swamp your output, and the footer always tells you what you're looking at.

The formatter reads the frame through reflection and takes no dependency on Microsoft.Data.Analysis, so the PowerShell module that created the frame keeps ownership of that assembly and there's no second copy to argue with. It's built into the VS Code extension, verso serve, and verso run, and it's published as Verso.DataFrame on NuGet if you're embedding the engine yourself. An explicit Display $frame renders the same way. And if you've already written your own DataFrame formatter, give it a priority above 50 and it stays in front of this one.

What crosses, and what doesn't

Python is a separate process, so values reach it as data. Most of that you never notice, and the parts you do are worth knowing before you lean on them.

That last row is a decision, not an accident. A value with no meaning outside the process that made it doesn't silently vanish. The name is still bound, and printing it tells you what happened:

<callback was not shared with Python: a function, which cannot be called from another process>

The value stays usable in the language that produced it. Two smaller rules go with that. A name beginning with a double underscore never reaches a Python cell, because the interpreter owns that prefix. And going the other way, datetime, Decimal, UUID, bytes, NumPy arrays, and pandas frames and series all convert back.

There's more on all of this in One variable store, eight languages, no hand-off, and on how the Python side is hosted in Python cells that run the Python you already have.

Two ways to finish

That's seven cells, and it stands on its own. Two things I'd do with it next.

The first is to turn it into a job. Declared parameters are coerced to CLR types and injected into the same variable store before any cell runs, so a parameter is just another name all four kernels can read. Add a species parameter, filter on it, and the notebook runs unattended:

verso run penguins.verso --param species=Gentoo --output json --output-file result.json

The exit codes are deterministic, so a pipeline can act on them: 0 for success, 1 for a cell failure, 2 for a timeout, and 5 for missing required parameters. I covered that end to end in Run the same notebook in CI that you run at your desk.

The second is to hand the result to somebody. Layout is a property of the file, so switching to the Presentation or Dashboard layout changes what a reader sees without touching a single cell.

Why it's worth the trouble

Here's how the neighbors do this. A Jupyter notebook binds one kernel, and the notebook's kernelspec metadata names one kernel specification for the document. In Polyglot Notebooks, several languages do live in one notebook, and each value that moves between them is named in a #!share or #!set command. The copy is made through the application/json MIME type by default, and for .NET-based kernels the serialization is done with System.Text.Json. Reference sharing is available under stated conditions: both kernels in the same process, both CLR-based, and --byref when using #!set.

Our answer is one VariableStore per session with no per-kernel isolation, which the kernels publish into and read from on their own. You saw the cost back in cell 2: a value that crosses a process boundary crosses as data, and Verso tells you plainly when something cannot make the trip. What you get for it is a notebook where the interesting line is WHERE body_mass_g > @minMass instead of the twenty lines it would otherwise take to get minMass from pandas into SQLite.

Get it

Verso 1.2.2 is on NuGet today, and the notebook editor is on the Visual Studio Marketplace.

dotnet tool install -g Verso.Cli
code --install-extension Datafication.verso-notebook

Build the seven cells yourself, or run your own table down the same path. If a value crosses a language boundary and comes out wrong, that's the report I most want to see.

The DataFrame formatter and the Palmer Penguins sample notebook it grew out of were contributed by @eosfor in #94 and #95. The dataset itself comes from the palmerpenguins project. The guides for everything used above are at versonotebooks.com/docs, and Verso itself is MIT-licensed at github.com/DataficationSDK/Verso.

Everything I needed to stop doing that shipped in Motus 1.0.15, so I built a suite around it. The one rule I gave myself was that a run has to leave enough on disk to answer what happened without rerunning anything. Here's what that looks like.

What I pointed it at

Two public pages the Motus samples already drive: https://example.com and https://www.iana.org/domains/reserved. Neither of them belongs to me, and that turned out to be the useful part of the exercise.

When you test a page you control, you can be sloppy about the difference between a finding that should stop a build and a finding you only want written down, because you can always go fix the page. When the page is somebody else's, you have to decide up front. That decision shows up in almost every section below.

Getting the project set up

Start with the tool and a browser.

dotnet tool install --global Motus.Cli
motus install

motus install downloads a Chrome for Testing build into ~/.motus/browsers. After that, the project is ordinary MSTest.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <IsTestProject>true</IsTestProject>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.11.0" />
    <PackageReference Include="MSTest.TestAdapter" Version="3.5.2" />
    <PackageReference Include="MSTest.TestFramework" Version="3.5.2" />
    <PackageReference Include="Motus" Version="1.0.15" />
    <PackageReference Include="Motus.Testing.MSTest" Version="1.0.15" />
    <PackageReference Include="Motus.Analyzers" Version="1.0.15" />
  </ItemGroup>
</Project>

Motus.Analyzers is optional and I would take it every time. It's seven Roslyn diagnostics that catch an unawaited call, an undisposed browser and a navigation with no wait after it, at compile time instead of at three in the morning. One heads-up when you go looking for it: an unrelated motion-planning library shares the name on nuget.org, so use the package page link and you'll land on the right one.

Usings.cs:

global using Microsoft.VisualStudio.TestTools.UnitTesting;
global using Motus.Abstractions;
global using Motus.Assertions;
global using Motus.Testing.MSTest;

AssemblySetup.cs launches one browser for the whole assembly. Each test still gets its own context and page, created and closed by the base class.

namespace PublicPages.Tests;

[TestClass]
public class AssemblySetup
{
    [AssemblyInitialize]
    public static async Task InitializeAsync(TestContext _) =>
        await MotusTestBase.LaunchBrowserAsync(new LaunchOptions { Headless = true });

    [AssemblyCleanup]
    public static async Task CleanupAsync() =>
        await MotusTestBase.CloseBrowserAsync();
}

You'll notice the accessibility, performance and coverage options are not set anywhere in that code. That's on purpose. Leaving them unset is what lets the config file and the MOTUS_* variables fill them in. Configuration layers file, then environment, then code, so whatever you hardcode wins and whatever you leave alone stays steerable from CI.

{
  "motus": "1.0",
  "launch": { "headless": true, "timeout": 30000 },
  "context": { "viewport": { "width": 1280, "height": 720 } },
  "assertions": { "timeout": 10000 },
  "accessibility": {
    "auditAfterNavigation": true,
    "includeWarnings": true,
    "skipRules": ["a11y-missing-landmark"]
  },
  "flaky": {
    "retryPolicy": "flake",
    "retries": 2,
    "historyPath": "artifacts/flake-history.json"
  }
}

I spelled out includeWarnings even though its default is already true, because that default is the one people trip over: a warning, not just an error, is enough to fail an audit assertion. Both of these pages trip a11y-missing-landmark, so the file skips it for the hook and the assertion below skips it for itself.

The tests

Four tests on the example domain, four on the reserved-domains page, and one that exists only to capture evidence.

namespace PublicPages.Tests;

[TestClass]
[PerformanceBudget(Lcp = 4000, Fcp = 3000, Ttfb = 2000, Cls = 0.25)]
public class ExampleDomainTests : MotusTestBase
{
    private const string Url = "https://example.com";

    private async Task OpenAsync()
    {
        await Page.GotoAsync(Url);
        await Page.WaitForLoadStateAsync(LoadState.Load);
    }

    [TestMethod]
    public async Task Page_HasItsTitleAndHeading()
    {
        await OpenAsync();

        await Expect.That(Page).ToHaveTitleAsync("Example Domain");
        await Expect.That(Page.GetByRole("heading", "Example Domain")).ToBeVisibleAsync();
    }

    [TestMethod]
    public async Task Page_LinksToTheIanaRecord()
    {
        await OpenAsync();

        var link = Page.GetByRole("link", "Learn more");
        await Expect.That(link).ToBeAttachedAsync();
        await Expect.That(link).ToHaveAttributeAsync("href", "https://iana.org/domains/example");
    }

    [TestMethod]
    public async Task Page_MeetsItsBudget()
    {
        await OpenAsync();

        await Expect.That(Page).ToMeetPerformanceBudgetAsync();
    }

    [TestMethod]
    public async Task Page_PassesTheRulesWeGateOn()
    {
        await OpenAsync();

        await Expect.That(Page).ToPassAccessibilityAuditAsync(
            o => o.SkipRules("a11y-missing-landmark"));
    }
}

The ToBeAttachedAsync on the link is not decoration, and if you take one thing from this post I would like it to be this one. A locator assertion polls for state once the element is attached. It does not wait for one to appear. So ToBeVisibleAsync on a selector matching nothing fails almost at once rather than after its timeout. Fast failures are usually good news, but not that one. ToBeAttachedAsync, ToBeDetachedAsync and ToHaveCountAsync are the three that are safe before the element exists, so one of them goes first.

The second class covers the response, the content, a network failure and a test I do not trust.

namespace PublicPages.Tests;

[TestClass]
public class ReservedDomainsTests : MotusTestBase
{
    private const string Url = "https://www.iana.org/domains/reserved";

    private async Task<IResponse?> OpenAsync()
    {
        var response = await Page.GotoAsync(Url);
        await Page.WaitForLoadStateAsync(LoadState.Load);
        return response;
    }

    [TestMethod]
    public async Task Page_RespondsWithTwoHundred()
    {
        var response = await OpenAsync();

        Assert.IsNotNull(response);
        await Expect.That(response).ToHaveStatusAsync(200);
    }

    [TestMethod]
    public async Task Page_HasAnExampleDomainsSection()
    {
        await OpenAsync();

        await Expect.That(Page.GetByRole("heading", "Example domains")).ToBeVisibleAsync();
    }

    [TestMethod]
    public async Task Page_RendersItsHeadingWithoutItsStylesheet()
    {
        await Page.RouteAsync("**/*.css", route => route.AbortAsync());

        await OpenAsync();

        await Expect.That(Page.GetByRole("heading", "IANA-managed Reserved Domains"))
            .ToBeVisibleAsync();
    }

    [TestMethod]
    [Quarantine(Reason = "Section headings follow IANA policy, not our code")]
    public async Task Page_ListsTheTestIdnTopLevelDomains()
    {
        await OpenAsync();

        await Expect.That(Page.GetByRole("heading", "Test IDN top-level domains"))
            .ToBeVisibleAsync();
    }
}

RouteAsync with AbortAsync is the cheapest way I know to test a failure you cannot otherwise arrange. I want to know the heading still renders when the stylesheet never shows up, and there is no way for me to make that happen on a server I do not run.

The last one is where [Quarantine] earns itself. That test's subject is somebody else's editorial decision, so it will change when IANA decides it should and not when I do. Quarantine keeps the test rather than deleting it: it runs, and it reports, in its own bucket, without gating the run. If you would rather not put the attribute in the source, a --quarantine list file does the same job from outside.

What actually gates the build

Two of the gates are the assertions you just read. The rest divide the same way all the way through: the flag decides whether a collector runs at all, and the file or the attribute supplies the numbers.

--perf-budget sets no numbers of its own, and that catches people out. With no attribute and no performance section there is nothing to enforce, and ToMeetPerformanceBudgetAsync throws rather than passing on an empty budget. I would rather it throw. A green test that measured nothing is worse than a red one.

Be clear-eyed about the accessibility side too. The nine rules are Motus's own, read from the browser's accessibility tree over the protocol, and they are not an axe-core replacement. Both gates are covered in more detail in Accessibility and performance are assertions.

Running it locally:

dotnet build -c Release
motus run bin/Release/net8.0/PublicPages.Tests.dll \
  --a11y warn \
  --perf-budget \
  --coverage console \
  --reporter console \
  --reporter html:artifacts/report.html

--a11y warn audits after every navigation and prints what it finds without failing anything, which is the right setting for pages you do not own. On this suite it reports the missing main landmark on both pages, and a missing document language attribute on the reserved-domains page. Neither one gates the build. They are real findings on markup I did not write, and I would rather see them and decide for myself than have a build tell me what to do about them.

What one test leaves behind

This is the test I am a little proud of. It records the same short scenario three ways and stops each recorder in a finally, so the artifacts exist on disk whether the assertion held or not. That second part matters more than the recording does. The run you want to look at afterward is the one that failed.

namespace PublicPages.Tests;

[TestClass]
public class EvidenceTests : MotusTestBase
{
    [TestMethod]
    public async Task FollowingTheLink_LeavesATraceAHarAndAVideo()
    {
        Directory.CreateDirectory("artifacts");

        await Context.Tracing.StartAsync(new TracingStartOptions
        {
            Screenshots = true,
            Snapshots = true,
        });
        await Page.StartHarRecordingAsync();
        await Page.StartVideoRecordingAsync("artifacts/follow-the-link.avi");

        try
        {
            await Page.GotoAsync("https://example.com");
            await Page.WaitForLoadStateAsync(LoadState.Load);

            await Page.GetByRole("link", "Learn more").ClickAsync();

            await Expect.That(Page).ToHaveTitleAsync("Example Domains");
        }
        finally
        {
            await Page.StopVideoRecordingAsync();
            await Page.StopHarRecordingAsync("artifacts/follow-the-link.har");
            await Context.Tracing.StopAsync(new TracingStopOptions
            {
                Path = "artifacts/follow-the-link.zip",
            });
        }
    }
}

Three details there are easy to get wrong, so here they are together. Tracing is on the context and browser-wide underneath, so concurrent starts serialize behind a gate, and one tracing test per suite is the comfortable number. HAR recording is per page, and it is the stop call that takes the path. Video is MJPEG frames in an AVI container, at viewport size, with no pointer drawn and no transcoding, so reach for ffmpeg when you need another format.

Open it with the CLI:

motus trace show artifacts/follow-the-link.zip --port 5200

That starts the visual runner in trace mode and opens your default browser. The archive is Motus's own layout, and this is its viewer.

That redirect is the reason I record all three instead of picking one. The click reads as a single action in the trace. The video shows a page that changes. Only the HAR shows the href returning a 301 before the browser reached the page the assertion checks. Three views of the same short scenario, and each one knows something the other two do not.

Coverage

Coverage is per test. It's collected over the protocol when a page closes, and remapped through source maps when a script has one.

motus run bin/Release/net8.0/PublicPages.Tests.dll \
  --coverage console \
  --coverage html:artifacts/coverage

The console reporter prints a per-file table and an overall line. The HTML reporter writes index.html plus a page per file. Thresholds are deliberately not a command-line option: they live in coverage.js.lines and coverage.css.rules, and a run below one exits non-zero.

This suite sets neither, and I want to be honest about why. The code being measured is somebody else's, so a threshold here would be a number about their scripts, not about my tests. On your own app it's the other way around, and that's where I'd set one.

Splitting it four ways

motus run --shard <index>/<total> sorts the discovered tests by assembly path and fully qualified name, then deals them out round-robin. That's the whole algorithm, and it works because every agent computes the same partition without talking to any other one. The sort makes it reproducible across machines. The round-robin stops one slow class landing on one agent.

jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - run: |
          motus run bin/Release/net8.0/PublicPages.Tests.dll \
            --shard ${{ matrix.shard }}/4 \
            --a11y warn --perf-budget \
            --retries 2 --retry-policy flake \
            --flaky-history artifacts/flake-history.json \
            --reporter junit:results.shard-${{ matrix.shard }}.xml
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: artifacts-${{ matrix.shard }}
          path: |
            results.shard-*.xml
            artifacts/

  merge:
    needs: test
    if: always()
    steps:
      - uses: actions/download-artifact@v4
      - run: motus shard merge **/results.shard-*.xml --output junit:results.xml --expect 4

fail-fast: false lets every shard finish after one of them fails, and if: always() runs the merge even when a shard job failed. Those two go together. The run where a shard blew up is exactly the run where you want the combined report.

--expect 4 guards the failure that sharding introduces, and it is the flag I would not leave off. Each shard stamps motus.shard.index and motus.shard.total into its result file. The merge reads them back and fails when one is missing or when an index turns up twice. Without it, an agent that died before writing anything produces a smaller report that is entirely green and looks fine, and you will believe it, because there is nothing in it to disbelieve.

Two limits are worth knowing before you add agents. Shards balance by count, not by duration, so a suite dominated by one slow test gains nothing from more of them. And the index is 1-based, so --shard 0/4 is rejected rather than guessed at.

Flaky, quarantined, or broken

Live pages over a shared network are a classic source of a failure that means nothing at all. --retry-policy decides which failures earn another attempt, and the two policies are further apart than the names suggest.

transient is the default and re-runs only a lost browser, which cannot mask a bug: a browser that vanished never told you anything about your code in the first place. flake re-runs any failure, assertion failures included, and labels a test that then passes as flaky rather than green. That label is the half that matters. Every attempt rebuilds the test instance and its context, and data from a failed attempt is discarded.

The console reporter shows you the outcome by name:

  [PASS] PublicPages.Tests.ExampleDomainTests.Page_HasItsTitleAndHeading
  [FLAKY] PublicPages.Tests.ExampleDomainTests.Page_MeetsItsBudget (after 2 attempts)
  [QUARANTINE] PublicPages.Tests.ReservedDomainsTests.Page_ListsTheTestIdnTopLevelDomains

Results: 8 passed, 0 failed, 1 flaky, 1 quarantined, 9 total

That run exits zero. --fail-on-flaky makes it exit non-zero, and it is what stops a suite drifting into needing retries everywhere while still reporting success. I would not switch it on the first day, though. Let --flaky-history accumulate per-test counters first:

{
  "PublicPages.Tests.ExampleDomainTests.Page_MeetsItsBudget": {
    "runs": 128,
    "failures": 3,
    "flakyPasses": 17,
    "lastSeenUtc": "2026-08-30T14:02:11Z"
  }
}

A flake rate is (failures + flakyPasses) / runs, and that's the number to sort by when you're deciding what to fix first. Persist the file between runs, as a CI cache or a committed artifact. If you don't, every run starts from nothing and you have a file that only ever describes the last few minutes.

Pinning the browser

A run that passed last week and fails this week with no commit behind it is usually a browser that moved. --channel takes whatever is installed. Pinning replaces that with an exact binary:

motus install --channel chromium --revision 149.0.7827.156
export MOTUS_EXECUTABLE_PATH="$(cat ~/.motus/browsers/.installed.chromium)"

--revision takes a Chrome for Testing version in dotted form. The marker file the installer writes holds the resolved executable path, so the install step can export it and nothing later in the job has to go hunting for where it landed. A path set in code still wins over the variable, which is the same layering from earlier showing up again.

Where this one falls short

It cannot run on Firefox as written, and I would rather say that here than have you find out from a failing job. Tracing, RouteAsync interception and code coverage all go through Chrome DevTools Protocol domains that a Firefox session driven over WebDriver BiDi does not have. The capability guard says so by name rather than failing obscurely, which is the best I can do about it right now. Locators, actions, assertions and script evaluation all work there. Those three do not.

Every artifact, and what it answers

None of that is a separate tool, a second browser session or another package. It is one suite, one browser, and a run you can ask what it saw.

Every flag and key above is documented at motustesting.com/docs, nearest the sharding, flaky tests and CLI pages. Motus is MIT licensed and the source is on GitHub. Build something like this, kill a shard on purpose, and tell me whether the merged report told you what happened.

The DAG Notebook layout does that part for you: it reads the notebook, works out which cells feed which, and when a cell finishes running it runs that cell's dependents, in dependency order. It shipped with Verso 1.2 as Verso.Showcase.DagNotebook, an ordinary package on NuGet.

What I like about it is where it lives. Reactive execution is normally a property of the notebook tool you picked. Here it is a layout extension sitting on the same public interfaces as everything else, which is what treating every feature as an extension buys you.

So let me build one in front of you: a week of forecast from a public API, an ipywidgets slider, one #!bind line, and two C# cells that follow the slider on their own.

Getting the layout in front of you

This one is an inline layout, so your cells stay the real, editable cells and the layout supplies the frame around them. Install the command line tool and open a notebook.

dotnet tool install -g Verso.Cli
verso serve weather.verso

A notebook can also ask for the extension itself. Two entries in its metadata block name the package and pin the layout, so the host installs it from NuGet and opens straight into it.

"activeLayout": { "extensionId": "com.verso.showcase.dag-notebook", "layoutId": "dag-notebook" },
"extensions": { "required": ["Verso.Showcase.DagNotebook"] }

Otherwise install it from the Extensions pane and pick DAG Notebook from the layout picker. Approving an extension is per notebook and pinned to the version you approved. Everything below works the same in VS Code and in the browser host verso serve starts.

The data

The forecast comes from the Open-Meteo forecast API, which needs no key. This is the request the weather briefing notebook in the Verso gallery makes.

using System.Net.Http;
using System.Text.Json;

var url = "https://api.open-meteo.com/v1/forecast"
        + "?latitude=47.6062&longitude=-122.3321"
        + "&daily=temperature_2m_max,temperature_2m_min"
        + "&temperature_unit=fahrenheit&timezone=America%2FLos_Angeles&forecast_days=7";

var json = await new HttpClient().GetStringAsync(url);
var daily = JsonDocument.Parse(json).RootElement.GetProperty("daily");

var days = daily.GetProperty("time").EnumerateArray()
    .Select(d => DateTime.Parse(d.GetString()!).ToString("ddd")).ToArray();
var highs = daily.GetProperty("temperature_2m_max").EnumerateArray()
    .Select(t => t.GetDouble()).ToArray();
var lows = daily.GetProperty("temperature_2m_min").EnumerateArray()
    .Select(t => t.GetDouble()).ToArray();

Console.WriteLine($"{days.Length} days for Seattle, highs {highs.Min():F1} to {highs.Max():F1}°F.");

7 days for Seattle, highs 67.8 to 85.2°F.

A forecast is live data, so your run gives a different week. Every number here comes from one response, saved inside that gallery notebook from a call made on 2026-07-04, so the figures are checkable rather than asserted.

An HTTP cell would fetch the same thing in two lines of .http syntax, and I did not use one. The dependency scan reads C#, Python, and F# source, and a variable an HTTP cell publishes is not an assignment anywhere in that source, so the scan cannot see it. Fetching in C# keeps the whole notebook inside the graph.

The slider

Two Python cells. The first builds the slider, the second shares it.

#!pip ipywidgets
import ipywidgets as widgets

slider = widgets.IntSlider(value=70, min=40, max=100,
                           description="Threshold", continuous_update=False)
slider

The #!pip line is there for a notebook that has to run anywhere. In the editor you can leave it out, because the default install policy offers to install what a cell imports and cannot find. On the command line it does real work: verso run never installs on import, and --auto-install covers only the distributions Verso keeps a mapping for.

continuous_update=False holds the value until you let go of the handle. You do not need it, because even with continuous updates the cascade runs once per gesture.

The next cell is one line, and it is the line that turns the notebook on.

#!bind slider.value as threshold

'threshold' now follows slider.value. Any kernel can read it, and writing it moves the widget.

From here threshold is an ordinary entry in the shared variable store, which every kernel can read from and write to.

The trait is an Int, so other kernels see a long. A Float arrives as a double, a Unicode as a string, and a Dict as a dictionary keyed by string. A trait holding another widget is refused, and so is a value over the megabyte a projected value may occupy, because a projection crosses on every change and a dragged control changes many times a second.

The two cells that read it

Two C# cells, written the way you would write any cell that reads a variable. Neither knows a widget exists.

var cutoff = Variables.Get<long>("threshold");
var warmDays = days.Zip(highs, (d, h) => (Day: d, High: h))
                   .Where(x => x.High >= cutoff)
                   .ToArray();

Console.WriteLine($"{warmDays.Length} of {days.Length} days at or above {cutoff}°F.");

5 of 7 days at or above 70°F.

var atOrAbove = Variables.Get<long>("threshold");
var listed = warmDays.Length == 0 ? "none" : string.Join(", ", warmDays.Select(w => w.Day));

$"{atOrAbove}°F and above: {listed}."

70°F and above: Sun, Mon, Tue, Thu, Fri.

That is the whole notebook: five code cells, no prose cells in between, so the numbers the layout draws are the numbers you just saw.

What the layout drew

Every linked cell gets a row of chips above it. ↑ 1 days means this cell reads days from cell 1. ↓ 5 warmDays means cell 5 reads warmDays from this one. ↻ threshold marks a variable that follows a control instead of a computation. Chips are numbered by document position but tracked by cell identity, so they survive a reorder, and clicking one scrolls you to the other end of the link.

Put every chip together and you have the graph. Cell 1 feeds cell 4 twice, once for days and once for highs. Cell 2 feeds cell 3, because the bind directive names the object it binds. Cell 3 produces threshold, which both C# cells read. Cell 4 feeds cell 5. lows gets parsed and read by nobody, so it gets no chip.

Moving the dial

Press Run DAG once. That button lives in the layout's own header and runs every cell in dependency order rather than document order. The host's Run All is untouched and keeps its document-order behavior, and the two coexist on purpose.

Then drag the slider and let go. Cells 4 and 5 re-run on their own, in that order, with nothing clicked. Cell 4 prints its count, cell 5 names the days.

Cell 1 never runs again. It does not depend on threshold, so no forecast is fetched a second time, which is the difference between this and Run All.

The trigger is a completed run, not a keystroke. When a cell finishes successfully, the layout runs that cell's transitive dependents one at a time, in topological order, through the same notebook operations you would drive by hand. Strictly sequential is the point: a dependent must not start before its producer has finished.

A drag is one run, not one per step. The cascade waits before it starts, and a change that arrives inside that window replaces the one before it. The sample's own constants are 300 milliseconds after a completed run and 450 after a moved control. The longer one is deliberate, because a dragged slider writes its variable many times a second and each write cancels the trigger the last one scheduled. That window also keeps a batch run honest: any cell starting inside it cancels the pending trigger, so a document-order Run All finishes on its own terms.

Turn Auto-run dependents off and drag again: cells 4 and 5 draw a dashed border and wait. The mark shows up the moment a producer starts running and clears when the cell catches up. The toggle round-trips through the layout's metadata, so a notebook saved with it off stays off.

How the graph is built

This is the part I would read twice, because it holds the honest limits.

On every render the layout scans each code cell for the variables it defines, meaning assignments, functions, and type declarations, and the names it references, including names inside interpolated strings. A variable with exactly one defining cell links that producer to every cell that reads it. The scan covers C#, Python, and F#. The sample's own README calls it a lightweight heuristic pass and a strong hint rather than a proof, which is the right way to hold it: it reads source text, it does not compile it.

Two of the ways a cell writes a variable are not assignments at all. #!bind shares a widget's trait, and Variables.Get("name") and Variables.Set("name", ...) reach the shared store by a name that lives inside a string literal. Both get read before comments and string literals are stripped away, and that one decision is what lets a Python control link to a C# cell instead of the graph stopping dead at each language boundary.

Cell 3 holds nothing but #!bind slider.value as threshold. To Python that line is a comment. To the scan it is a cell that reads slider and writes threshold, which is the pair of edges the graph needs.

When it refuses to cascade

When the layout is not sure it says so rather than guessing, and that matters more to me than the happy path.

The failure row is the one to plan around. A cascade is not a transaction: if cell 4 throws, cell 5 keeps its stale marker and its old output, and the notebook is left honestly half updated.

The multi-writer row is easy to trip over. Give a variable the same name in two cells and both get a warning chip and the links vanish. The pricing sample that ships with the layout assigns counter twice on purpose so you can watch it happen.

The link runs both ways

Writing the variable from a cell moves the slider on the page.

Variables.Set("threshold", 80L);

The control moves, the author's observe callbacks fire, and every other kernel sees 80.

That symmetry is what makes a cell writing the variable it reads safe. A control driving a cell that writes the same name back is a loop the scan cannot see, because the write happens at run time and not in the source. What settles it is that a fresh reading of every bound variable is taken each time a cell completes.

#!bind --list tells you what is currently shared:

Widget traits shared as variables:
  threshold  <-  slider.value

#!bind --remove threshold stops the two following each other without deleting anything, so a cell reading the name keeps working on its last value. A kernel restart does the same, and re-running the #!bind line reconnects it.

Where the limits are

A widget's state travels in the notebook file, but the JavaScript that draws it comes from a public CDN when the widget is shown, so a machine with no network draws an empty frame. A saved file holds the state the reader last saw, not the state the cell drew: drag the slider to 98, save, and the file says 98.

Widgets are live in the editor, whether you served the notebook with verso serve or opened it in VS Code. A notebook run by verso run has no view to talk to, so there the slider draws from its saved state and the C# cells read whatever that state holds. That is right for a scheduled job, and it means one file is both an instrument you play at your desk and a script that produces one answer in a pipeline. If the pipeline should pick the number, use notebook parameters rather than the slider.

What I take from this

Five cells, two languages, one variable, and a package. The reactive behavior is not in the engine, not in the file format, and not in the editor. It is in a layout extension that references Verso.Abstractions and nothing else, bundles no third-party libraries, and is MIT licensed like everything around it. If reactive execution can arrive as a package, so can whatever else you were going to ask us to build in.

Both samples, dag-notebook.verso and dag-notebook-widget.verso, sit in the sample folder on GitHub with the layout's source. The first seeds a small pricing model, where two base inputs feed revenue, revenue feeds profit, and a summary cell reads all three. The Interactive Widgets guide covers #!bind and the projected types, and the layout authoring guide is where to start on one of your own. If you build one, I would like to hear where it got awkward.

The steps below are in the order you would do them. There is a section near the end that says what does not come across, because a migration guide that hides the losses is not worth following.

Before you start

You need the .NET 8 SDK or later, a suite that builds today, and a browser. Two questions decide whether the rest of this is for you.

Does any part of your suite run outside Chromium and Firefox? Motus drives Chromium, including Chrome and Edge, over the Chrome DevTools Protocol, and Firefox over WebDriver BiDi. That is the whole list.

Do you live in Playwright's trace viewer? Motus writes its own trace zip and it opens in motus trace show, nowhere else. The two formats do not interoperate, and they were never meant to.

If both answers are no, everything below is mechanical.

What sits between you and the browser

Here is the starting position, in the migration guide's own words: Playwright for .NET "ships a bundled Node.js process (playwright.ps1 / playwright) that acts as the automation server; your .NET process talks to it over a named-pipe IPC channel". Motus has no sidecar. Your process holds the browser's WebSocket and speaks the protocol itself.

That takes the playwright install step out of your build and the Node.js runtime off your machine image. It also means the wire is something you can read: every command is a CDP or BiDi message, not a translation of one.

Step 1: swap the packages

Nothing clever here.

dotnet remove package Microsoft.Playwright
dotnet remove package Microsoft.Playwright.MSTest
dotnet add package Motus
dotnet add package Motus.Testing.MSTest
dotnet add package Motus.Analyzers

Then delete any playwright install or playwright.ps1 install line from your build scripts, and install a browser the Motus way, once per machine.

dotnet tool install --global Motus.Cli
motus install

motus install pulls a Chrome for Testing build into ~/.motus/browsers. In CI, pin it with a dotted version, motus install --revision 149.0.7827.156, so a moving stable channel cannot quietly change what your suite ran against.

Step 2: fix the using directives

Four namespaces where you had two.

// Before
using Microsoft.Playwright;
using Microsoft.Playwright.MSTest;

// After
using Motus;
using Motus.Abstractions;
using Motus.Assertions;
using Motus.Testing.MSTest;

Step 3: replace the launch call

There is no object sitting between startup and the browser, so Playwright.CreateAsync() has nothing to map onto. It just goes away.

// Before
var playwright = await Playwright.CreateAsync();
var browser = await playwright.Chromium.LaunchAsync(new() { Headless = true });

// After
var browser = await MotusLauncher.LaunchAsync(new LaunchOptions { Headless = true });

Firefox is a channel rather than its own entry point: new LaunchOptions { Channel = BrowserChannel.Firefox }.

Step 4: the assertions

This is the one project-wide replacement, Expect( to Expect.That(. The method names and what they mean are unchanged, so nothing else on an assertion line moves.

await Expect.That(page).ToHaveTitleAsync("Example Domain");
await Expect.That(page.GetByRole("button", "Submit")).ToBeVisibleAsync();

Step 5: the test base class

Swap PageTest for MotusTestBase, then add the assembly hooks that launch the shared browser.

[TestClass]
public static class AssemblySetup
{
    [AssemblyInitialize]
    public static async Task Init(TestContext _) => await MotusTestBase.LaunchBrowserAsync();

    [AssemblyCleanup]
    public static async Task Cleanup() => await MotusTestBase.CloseBrowserAsync();
}

[TestClass]
public class HomePageTests : MotusTestBase
{
    [TestMethod]
    public async Task TitleIsCorrectAsync()
    {
        await Page.GotoAsync("https://example.com");
        await Expect.That(Page).ToHaveTitleAsync("Example Domain");
    }
}

Motus shares one browser process across the whole test assembly and hands each test its own context and page, so you can leave [Parallelize] alone. NUnit uses the same MotusTestBase, with one BrowserFixture per fixture class. xUnit is put together differently: decorate the class with [Collection(nameof(MotusCollection))] and take SharedBrowserFixture through the constructor.

The mapping table

These rows come from the migration guide, which maps every surface in full. These are the ones you will hit most.

Four of those need a hand edit rather than a rename. Options objects flatten into positional parameters, so new() { Name = name } becomes a second argument. AriaRole enum values become plain role strings. FrameLocator has no Motus type at all, so take an IFrame out of page.Frames and call the same locator factories on it. And Playwright's two connect methods collapse into one ConnectAsync that accepts either a WebSocket URL or an HTTP debugging endpoint.

Step 6: configuration

playwright.config.ts becomes motus.config.json, read from the working directory or from the path in MOTUS_CONFIG. It is sectioned rather than flat.

{
  "launch": { "headless": true, "timeout": 30000 },
  "context": { "viewport": { "width": 1280, "height": 720 } },
  "assertions": { "timeout": 5000 }
}

Settings layer file first, then MOTUS_* environment variables, then code. LaunchOptions and ContextOptions passed at a call site always win, which is the rule to remember the day a value refuses to change.

What has no equivalent

Better you read this now than find it in week three.

Browser engines beyond Chromium and Firefox. There is no third transport. If part of your matrix runs somewhere else, that part is staying where it is.

The Playwright trace format and its viewer. Motus traces are their own zip layout, opened by motus trace show. Tooling built on Playwright's trace files will not read them.

Firefox parity with Chromium. Tracing, network interception, emulation overrides, security overrides, target multiplexing, the accessibility tree and code coverage are CDP-only. On Firefox those calls throw a NotSupportedException that names the feature and the transport, so you find out loudly rather than quietly. Locators, actions, assertions and script evaluation all work there.

Attaching to a Firefox endpoint. ConnectAsync builds a CDP transport unconditionally, so attaching is a Chromium-only path.

Packages built on Playwright. Anything in that ecosystem stops applying, and accessibility auditing is the one that stings: the guide notes that "Playwright delegates accessibility auditing to the separate axe-playwright ecosystem package". Motus has nine WCAG rules in the box and no extra dependency. Nine rules are not a replacement for a full audit library, and I am not going to pretend they are.

What you get in exchange: those audits and Core Web Vitals budgets without a second package, seven compile-time diagnostics from Motus.Analyzers, an extension model written in .NET instead of injected JavaScript ("Playwright's extensibility is limited to JavaScript-side selector engines and browser context options; Motus hooks are pure .NET"), and attaching to a browser you did not start.

Step 7: build, run, triage

dotnet build
motus run bin/Release/net8.0/MyTests.dll --reporter console

With Motus.Analyzers referenced, the build itself catches the common leftovers: a call you forgot to await, a browser not disposed with await using, a navigation with nothing waiting after it. Three of the seven diagnostics ship a code fix with Fix All.

So where a test asserts against something that renders later, wait for it first.

await Expect.That(page.GetByRole("dialog")).ToBeAttachedAsync();
await Expect.That(page.GetByRole("dialog")).ToBeVisibleAsync();

Then check the selectors themselves, which is the other thing a port tends to disturb.

motus check-selectors "tests/**/*.cs" --manifest tests.selectors.json --ci

The full mapping lives in the migration guide, the fixture shapes for all three frameworks in testing frameworks, and the whole config schema in configuration. If you hit a surface the mapping table does not cover, that is the issue I want to see.

The reading half is where notebook workflows pick up a service: somewhere to upload to, an export step, a copy that drifts from the file the moment you commit again. Our answer is an edit to the address bar.

Take the address of a notebook in a public repository:

https://github.com/DataficationSDK/Verso/blob/main/samples/showcase/slide-studio/slide-studio.verso

Change the host to www.versonotebooks.com/share/github:

https://www.versonotebooks.com/share/github/DataficationSDK/Verso/blob/main/samples/showcase/slide-studio/slide-studio.verso

That link opens the notebook as a page: its prose, its code, and the outputs the file was saved with, which here is a table of regional numbers, a bar chart, and a printed summary line. Everything after the host is untouched, so you can make the change in the address bar without looking anything up. If you would rather paste than edit, the share page has a box that does the swap.

GitLab and gists follow the same shape:

https://gitlab.com/group/project/-/blob/main/analysis.verso
https://www.versonotebooks.com/share/gitlab/group/project/blob/main/analysis.verso

https://gist.github.com/user/2b1f0c9e4a
https://www.versonotebooks.com/share/gist/user/2b1f0c9e4a/analysis.verso

GitLab projects nested several groups deep work as written. A gist needs the file name on the end, because it can hold more than one file.

What the page does, and what it will not do

Nothing is uploaded. There is no copy of your notebook on our side to go stale, because the page is built from the file already in your repository. Commit a change and the link shows it.

Nothing is executed, on the page or anywhere else. The notebook renders as a document, in a sandbox with no access to the site around it. A cell that expects a live kernel shows only what it last saved, and a reader who wants to run it downloads the file.

Which means the page shows whatever the file already contains. A notebook saved with its outputs shows its charts, tables, images, and diagrams. One committed after clearing outputs shows the code alone. Worth knowing before you paste a link into a review: strip outputs before committing and the reader gets source and nothing else.

Three formats, no conversion step

The Jupyter row is the one that surprises people. There is no convert-then-share step: point a share link at an .ipynb in a public repository and it reads.

The Markdown rule is the one the editor uses. Prose stays prose, and a top-level fenced block tagged with a language Verso knows becomes a cell of that language, so a shared .md is cut into the same cells you see in the editor. A bare fence, or one tagged with a language Verso does not run, stays prose.

Relative links and images keep working

A markdown cell that says ![](figs/genome.png) is asking for the file beside it in your repository, and that is where the page fetches it from, so a notebook that leans on a folder of figures reads the same here as at home. Relative links work the same way: one pointing at another notebook, or at a Markdown or Jupyter file, opens as a page here rather than on the forge, so you can read a folder of notebooks straight through. Everything else opens on the forge, and a full address is left exactly as you wrote it. Every page carries a View source button.

The catch is the obvious one. Those files have to be public too. A figure in a private repository is no more reachable than the notebook would be.

A link that keeps showing what it showed

A link to a branch shows whatever that branch holds today, which is what you want in a README. A link that has to keep showing the same thing, in a paper or an issue thread, should name a commit instead:

https://www.versonotebooks.com/share/github/owner/repo/blob/9f2c1ab.../analysis.verso

GitHub writes that link for you: press y while viewing the file and the address bar swaps the branch name for the commit it points at. Copy it then, and the link keeps showing what it showed the day you shared it.

A badge, and a link preview

Every shared page offers the markdown for a badge, ready to paste into a README beside the notebook:

[![Open in Verso](https://www.versonotebooks.com/share/assets/open-in-verso.svg)](https://www.versonotebooks.com/share/github/owner/repo/blob/main/analysis.verso)

Share links also carry the notebook's title and opening paragraph as page metadata, so pasting one into Slack, Discord, or a social post produces a card describing the notebook. The title comes from the notebook's own when it has one, otherwise from the file name.

Why we built it this way

The alternatives all involve a copy. Export to HTML and the copy is stale the next time you run the notebook. Upload to a service and the copy lives somewhere else, with its own permissions and its own account to keep.

A URL that names the file in your repository makes nothing. It is a view, in the database sense: nothing to keep in sync, nothing to revoke, nothing to migrate when the repository moves. The link breaks when the file moves, which is what you want from a pointer.

The quickest way to find out whether it suits your repository is to open a notebook on GitHub, edit the host, and press Enter. The Sharing a Notebook guide covers every URL form, and it went out alongside the 1.2 releases.

What changed

Widgets that are still connected

Drag a slider in a Python cell and the Python that made it hears about it, runs whatever the author wired to it, and can send something back, within a cell and across cells. That holds for ipywidgets and for anything built with anywidget, because Python cells run in a separate host process that is still there after the cell finishes.

A widget with no interpreter behind it, because you just opened the file or restarted its kernel, draws visibly inert with a note to run the cell. Saving asks each live widget for its state, so the file records what you were looking at rather than what the cell first drew.

Three ceilings apply, and each refuses with a diagnostic rather than going quiet: 4 MB for a widget's saved page, 8 MB for one message between a widget and its kernel, 1 MB for one projected value. The state travels in the notebook, but the JavaScript that draws it comes from a public CDN, so a machine with no network draws an empty frame.

A control in front of another language

#!bind takes a trait on any object in the Python interpreter and makes it an ordinary shared variable.

import ipywidgets as widgets

slider = widgets.IntSlider(value=20, min=0, max=100, description="Threshold")
slider

#!bind slider.value as threshold

var cutoff = Variables.Get<long>("threshold");
readings.Where(r => r > cutoff)

Variables.Set("threshold", 70L) from a C# cell moves the slider and fires the author's observe callbacks. #!bind --list shows every trait currently projected, and #!bind --remove <name> stops one following its widget without deleting the variable.

Two limits. A trait holding another widget is refused, layout and style being the ones people try first, so bind one of that widget's own traits instead. And a projection lasts as long as the interpreter: restart Python and the name keeps the value it last had, until you re-run the #!bind line.

Reactive execution, as a package

The new DAG Notebook showcase layout, published as Verso.Showcase.DagNotebook, scans each code cell for the variables it defines and the names it reads, draws chips linking producers to consumers, and runs a finished cell's dependents in dependency order. A bound control at the top of the graph cascades a run with nothing else clicked.

The scan is a heuristic rather than a proof, and the layout is honest about it: a variable written by more than one cell gets a warning chip and no edges, and cycle edges are excluded, so a cascade cannot loop. What I like most is that it is a package. Reactive execution is usually a property of the notebook tool you picked, and here it arrives as an extension.

Panels beside the notebook

An extension can now contribute a panel beside the notebook body by implementing INotebookPanel, toggled from the toolbar next to Verso's own Metadata, Extensions, Variables, Settings, and Cell Properties. A panel describes its content rather than drawing it, so it works on every host, including one that never touches a browser.

Five languages

The interface ships in German, Spanish, Japanese, and Simplified Chinese alongside English, covering the notebook UI, the toolbar and panels, the kernel messages that land in cell output, and the command line tool. Choose one with --language or the verso.language setting. With neither, Verso follows VERSO_LANGUAGE, then the operating system's language, then English. verso serve negotiates per browser from Accept-Language.

Numbers, dates, and currency keep the machine's own formatting whichever language you choose, because translating those would change what a cell computes.

From the community

A kernel can now hand a value to registered formatter extensions before its own rendering, through a new IExecutionContext.TryFormatAsync. PowerShell is the first kernel wired to it, contributed by @eosfor (#93), who also sent two PowerShell samples that build an automatic differentiation engine from scratch and run it on handwritten digits (#92).

Native libraries now resolve to a package's own copy in preference to a same-named library elsewhere on the system, and against the running process's architecture and C library rather than the machine's. That fixes a class of failure where a plotting library died on a version mismatch it had nothing to do with, found and diagnosed by @oxygen-dioxide (#91).

Upgrade notes

Code written after #!import in the same cell now runs. Everything below the directive used to be discarded silently, so a cell with boilerplate under an import will execute it for the first time on this release.

An extension built against Verso.Abstractions 1.2 needs a 1.2 or newer host. A host accepts an extension whose referenced minor version is at or below its own, and patch versions are never compared, which is why extensions kept loading across the 1.1 series.

Formatter extensions should check context.MimeType in CanFormat. Both new interface members have defaults, so nothing fails to compile, but a formatter that claims a value it cannot render in the requested MIME type is now stepped over.

Getting it

dotnet tool update -g Verso.Cli
code --install-extension Datafication.verso-notebook
dotnet add package Verso

The new Interactive Widgets guide covers #!bind and what separates a live widget from a static one, and Panels covers writing one. If a widget you rely on does not come back to life the way you expect, that is the report I want.

Verso's answer, since 1.1.3, is the one you already have. Python cells run against a CPython installation on your machine, 3.8 or newer, in a separate process that Verso starts and supervises. We do not embed a Python of our own and we do not bundle one, so a cell sees the interpreter, virtual environment, and packages you would get from a terminal.

That sounds like a packaging detail, and it is the reason for everything else here. Running Python outside the notebook process is what lets you interrupt a cell, survive a native crash, and get a restart that genuinely clears imported module state.

A separate process, on purpose

Verso starts the host and talks to it over a loopback connection. Completions and hover are computed in that same process, so the interpreter that runs your code is the one that answers questions about it.

A restart clears the variables from earlier Python cells, but not values other languages shared into the notebook's variable store, because the store lives on the notebook's side of that boundary. It also takes with it anything the interpreter started, so a background shell command ends there rather than outliving it.

Which interpreter you get

Verso goes looking the first time a Python cell runs, and takes the first candidate that validates.

A candidate has to answer a version probe and report CPython 3.8 or newer, so a broken entry near the top of the list does not stop a working one further down from being found, and if nothing validates the cell tells you what it searched. Activation is read from the environment, so activating a virtual environment before you launch your editor is usually the whole configuration step.

#!python reports the interpreter in use, its version, what kind of environment it is, and which source selected it. #!python --list shows every interpreter that was discovered and where each was found. #!python /usr/local/bin/python3.13 selects one and restarts the kernel.

A selection like that lasts for the session and is never written into the notebook file, because an absolute path is only true on the machine that produced it. To pin an interpreter for a run instead, verso run, verso serve, and verso repl all take --python <path>.

Packages land in that same interpreter

Because the cell runs in your interpreter, an install lands there too, and the import on the next line finds it without a restart.

#!pip requests pandas>=2
import requests

#!pip runs before the rest of the cell and takes the same package specifiers and options pip does. If uv is on your PATH, Verso uses it. Both installers list every dependency they touch, so the cell reports a summary instead and saves that with the notebook. A failed install always prints in full, since that output is the only account of why it failed.

The second route is the import itself. A cell that imports something the environment does not have raises a "Package Install Required" dialog naming the distribution, the import that asked for it, and the interpreter it would go into. The distribution name is often not the import name, so import cv2 offers opencv-python, import PIL offers Pillow, and import sklearn offers scikit-learn. Decline and the cell runs anyway, failing at the import as it would have without the offer. An import wrapped in try is never installed: that cell has already said it can run without the module.

Guessing means falling back to the import name as the distribution name, and that is the case to be careful about: a typo like import pandsa produces a plausible package name somebody may well have published. It is also why the command line differs from the editor, which matters if you run the same notebook in CI that you run at your desk.

The third route is declaring requirements once, either in the Python kernel's Dependencies setting or inline at the top of the first cell you run, using the standard script metadata format. Those travel with the file, so a declared requirement may only name a package. An installer option such as --index-url, or a location to install from such as a URL or a filesystem path, is reported rather than installed. Where code gets fetched from is a decision for whoever runs the notebook, not for the file they opened.

Some interpreters, particularly ones from a Linux distribution's package manager, mark themselves externally managed, and pip refuses to install into them. Verso detects that and derives a small environment from the interpreter with access to its existing packages. It never does that to a virtual environment, which is yours to install into.

Widgets draw

Libraries that render only as ipywidgets models hand the notebook a reference rather than a picture, which is why a cell ending in plot.display() used to print a model description. Those now draw: k3d, ipyleaflet, pythreejs, bqplot, and ipyvolume among them, as does anything built with anywidget.

import k3d
import numpy as np

plot = k3d.plot()
plot += k3d.points(np.random.randn(5000, 3).astype(np.float32), point_size=0.03)
plot.display()

The widget gets an auto-resized frame of its own, with theme tokens injected into it so it follows the host theme. Its state is saved with the notebook, so reopening the file draws it again without running the cell.

Two things to watch for. The state travels in the notebook, but the JavaScript that draws it comes from a public CDN, so a machine with no network draws an empty frame. And state has a size: a five thousand point scatter adds roughly 90 KB each time the cell is run and saved.

Next to a Jupyter kernel

Jupyter's own documentation describes a model worth putting beside this one: kernels there are "programming language specific processes that run independently", and an open notebook "has exactly one interactive session connected to a kernel". The nbformat specification records that choice in the file, as a single kernelspec in notebook metadata.

The difference is where the choices live. Verso's Python process is one of eight kernels reading and writing one variable store, so a value set in C# is readable in Python with no hand-off. And the interpreter is picked per session and per machine, never saved into the file.

Two notes if you are upgrading

Python cells now need CPython 3.8 or newer installed on the machine. Where none is found, a Python cell reports what it searched instead of failing silently.

PythonKernelOptions.PythonDll is ignored. The property remains, so nothing fails to compile, and a session that sets it says once that it has no effect.

Point a cell at the environment you already have and see whether it picks the interpreter you expected. If it does not, #!python --list will show you why. The rest is in the Python Interpreters and Python Packages guides.

What changed

A browser you already have running

Sometimes the browser you want to drive is already open. You signed into a profile by hand, or CI keeps a warm browser between runs, or the thing you are testing is an application built on an embedded Chromium runtime that exposes a debugging port. Until now Motus had to start its own.

ConnectAsync takes the CDP WebSocket URL or the HTTP debugging endpoint, and comes back once it has adopted the contexts and pages that were already open.

await using IBrowser browser = await MotusLauncher.ConnectAsync("http://127.0.0.1:9222");

foreach (IBrowserContext context in browser.Contexts)
foreach (IPage page in context.Pages)
    Console.WriteLine($"{await page.TitleAsync()} - {page.Url}");

Anything that opens or closes after that gets tracked too, so a long session keeps up instead of describing the moment you connected. ConnectOptions carries AdoptExistingTargets, SlowMo and a Timeout that bounds the connect itself.

One limit worth knowing up front: ConnectAsync speaks the Chrome DevTools Protocol, so the endpoint has to be a Chromium one.

Ownership is something you can check. On a browser you attached to, CloseAsync closes the contexts Motus created and disconnects, and leaves the process running. OwnsProcess tells you which case you are in. The attach guide is blunt about the security side: attaching is the same as sitting down at the machine, and there is no narrower permission to hand out.

Frames the browser puts in their own process

If you have ever fought a cross-origin iframe, you know the browser renders it in a separate process, which gives it its own protocol target, session and execution contexts. Motus now handles that for you. A frame like that is an ordinary IFrame in page.Frames, at any depth, and locators, clicks, evaluation and navigation all go to the session that owns it.

IFrame.EvaluateAsync also picked up an overload that chooses the frame's main world or an isolated one. The main world is still the default, and the trap here runs the other way from what you would expect: an isolated world shares the document and nothing else, so reading a framework handle off window there comes back undefined, which looks exactly like an application that never loaded.

Splitting a suite and putting it back together

If a suite takes too long on one agent, you want it on four. Splitting it is the easy half. Trusting the merged result is the hard half.

motus run bin/Release/net8.0/MyTests.dll --shard 1/4 --reporter junit:results.shard-1.xml
motus shard merge results.shard-*.xml --output junit:results.xml --expect 4

Each shard works out its own slice from the sorted test set and its shard coordinates, so no agent has to coordinate with any other. Two things to watch. Shards balance by count, not by how long a test takes, so a suite dominated by one slow test is not rescued by adding agents. And a shard that never ran leaves you a smaller report that is entirely green, which is the failure --expect exists to catch: every shard stamps its coordinates into its result file, and the merge fails when an index is missing or shows up twice.

A flaky test is not a broken one

Retries have a bad reputation because they usually hide something. These try not to.

--retry-policy transient is the default, and it only re-runs a failure caused by the browser disconnecting. flake re-runs any failure, and a test that passes on the second try is reported as flaky rather than green. A flaky test still passes the run with a warning unless you say --fail-on-flaky. For the ones you already know about, [Quarantine] keeps a test running and reported without gating the build, --quarantine <file> does the same from a list of names, and --flaky-history <file> turns one bad morning into a trend you can look at.

Behavior changes

Seven of them, and each is here because it would otherwise read as a regression.

Getting it

dotnet add package Motus
dotnet tool install --global Motus.Cli
motus install

All ten packages are at 1.0.15 on nuget.org. There are new guides for attaching, frames, sharding and flaky tests, plus a CLI reference. If you drive Motus from an agent, motus mcp --connect starts the server already attached, and the MCP walk-through covers the rest. Try attach mode against something you already have running, and tell me what surprises you.

Fair warning, this is an advanced scenario. If what you want is a notebook, use the notebook. This guide is for the case where a notebook runtime belongs inside something else: a rules engine that has to evaluate user-authored expressions, an internal tool that reports on data using code its users write, a test harness that executes documented examples.

Before you start

You need .NET 8 or later and one package:

dotnet add package Verso

That is the engine, and it is not the editor. The Razor components live in a separate assembly and none of them come along for the ride.

The parts

Scaffold is the session. It owns the in-memory notebook model, the kernel registry, execution dispatch, and the theme, layout, and settings subsystems. ExtensionHost finds and loads extensions, and that is where the kernels come from in the first place, so the two always show up together.

A complete program

Here is the whole thing. Read it once, then I will walk back through the parts that are easy to get wrong.

using Verso;
using Verso.Abstractions;
using Verso.Extensions;

// 1. Load the built-ins: kernels, themes, layouts, formatters.
var extensionHost = new ExtensionHost();
await extensionHost.LoadBuiltInExtensionsAsync();

// 2. Open a session over a blank notebook.
var scaffold = new Scaffold(new NotebookModel(), extensionHost, filePath: null);

// 3. Subsystems come after the extensions are loaded, never before.
scaffold.InitializeSubsystems();

// 4. Whatever the host sets is visible to every kernel.
scaffold.Variables.Set("threshold", 0.95);

// 5. Run code that never becomes a cell.
var outputs = await scaffold.ExecuteCodeCaptureOutputsAsync("1 + 41", language: "csharp");
foreach (var output in outputs)
    Console.WriteLine(output.Content);

// 6. Or build a real notebook and watch it run.
scaffold.OnCellExecuted += cellId =>
{
    var cell = scaffold.GetCell(cellId);
    Console.WriteLine($"{cell?.Language}: {cell?.LastStatus} in {cell?.LastElapsed}");
};

scaffold.AddCell("code", language: "csharp", source: "var score = 0.97;");
scaffold.AddCell("code", language: "csharp",
    source: "score > Variables.Get<double>(\"threshold\")");

await scaffold.ExecuteAllAsync();

await scaffold.DisposeAsync();

That is the whole surface for a first program. Everything below is what each step is doing.

Why the order matters

InitializeSubsystems() asks the extension host for themes, layouts, and settable extensions, and builds the subsystems out of what it finds. Call it before the extensions are loaded and it builds them out of nothing. Call it after, the way step 3 does, and it also subscribes to the host's load and status events, so the subsystems refresh on their own when an extension is added or toggled later.

Until you call it, the ThemeEngine, LayoutManager, and SettingsManager properties are null. That is usually the first surprise.

Three ways to execute

ExecuteCodeCaptureOutputsAsync(code, language) runs a string and hands back its outputs. Nothing is added to the notebook. This is the one to reach for when the notebook model is an implementation detail and all you want out of the engine is an evaluator.

AddCell plus ExecuteAllAsync() is a real notebook run. ExecuteAllAsync resets the kernels first, so a full run behaves as though the file had just been opened.

ExecuteCellAsync(cellId) runs one cell without resetting anything, which is what an editor does when you press Run on a single cell. Both of the cell methods also return ExecutionResult values directly, which is simpler than subscribing when you only care about the call you just made.

One store, every language

Every kernel in the session reads and writes the same variable store, and your host code reads and writes it too:

scaffold.Variables.Set("threshold", 0.95);
var back = scaffold.Variables.Get<double>("threshold");

There is no per-kernel isolation, and that is the point of the thing. A value your application sets before a run is a plain variable inside a C# cell, and the same name is readable from Python or SQL in the same session.

The built-in C# kernel is in the Verso package. Other languages arrive as their own packages, and because LoadBuiltInExtensionsAsync also scans assemblies sitting beside yours that reference Verso.Abstractions, adding one is a package reference and nothing else:

dotnet add package Verso.FSharp
dotnet add package Verso.Ado

Watching it happen

Subscribe when you need to drive progress in your own UI. The cell events carry only the cell's id, so look the cell up and read what was stamped on it:

The kernel events carry the language name rather than a cell id, because a restart is not about any one cell.

Loading somebody else's extension

await extensionHost.LoadFromAssemblyAsync("./MyExtension.dll");

A third-party assembly loads into a collectible AssemblyLoadContext that isolates its dependencies while handing it the host's own Verso.Abstractions types, so the interfaces match. Built-ins load into the default context instead, since they ship alongside the host.

Cleaning up

Scaffold is IAsyncDisposable. Disposing it disposes every registered kernel, clears the internal registries, and disposes the extension host, which unloads the extensions.

In a long-lived process, dispose per session rather than holding one open forever. Kernels hold compiler state and, for some languages, a separate process, so a session nobody closes is a session that never hands any of that back.

Where the engine stops

The boundary between the engine and a user interface is INotebookService, and it lives in Verso.Blazor.Shared, not in the engine. The browser host implements it in process, the VS Code host implements it over JSON-RPC, and the CLI's headless runner does not implement it at all: it drives Scaffold directly with no UI boundary. If you are embedding, you are in the third position.

Two host capabilities are worth knowing about, because kernels ask for them through public abstractions. WriteOutputAsync streams an output while a cell is still running, which is how PowerShell's host writes reach a cell before it finishes. RequestInputAsync asks for a single value from the user, which is how Read-Host works in the editor. A host that does not support them keeps the default behavior, which throws NotSupportedException, and kernels are written to treat both as optional, so implement them when your front end can and skip them when it cannot.

If the last release put layouts and a marketplace in reach of an extension author, this is the same engine pointed the other way, with your application as the front end. Build something on it and tell me where the API fights you.

What changed

Two ways to draw a layout

A layout decides what a notebook looks like when you open it, and there are two ways to build one.

An inline layout writes the arrangement and hands it to the host, and the host drops your real cells into the places the layout marked for them. Those are live cells: they still execute, still stream output, still edit. You write the arrangement, the host keeps the cells.

An isolated layout ships a JavaScript bundle that the host runs in a sandboxed frame. It draws its own content, keeps its own DOM and CSS, and has no network inside the frame, so anything it needs fetched gets fetched kernel side.

The trade is isolation against reuse. Inline is C# only, inherits the host CSS, and keeps the host's cells. Isolated needs a bundle and gets a clean room. Toolbars and grids usually want the first, visualizations and custom editors the second.

Either way, interactions come back through the same handler, so your code does not need to know which mode drew the screen. Both also take their colors from the host's CSS variables instead of asking what the theme is, which is why a layout recolors correctly in the browser and in VS Code alike.

A marketplace that is just NuGet

The Extensions panel now has a search box above the extensions you have loaded. Type a package name, pick a version, install. There is no Verso feed behind it: the search runs against the NuGet sources configured on the machine, private ones included. Packages unpack one folder per version into ~/.verso/extensions/<package-id>/<version>/ or %APPDATA%\verso\extensions\<package-id>\<version>\.

An extension is executable code, so the first load asks you. Trust is pinned to the exact version you approved, which means a notebook asking for a different version prompts again instead of quietly trusting the new build.

A notebook can declare what it needs:

"metadata": {
  "extensions": {
    "required": ["Contoso.Verso.ChartLayout@1.2.0"],
    "optional": []
  }
}

Those load before the notebook renders, so a layout the file depends on is there on the first paint. If one cannot be found or approved, the notebook still opens, with a notice, and falls back to a built-in layout. The on/off toggle beside a loaded extension stays local and does not travel with the file.

Three layouts that prove the API

We published three of them, each referencing Verso.Abstractions and nothing else, each isolated:

• Grid Studio (Verso.Showcase.GridStudio) shows a kernel DataBlock as an editable spreadsheet and commits every edit back to the same variable with the column types preserved. A System.Data.DataTable, such as a shared SQL result, renders read-only on purpose. Bundles Jspreadsheet CE (MIT).
• Form Studio (Verso.Showcase.FormStudio) is a dashboard you build by dragging. Sliders, dropdowns, toggles, and charts drop onto a canvas, each input writes a kernel variable by name, and with auto-run on the notebook recomputes and pushes fresh data back. Charts are Chart.js (MIT).
• Image Studio (Verso.Showcase.ImageStudio) turns the same file into a layered image compositor. A procedural layer hands its drawing off to a kernel variable, so re-running a code cell repaints it. Bundles nothing.

They make the point from if a built-in feature needs a private API: the built-in Notebook, Dashboard, and Presentation layouts run on the same interfaces.

Getting it

dotnet tool update -g Verso.Cli
code --install-extension Datafication.verso-notebook
dotnet add package Verso

If you write extensions, the template has a new switch. dotnet new verso-extension --includeLayout scaffolds an inline layout with cell slots, interaction routing, metadata persistence, and themed CSS.

Also in 1.1.1: export moved to an icon-only toolbar behind a per-host download that works from inside an isolated frame, and publishing Python variables with cyclic or deeply nested structures no longer crashes the host.

Thanks to @fluentfoundation and @fiVISION for sponsoring this work. The full notes are on the release notes page. Build a layout, and if the API will not let you do something you expected, that is the report I most want to see.

Start with what you do not install. There is no Motus.Mcp package on NuGet. The server is a verb on the CLI tool: motus mcp.

Install and register

dotnet tool install --global Motus.Cli
motus install
claude mcp add motus -- motus mcp

Everything after -- is the command the client runs, so server options go there too: claude mcp add motus -- motus mcp --channel chrome.

Clients that read a JSON configuration file, Claude Desktop among them, take the same command and arguments under an mcpServers map:

{
  "mcpServers": {
    "motus": {
      "command": "motus",
      "args": ["mcp"]
    }
  }
}

If the client tells you the server failed to connect, the usual cause is that motus is not on the PATH the client inherits. Check with which motus, which should print something like ~/.dotnet/tools/motus. If it prints nothing, stop depending on PATH and give the absolute path instead, either as command in the JSON above or on the command line:

claude mcp add motus -- "$HOME/.dotnet/tools/motus" mcp

You will not find a start-session tool, and you do not need one. The browser and a "default" context are created lazily, on the first call that needs a page.

What the agent actually sees

snapshot returns the browser's accessibility tree as indented text. Two spaces per level, one line per node, and a ref on every node that maps to a real DOM node. Refs are e1, e2 and so on, assigned in document order.

- RootWebArea "Sign in" [ref=e1]
  - navigation [ref=e2]
    - button "Sign in" [ref=e3]
  - form [ref=e4]
    - textbox "Email" [ref=e5]
    - textbox "Password" [ref=e6]
    - button "Sign in" [ref=e7]

State follows the ref in brackets: [value="..."], then any of disabled, readonly, required, checked, selected, expanded, pressed. The interaction tools take the ref, not a selector:

type(ref: "e5", text: "ada@example.com")
type(ref: "e6", text: "hunter2", submit: true)

Refs belong to the latest snapshot. Use a stale one and you get back an error result that carries the fix, rather than a protocol failure: Ref 'e5' is not in the latest snapshot. Call snapshot to refresh refs, then retry. An agent reads that and re-snapshots on its own. This is why perception here is a tree rather than a picture. A screenshot shows an agent what a page looks like; a snapshot gives it something it can address.

The 51 tools

When the tree has nothing to point at

A page that paints to a <canvas> gives the accessibility tree nothing to describe. Rather than let an agent decide the page is empty, snapshot says so and names the way out: take a screenshot, find the control visually, then act on its position.

click_xy, hover_xy, move_xy, scroll_xy and drag take CSS pixels in the viewport, the same space screenshots and getBoundingClientRect() report. resize changes the viewport when a target sits past its edge. The session default is 1280x800, and --viewport WIDTHxHEIGHT changes it at launch.

I want to be honest about what you give up here. There is no element resolution and no actionability check. Input is still dispatched as trusted browser-level events, so frameworks that ignore synthetic JavaScript events respond to it, but the browser's own hit test decides what receives the event. An overlay with pointer-events: none gets passed through; an overlay that accepts pointer events takes the click instead of your target. drag accepts refs (start_ref, end_ref) or coordinates, one addressing mode per call, and it always emits intermediate moves, with steps and hold_ms for libraries that threshold a drag start.

The parts that come from a test framework

Three tools are here because the engine underneath is a test framework rather than a driver.

audit_accessibility runs Motus's nine built-in WCAG 2.1 A and AA rules against the browser's accessibility tree, and takes min_severity if you want to filter. get_performance returns the Core Web Vitals the suite asserts on: LCP, FCP, TTFB, CLS and INP, plus JS heap size and DOM node count. Both report exactly what a test would, so an agent's finding and a CI failure are the same measurement rather than two things you have to reconcile.

generate_pom closes the loop with the recorder and code generator. It analyzes the page the agent just explored and hands back a C# Page Object Model class inline, with namespace and class_name optional. That turns an exploration into a test instead of a transcript, which is the whole reason I wanted it in the server.

For evidence, trace_start and trace_stop, har_start and har_stop, and video_start and video_stop all follow one convention: stopping finalizes the file and returns its path, and if you leave the path out, one is generated under the temporary directory. Video is MJPEG in an AVI container, written without an external dependency, captured at viewport resolution, and no mouse cursor shows up in it. Convert it with ffmpeg -i in.avi -c:v libx264 out.mp4 when you need another format. If you would rather record everything, --record-video <dir> captures every page for its whole life, and in that mode video_start reports an error because the page is already recording.

Serving it to a team

The same tools run over Streamable HTTP, which is the transport for remote clients. It is not SSE.

# loopback only, no token needed
motus mcp --http

# reachable from other machines: a non-loopback bind requires a token
motus mcp --http --host 0.0.0.0 --port 8931 --token "$MOTUS_MCP_TOKEN"

Each connected client gets its own session with its own browser, and a session that sits idle for thirty minutes is torn down along with the browser it holds. Binding a non-loopback host without a token is refused at startup rather than warned about, and when a token is set every request is compared against it in constant time. stdio inherits the trust of whoever launched it and needs no token. HTTP does not inherit anything, so treat that token like a credential.

Worth knowing before you start

The tools are registered by hand rather than found by scanning, which keeps reflection out of schema generation. The server targets net8.0 and net10.0 and rolls forward, so a machine carrying only the .NET 10 runtime runs it fine.

Firefox is available through --channel firefox, but not all of this is. Tracing, network interception and the accessibility tree are Chrome DevTools Protocol capabilities, so the tools built on them return a diagnostic instead of a result on a Firefox session. Drive Chromium unless Firefox is the thing you are testing.

The MCP server guide has the full option table, and the site publishes a machine-readable index of every documentation page at llms.txt for an agent that would rather read the manual itself. Point a client at it, give it a page you know well, and tell me where the snapshot let you down.

Motus 1.0.10 closes the loop. The recorder and the code generator now write a selector manifest beside the code they emit, and motus check-selectors reads it, checks every selector against a live page, and rewrites the broken ones it is sure about.

Before you start

You need the .NET 8 SDK or later, a test project, and the CLI. One thing to get right up front: the verb is motus, never dotnet motus.

dotnet add package Motus
dotnet add package Motus.Testing.MSTest
dotnet tool install --global Motus.Cli
motus install

motus install pulls down a Chrome for Testing build into ~/.motus/browsers. Every example below drives an application on http://localhost:5000 that has a top bar and a sign-in form:

<nav class="topbar"><button class="link-btn">Sign in</button></nav>
<form>
  <input data-testid="email" type="email" aria-label="Email">
  <input data-testid="password" type="password" aria-label="Password">
  <button data-testid="sign-in" type="submit">Sign in</button>
</form>

Step 1: generate the page objects

Start with motus codegen. It loads a page, waits for the network to settle, crawls the DOM for interactive elements (inputs, buttons, selects, textareas, links with an href, and anything with role="button"), infers a selector for each one, and writes a partial class.

motus codegen http://localhost:5000/sign-in \
    --output tests/Pages \
    --namespace MyApp.Tests.Pages

The class name comes from the URL: host segments first, with www dropped, then path segments. So that command writes tests/Pages/LocalhostSignInPage.g.cs:

// <auto-generated/>
using Motus.Abstractions;

namespace MyApp.Tests.Pages;

public partial class LocalhostSignInPage
{
    private readonly IPage _page;

    public LocalhostSignInPage(IPage page) => _page = page;

    public Task NavigateAsync() => _page.GotoAsync("http://localhost:5000/sign-in");

    // Locators
    public ILocator EmailInput => _page.Locator("data-testid=email");
    public ILocator PasswordInput => _page.Locator("data-testid=password");
    public ILocator SignInButton => _page.Locator("data-testid=sign-in");

    // Form actions
    public async Task SubmitSignInFormAsync(string email, string password)
    {
        await EmailInput.FillAsync(email);
        await PasswordInput.FillAsync(password);
        await SignInButton.ClickAsync();
    }
}

Two things about that file. It is partial, so your own helpers live in a second file that regeneration never touches. And the property names come from the first of id, name, aria-label, placeholder and visible text that is actually set, plus a suffix for the kind of element. SubmitSignInFormAsync shows up only because the form holds a fillable input and a submit button.

If you cannot reach the page by URL, there are three ways in. --headed opens a visible browser and waits for you to press Enter. --connect ws://localhost:9222 analyzes what is already open in a browser you started yourself. And --scope "#login-form" limits discovery to a single container.

How a selector gets chosen

This part is worth a minute of your time, because it explains the code you get back. Inference walks the registered selector strategies in priority order and takes the first candidate that is at most 200 characters and resolves to exactly one node. These are the same ISelectorStrategy implementations the runtime uses, registered the way any other plugin is, so a custom strategy changes generation and resolution together.

In practice the ladder is test id, role, text, CSS. CSS sits ahead of XPath at the same priority and almost always succeeds, so XPath rarely wins. When nothing qualifies, the element comes out as a // TODO: comment instead of a guessed locator. I would rather hand you a gap you can see than a locator that looks fine and is not.

Step 2: record a scenario

motus record launches a headed browser, injects a recorder script that survives navigation, and turns your clicks, keystrokes and navigations into one line of C# each. There is no --headless option here, and --selector-priority is reserved on record: only codegen applies it.

motus record --url http://localhost:5000/ \
    --output tests/SignInFlow.cs \
    --namespace MyApp.Tests \
    --class-name SignInFlowTests \
    --method-name CanSignIn

Press Enter when you are done. Consecutive fills on one selector get coalesced into a single line:

        await page.GotoAsync("http://localhost:5000/");
        await page.Locator("css=nav.topbar > button.link-btn").ClickAsync();
        await page.GotoAsync("http://localhost:5000/sign-in");
        await page.Locator("data-testid=email").FillAsync("ada@example.com");

Look at the second line. The top bar button has no test id, and role=button[name="Sign in"] also matches the form's submit button, so inference falls all the way through to CSS. That line is now coupled to a class name, which is exactly the kind of thing that breaks later.

Step 3: the manifest

Both commands write a sidecar beside their output, here tests/SignInFlow.selectors.json. Each entry records the selector, the locator method, where it sits in your source, the URL it was captured on, and a fingerprint of the element.

{
  "entries": [
    {
      "selector": "css=nav.topbar > button.link-btn",
      "locatorMethod": "Locator",
      "sourceFile": "/work/app/tests/SignInFlow.cs",
      "sourceLine": 15,
      "pageUrl": "http://localhost:5000/",
      "fingerprint": {
        "tagName": "button",
        "keyAttributes": {},
        "visibleText": "Sign in",
        "ancestorPath": "html > body > nav",
        "hash": "8095124e9ec5e2dad1577e7fff57f70add38c2d933b2861ce27b4c01015bbd17"
      }
    }
  ]
}

keyAttributes holds only id, name, role, data-testid, aria-label, type and href, which is why it is empty for that button. ancestorPath is three levels of tag names, and hash is a SHA-256 over the four fields above it. Notice what is not in there: class names. Leaving them out is what lets a fingerprint outlive a restyling.

Step 4: check the selectors

motus check-selectors parses your C# with Roslyn, picks out the calls to Locator, GetByRole, GetByText, GetByTestId, GetByLabel, GetByPlaceholder, GetByAltText and GetByTitle, and resolves each one against a live page. The match count is the verdict.

--base-url points every selector at one page. With --manifest, each one is checked against the URL it was recorded on, which is the only way a multi-page flow checks correctly. Say the design system renames .topbar to .appbar and you run this:

motus check-selectors "tests/**/*.cs" --manifest tests/SignInFlow.selectors.json

STATUS     SELECTOR                                 FILE:LINE                           MATCHES
---------- ---------------------------------------- ----------------------------------- -------
BROKEN     css=nav.topbar > button.link-btn         SignInFlow.cs:15                          0
  -> Suggestion (High, css): Locator("css=nav.appbar > button.link-btn")
  -> Suggestion (High, xpath): Locator("xpath=/html/body/nav[1]/button[1]")
HEALTHY    data-testid=email                        SignInFlow.cs:17                          1
HEALTHY    data-testid=password                     SignInFlow.cs:18                          1
HEALTHY    data-testid=sign-in                      SignInFlow.cs:19                          1

Total 4  |  3 healthy  |  1 broken  |  0 ambiguous  |  0 skipped

Step 5: repair

Now the part that saves you the morning. For a broken selector that has a manifest entry, Motus scans the live page for the fingerprinted element and grades what it finds. An exact hash recompute is High. All key attributes matching, or at least three of them, is Medium. Same tag and ancestor path with fewer than three is Low. It then regenerates selectors through every strategy and keeps the ones that resolve uniquely.

--fix applies the first suggestion, and only when that suggestion grades High. The edit goes through a Roslyn rewriter that replaces the call and leaves the rest of the file exactly as it was, comments and formatting included. The original is copied to <file>.bak unless you pass --no-backup.

motus check-selectors "tests/**/*.cs" \
    --manifest tests/SignInFlow.selectors.json --fix

A repaired row prints as FIXED with a -> Fixed: line under it. A renamed test id or an edited label grades Medium or Low, so it gets reported and left alone for a person to look at. --interactive walks you through those one at a time in the visual runner, with the candidate highlighted on the page. Repairs need a fingerprint, so both flags require --manifest, and you cannot combine them. A usage error exits 2.

In CI

Run the check as its own job against a deployed environment:

motus check-selectors "tests/**/*.cs" \
    --base-url https://staging.example.com \
    --ci --json selector-report.json

--ci exits non-zero as soon as anything is broken, and --json writes the full result out for a build annotation. Keep --fix out of CI. A repair is a source change, and source changes belong in a pull request where somebody reads them.

One thing that will catch you out

--detect-listeners adds a second codegen pass over CDP DOMDebugger.getEventListeners to find clickable elements carrying a directly attached handler. It sees vanilla JavaScript and jQuery listeners. It does not see React's delegated events, which are bound at the root rather than on the element. On a React application you get back only the semantic set, so plan on adding test ids to whatever the crawl cannot name.

The full option lists live in the recording and code generation guide and the CLI reference, and Motus 1.0 covers what sits underneath all of it. If you have a suite already, point check-selectors at it and tell me what comes back. I am most curious about the ambiguous ones.

Motus 1.0.7 added accessibility auditing and 1.0.8, out today, adds Core Web Vitals and performance budgets. Both read from the session your test is already driving. An audit is an assertion in the middle of a test, not a job at the end of the build.

The accessibility side

The tree comes from the browser, not from a library we inject into your page. Motus asks CDP for the browser's own computed accessibility tree and hands each node to every registered rule, and color values come from the browser's computed styles. Two of the nine rules do run a single Runtime.evaluate each, for the duplicate-id sweep and for the document's lang attribute, so the honest way to put this is that the audit does not inject a rule engine, not that it runs no JavaScript at all.

Nine rules ship, registered by AccessibilityRulesPlugin:

Nine rules is a small number, and I mean it to read that way. axe-core's own published rule set is several times larger, and Motus does not depend on it, port it, or try to replace it. What nine rules buy you is that the check is already in the box, runs in-process, and has no extra package to install and keep current. Playwright delegates accessibility auditing to the separate axe-playwright ecosystem package, and if you need axe's full coverage that is still the right tool.

Three ways to use it

As an assertion, on the page you are already on:

await Expect.That(Page).ToPassAccessibilityAuditAsync();

await Expect.That(Page).ToPassAccessibilityAuditAsync(opts =>
{
    opts.SkipRules("a11y-color-contrast", "a11y-missing-landmark");
});

IncludeWarnings defaults to true, so the two warning-severity rules fail the assertion unless you set it to false. Individual elements have their own assertions: ToHaveAccessibleNameAsync("Submit order") and ToHaveRoleAsync("navigation").

A failure names what it found. Each AccessibilityViolation carries the rule id, the severity, a message, the node's role and accessible name, and the backend node id it came from, so the report points at an element rather than at a page. Worth knowing: unlike most locator assertions, the audit assertion evaluates once instead of polling, which is the right behavior for a whole-page check. Put it after the assertion that establishes the state you meant to audit.

As a lifecycle hook, so every navigation is audited without a line in the test:

await MotusTestBase.LaunchBrowserAsync(new LaunchOptions
{
    Headless = true,
    Accessibility = new AccessibilityOptions
    {
        Enable = true,
        Mode = AccessibilityMode.Warn,
        AuditAfterActions = true
    },
    Performance = new PerformanceOptions { Enable = true }
});

AuditAfterNavigation is on by default and AuditAfterActions is off; when it is on, the audited actions are click, fill and select. Mode is Off, Warn or Enforce. When the hook is running, ToPassAccessibilityAuditAsync reuses the audit it already stored rather than running another one; when the hook is off, the assertion runs an audit on demand.

And from the runner:

motus run ./bin/Debug/net8.0/MyTests.dll --a11y enforce --perf-budget

One thing to know about --a11y: leaving it off means the hook never activates, whatever motus.config.json says. The flag is what turns the section on.

Adding a rule of your own

IAccessibilityRule has three members, and a rule is called once per node with a context that carries the page-wide facts a single node cannot answer.

using Motus.Abstractions;

public sealed class DisclosureExpandedRule : IAccessibilityRule
{
    public string RuleId => "custom-aria-expanded-disclosure";

    public string Description =>
        "Disclosure triggers must expose aria-expanded.";

    public AccessibilityViolation? Evaluate(
        AccessibilityNode node, AccessibilityAuditContext context)
    {
        if (!string.Equals(node.Role, "button", StringComparison.OrdinalIgnoreCase))
            return null;
        if (!node.Properties.ContainsKey("controls") || node.Properties.ContainsKey("expanded"))
            return null;

        return new AccessibilityViolation(
            RuleId: RuleId,
            Severity: AccessibilityViolationSeverity.Error,
            Message: "Disclosure button must expose aria-expanded.",
            NodeRole: node.Role,
            NodeName: node.Name,
            BackendDOMNodeId: node.BackendDOMNodeId,
            Selector: null);
    }
}

Register it from a plugin with context.RegisterAccessibilityRule(...), which is the same call the nine built-in rules use. That is not a coincidence: as we wrote about the plugin model, the built-ins have no private entrance.

The performance side

The performance collector is a lifecycle hook too. It installs a small observer script when the page is created, takes a snapshot after each navigation, and takes a final one when the page closes.

A metric that was never observed stays null, and an assertion against a null metric fails immediately rather than passing quietly.

Thresholds are declared, not passed in:

[TestClass]
[PerformanceBudget(Lcp = 2500, Fcp = 1800, Cls = 0.1)]
public class DashboardTests : MotusTestBase
{
    [TestMethod]
    public async Task DashboardIsWithinBudget()
    {
        await Page.GotoAsync("https://app.example.com/dashboard");
        await Expect.That(Page).ToMeetPerformanceBudgetAsync();
    }

    [TestMethod]
    [PerformanceBudget(Lcp = 1500)]
    public async Task CheckoutIsTighter()
    {
        await Page.GotoAsync("https://app.example.com/checkout");
        await Expect.That(Page).ToMeetPerformanceBudgetAsync();
    }
}

Every property on the attribute defaults to -1, which means not enforced, so a budget only covers the metrics you name. Zero is a real threshold. The method attribute wins over the class attribute, and motus.config.json is the fallback. If nothing supplies a budget at all, ToMeetPerformanceBudgetAsync throws instead of passing, so a test can never quietly assert nothing.

Individual metrics have their own assertions when a whole budget is more than you want: ToHaveLcpBelowAsync(2500), ToHaveFcpBelowAsync(1800), ToHaveTtfbBelowAsync(600), ToHaveClsBelowAsync(0.1), ToHaveInpBelowAsync(200). Each one re-collects metrics on every poll, so a value that arrives late still counts.

One more thing about the CLI flag: --perf-budget turns enforcement on and nothing else. The numbers still come from [PerformanceBudget] or from the performance section of the config file.

What Firefox gets

The observer script is ordinary page JavaScript, so LCP, FCP, CLS and INP are collected over WebDriver BiDi as well. JS heap size and DOM node count come from a CDP domain and are always null there. The accessibility tree is CDP-only too, so an audit on a Firefox session comes back empty with a diagnostic message naming the transport rather than throwing halfway through a suite. If accessibility gating matters to you, run that job on Chromium.

None of this says the browser you test in is the browser your users have. It says something narrower, about which page gets checked. The audit that runs after your test has logged in, opened the drawer and filtered the table is looking at the markup a person would actually run into, and the budget it is measured against is the one your team wrote down.

Both features are off by default. Turning them on is one options block or one flag, and after that the checks live where the rest of your assertions do. The accessibility guide and the performance guide cover the rest of the configuration. If you turn it on and there is a rule you wish was in the box, tell me which one.

I did not want to make that trade, so Verso goes the other way. The same file runs at your desk and in a pipeline, the inputs are declared once inside the file, and the command line supplies them. This guide takes a notebook from a form in the editor to a scheduled GitHub Actions job that turns the build red when a cell fails.

Before you start

You need the .NET 8.0 SDK or later, the Verso command line tool, and a notebook to run. Any .verso, .ipynb, or .dib file will do.

dotnet tool install -g Verso.Cli
verso info

verso info prints the CLI version, the .NET runtime, the engine version, and every extension, serializer, and formatter it discovered. Run it once now so you know what a healthy environment looks like, because you will want to compare against it later. The built-in kernels travel with the tool, so there is nothing else to install on the agent.

Step 1: declare the inputs

Parameters live in the notebook's metadata. Each one gets a type, and if you want it, a description, a default, a required flag, and a place in the ordering.

{
  "verso": "1.0",
  "metadata": {
    "title": "Regional Sales Report",
    "defaultKernel": "csharp",
    "parameters": {
      "region":     { "type": "string", "description": "Region to process",
                      "required": true, "order": 1 },
      "reportDate": { "type": "date", "description": "Report date",
                      "required": true, "order": 2 },
      "batchSize":  { "type": "int", "default": 1000, "order": 3 },
      "dryRun":     { "type": "bool", "default": false, "order": 4 }
    }
  }
}

You do not have to write that by hand. Insert a parameters cell in the editor and you get a form for the name, type, and default, and it writes the same metadata into the file for you.

There are six types, and each one is coerced to a CLR type before any cell runs.

Step 2: read them from any cell

Parameters go into the shared variable store before the first cell executes. That means they are ordinary variables in every kernel, not something a Python cell has to be handed on its way in. One variable store, eight languages covers how that store works.

In C# they are top-level variables, already the right type:

var cutoff = reportDate.AddDays(-7);
Console.WriteLine($"{region}: {cutoff:yyyy-MM-dd} to {reportDate:yyyy-MM-dd}, batch {batchSize}");

In a SQL cell the same names come through as bindings:

SELECT product, SUM(amount) AS total
FROM sales
WHERE region = @region AND sale_date = @reportDate
GROUP BY product

In a Python cell they are just names. One declaration, three languages reading it.

Step 3: run it from a terminal

Now leave the editor and run the same file from a shell.

verso run pipeline.verso \
  --param region=us-east \
  --param reportDate=2026-04-08

--param is repeatable and uses an equals sign. Values are parsed against the declared type before anything executes, so a bad date is an error you see right away instead of a crash forty seconds in.

What comes back is the cells, in order, then a summary:

─── Cell 2 (csharp) ──────────────────────
us-east: 2026-04-01 to 2026-04-08, batch 1000

─── Summary ──────────────────────────────
Cells: 5 total, 5 succeeded, 0 failed
Time:  3.4s

Two flags are worth knowing here. --show-parameters prints the resolved values alongside the cells, which is what a pipeline log needs when someone asks a month later what the nightly run actually used. --interactive prompts on standard input for any required parameter you left out, which is what you want at your desk.

Step 4: let the exit code decide

verso run streams to the terminal and returns a specific code. Nothing is written back to the notebook unless you pass --save, so a scheduled run cannot quietly rewrite the file in your repository.

Code 5 is the one that saves you time. A required parameter with no value stops the run before a single cell executes and tells you what is missing:

Error: Missing required notebook parameters:

  region (string)  Region to process
  reportDate (date)  Report date

Supply values with --param or use --interactive to be prompted.

By default a run keeps going past a failed cell, so one pass shows you every failure instead of only the first. --fail-fast stops at the first one. --timeout caps the whole run and defaults to 300 seconds, which is short for a report that reads a database, so pick that number on purpose rather than finding out at 6am.

Step 5: the workflow file

Here is a complete scheduled job: install the tool, run the notebook, write machine-readable results, and keep them whether the run passed or not.

name: Nightly report

on:
  schedule:
    - cron: "0 6 * * *"
  workflow_dispatch:

jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: "8.0.x"

      - name: Install the Verso CLI
        run: dotnet tool install -g Verso.Cli

      - name: Run the notebook
        run: |
          verso run reports/regional.verso \
            --param region=us-east \
            --param reportDate=$(date -u +%Y-%m-%d) \
            --show-parameters \
            --output json \
            --output-file results.json \
            --fail-fast \
            --timeout 900
        env:
          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}

      - name: Keep the results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: regional-results
          path: results.json

--output json writes the notebook path, one entry per cell carrying its index, id, language, status, elapsed time and outputs, the resolved parameters, and a summary of totals. Parse that when a later step needs to know which cell failed.

Notice what is not a --param. Command-line arguments show up in process listings, so a password belongs in the step's env: block and gets read from the connection string:

#!sql-connect --name prod --connection-string "Server=$var:dbServer;Database=Analytics;User Id=svc_report;Password=$env:DB_PASSWORD"

$var: reads the variable store, so it picks up a parameter. $env: reads the process environment. Neither value reaches the command line.

Step 6: one notebook, four regions

Once the inputs are on the command line, a matrix runs the same file several ways:

    strategy:
      fail-fast: false
      matrix:
        region: [us-east, us-west, eu-central, ap-south]

verso run reports/regional.verso \
  --param region=${{ matrix.region }} \
  --output json --output-file results-${{ matrix.region }}.json

fail-fast: false keeps the other legs running when one of them fails, so a bad region does not hide the state of the rest.

Coming from Papermill

If you already run parameterized notebooks with Papermill, the shapes line up and the mechanics differ. Here is the mapping.