Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions checks/fixtures/twin-dashboard.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Dashboard title

`.clayo/pages/dashboard.html` · written 2026-11-18 12:00

What these numbers cover and the one thing they say.

1,284 label (+8% vs last week) · 99.2% label · 340 ms label · 7 label

**Trend title**, a line chart:

| | This week | Last week |
|---|---|---|
| Mon | 12 | 10 |
| Tue | 19 | 14 |
| Wed | 14 | 13 |
| Thu | 22 | 17 |
| Fri | 25 | 19 |

**Breakdown title**, a doughnut chart:

| | Share |
|---|---|
| A | 55 |
| B | 30 |
| C | 15 |

## Table title

| Name | Status | Value | Change |
|---|---|---|---|
| First | ok | 812 | +4% |
| Second | slow | 472 | -2% |
37 changes: 37 additions & 0 deletions checks/fixtures/twin-report.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# Report title

`.clayo/pages/report.html` · written 2026-11-18 12:00

One or two sentences with the conclusion, including the key number.

Scope or date · Status

312 label · 98.7% label (+1.2 since last run) · 4 label

## First finding

What you found and why it matters, in two or three sentences.

> **Watch out.** The one thing the reader must not miss.

## Details

| Item | Status | Count | Time |
|---|---|---|---|
| `auth/login` | failed | 4 | 1.8 s |
| `api/users` | passed | 120 | 0.6 s |

## Chart or diagram

**Chart title**, a bar chart:

| | Series |
|---|---|
| A | 4 |
| B | 7 |
| C | 2 |

## Next steps

1. **Do this first.** Why, in a few words.
2. **Then this.** Why, in a few words.
73 changes: 73 additions & 0 deletions checks/fixtures/twin-slides.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# Deck title

`.clayo/pages/slides.html` · written 2026-11-18 12:00

The one-line message of the whole deck.

---

## A part of the deck

What this part shows, in one line.

---

## A heading that states the point

- A short bullet, one line.
- Another, with the **key term** in bold.
- At most four.

---

**42%**

What the number is, in one line.

---

## Text on the left

Two or three sentences about what the chart shows.

A bar chart:

| | Series |
|---|---|
| A | 4 |
| B | 7 |
| C | 2 |

---

## Numbers side by side

312 label · 98% label · 4 label

---

## Three things side by side

### First

One or two lines.

### Second

One or two lines.

### Third

One or two lines.

---

> A sentence worth a slide of its own.

— Who said it

---

## The one thing to remember

What happens next, in one line.
53 changes: 53 additions & 0 deletions checks/pages.cs
Original file line number Diff line number Diff line change
Expand Up @@ -321,6 +321,59 @@ string Bundle(string body) => PageBundle.Make(
Check(" odd types in the file read as nothing", (new PageShares(Path.Combine(dir, "shares.json")).Login, new PageShares(Path.Combine(dir, "shares.json")).All().Count), ((string?)null, 0));
Check(" a broken entry is skipped", new PageShares(Path.Combine(dir, "shares.json")).All().Count, 0);
Check("filter: shared only", string.Join(",", PageIndex.Filter([fixture[0], fixture[1] with { Shared = true }], new(Shared: true)).Select(p => p.Title)), "alpha");

// The text twin (P9, D18): markdown made from the page, for other sessions to read.
var fixtures = Path.Combine(AppContext.BaseDirectory, "..", "..", "..", "..", "..", "checks", "fixtures");
if (!Directory.Exists(fixtures)) fixtures = Path.Combine(Environment.CurrentDirectory, "fixtures");
var made = new DateTime(2026, 11, 18, 12, 0, 0);
foreach (var name in new[] { "report", "dashboard", "slides" })
{
var html = File.ReadAllText(Path.Combine(AppContext.BaseDirectory, "Assets", "pages", "templates", name + ".html"));
var twin = PageTwin.Make(html, name + ".html", made);
Check($"twin: {name}.html matches its fixture", twin, File.ReadAllText(Path.Combine(fixtures, $"twin-{name}.md")).ReplaceLineEndings("\n"));
if (name == "report") Console.WriteLine($" report twin: {twin.Length} of {html.Length} bytes ({100.0 * twin.Length / html.Length:F0}%)");
}
string Twin(string body) => PageTwin.Make($"<!doctype html><head><title>T</title></head><body>{body}</body>", "t.html", made);
Check(" the title first, then the file and when", Twin("<main class=\"page\"><h1>T</h1></main>"), "# T\n\n`.clayo/pages/t.html` · written 2026-11-18 12:00\n\n\n");
Check(" a chart gives a data table",
Twin("<script type=\"application/json\" class=\"chart\">{\"type\":\"bar\",\"title\":\"Fails\",\"yLabel\":\"n\",\"labels\":[\"auth\",\"api\"],\"series\":[{\"name\":\"a\",\"data\":[4,0]},{\"name\":\"b\",\"data\":[1]}]}</script>")
.Contains("**Fails**, a bar chart (n):\n\n| | a | b |\n|---|---|---|\n| auth | 4 | 1 |\n| api | 0 | |"), true);
Check(" a scatter, a row per point", Twin("<script type=\"application/json\" class=\"chart\">{\"type\":\"scatter\",\"series\":[{\"name\":\"s\",\"data\":[[1,2],[3,4]]}]}</script>")
.Contains("| | x | y |\n|---|---|---|\n| s | 1 | 2 |\n| s | 3 | 4 |"), true);
Check(" broken chart JSON is left out", Twin("<p>a</p><script type=\"application/json\" class=\"chart\">{nope</script>").EndsWith("\n\na\n"), true);
Check(" Mermaid as a mermaid block", Twin("<pre class=\"mermaid\">\nflowchart LR\n A --&gt; B\n</pre>").Contains("```mermaid\nflowchart LR\n A --> B\n```"), true);
var deckTwin = Twin("<main class=\"deck\"><section class=\"slide\"><h2>One</h2></section><section class=\"slide\"><h2>Two</h2></section><section class=\"slide\"><h2>Three</h2></section></main>");
Check(" a deck: one section per slide", deckTwin.EndsWith("## One\n\n---\n\n## Two\n\n---\n\n## Three\n"), true);
Check(" layout as short lines", Twin("<section class=\"kpis\"><div class=\"kpi good\"><b>312</b><span>passed</span></div><div class=\"kpi bad\"><b>4</b><span>failed</span></div></section>")
.Contains("\n312 passed · 4 failed\n"), true);
Check(" no script, style or image data", Twin("<style>p{}</style><script>var x;</script><p>a <img alt=\"logo\" src=\"data:image/png;base64,AAAA\"></p>").EndsWith("\n\na [image: logo]\n"), true);
Check("index.html's twin is not the list", Path.GetFileName(PageTwin.PathOf(@"C:\p\.clayo\pages\index.html")), "index.html.md");

// The twin and index.md follow the index.
var twinDir = Path.Combine(dir, "twin", ".clayo", "pages");
Directory.CreateDirectory(twinDir);
var one = Path.Combine(twinDir, "one.html");
var two = Path.Combine(twinDir, "two.html");
File.WriteAllText(one, "<title>First</title><main class=\"page\"><p>hello</p></main>");
File.WriteAllText(two, "<title>Second</title>");
var twins = new PageIndex(Path.Combine(dir, "twins.json"));
twins.Record([one, two], Path.Combine(dir, "twin"), "s1", "Claude");
var list = Path.Combine(twinDir, PageTwin.IndexFile);
Check("record: the twin is written beside the page", File.Exists(Path.Combine(twinDir, "one.md")) && File.ReadAllText(Path.Combine(twinDir, "one.md")).Contains("\nhello\n"), true);
Check(" index.md lists every page", (File.ReadAllText(list).Contains("- First: `one.md` (page `one.html`)"), File.ReadAllText(list).Contains("- Second: `two.md`")), (true, true));
File.WriteAllText(one, "<title>First</title><main class=\"page\"><p>changed</p></main>");
File.SetLastWriteTimeUtc(one, DateTime.UtcNow.AddMinutes(1));
twins.Record([one], Path.Combine(dir, "twin"), "s1", "Claude");
Check(" a change rewrites the twin", File.ReadAllText(Path.Combine(twinDir, "one.md")).Contains("\nchanged\n"), true);
twins.Scan([Path.Combine(dir, "twin")]);
Check(" the scan lists no twin as a page", twins.Recent(int.MaxValue).Count, 2);
twins.Remove([two]);
Check("remove: the twin goes too", File.Exists(Path.Combine(twinDir, "two.md")), false);
Check(" and index.md drops it", File.ReadAllText(list).Contains("Second"), false);
File.Delete(one);
twins.Recent(10);
Check("a page that drops out takes its twin", File.Exists(Path.Combine(twinDir, "one.md")), false);
Check(" none left: no index.md", File.Exists(list), false);
}
finally { Directory.Delete(dir, recursive: true); }

Expand Down
26 changes: 24 additions & 2 deletions checks/prompt.cs
Original file line number Diff line number Diff line change
Expand Up @@ -128,10 +128,32 @@ void Same(string name, object? got, object? want)
Same("a line carried on with \\: not", PagePrompt.Rewrite("/page x\\"), null);
Same("with a page open, the prompt names it",
PagePrompt.Rewrite("/page make the title shorter", @"C:\proj\.clayo\pages\test-results.html"),
Head + " (open: `.clayo/pages/test-results.html`): make the title shorter.");
Same("Claude: the open page goes on the end of the line", PagePrompt.OpenNote(@"C:\proj\.clayo\pages\a.html"), " (open: `.clayo/pages/a.html`)");
Head + ": make the title shorter. (page open: .clayo/pages/test-results.md)");
Same("the open page goes on the end of the line, by its twin", PagePrompt.OpenNote(@"C:\proj\.clayo\pages\a.html"), " (page open: .clayo/pages/a.md)");
Same(" none open: nothing", PagePrompt.OpenNote(null), "");

// The open page's twin is named on the first prompt after it opens or changes (P9), not on every one.
{
const string Open = @"C:\proj\.clayo\pages\a.html";
const string Note = " (page open: .clayo/pages/a.md)";
var t0 = new DateTime(2026, 11, 18, 9, 0, 0, DateTimeKind.Utc);
var note = new OpenPageNote();
Same("twin: no page open, nothing", note.For("hello", null, t0), "");
Same(" the first prompt gets it", note.For("summarise this", Open, t0), Note);
Same(" the next doesn't", note.For("and shorter", Open, t0), "");
Same(" a change to the page brings it back", note.For("again", Open, t0.AddSeconds(5)), Note);
Same(" a slash command never", new OpenPageNote().For("/model", Open, t0), "");
Same(" nor a shell line or an empty one", (new OpenPageNote().For("!ls", Open, t0), new OpenPageNote().For(" ", Open, t0)), ("", ""));
note.Forget();
Same(" opened again: named again", note.For("hi", Open, t0.AddSeconds(5)), Note);
var cmd = new OpenPageNote();
Same(" /page always, once", cmd.For("/page x", Open, t0) + cmd.For("/page y", Open, t0), Note + Note);
Same(" and the prompt after it doesn't repeat it", cmd.For("thanks", Open, t0), "");
Same("/page gets one suffix, not two",
PagePrompt.Rewrite("/page x", Open)!.Split("(page open:").Length - 1, 1);
Same("Claude's /page says what the suffix means", PagePrompt.ClaudeCommand.Contains("(page open: <name>.md)") && PagePrompt.ClaudeCommand.Contains(".html"), true);
}

// The line at the prompt, from the keys alone.
string? Typed(params string[] keys)
{
Expand Down
4 changes: 4 additions & 0 deletions src/Clayo/Assets/pages/page-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@
A page is one HTML file that Clayo shows beside the terminal: a report, a dashboard, a
diagram or a slide deck. The design is already done. You write content and data.

To read an existing page, read its `.md` twin (Clayo writes it beside the page; all of them are
listed in `.clayo/pages/index.md`). `(page open: <name>.md)` at the end of a prompt names the
page open in Clayo by its twin; a change to it goes in `<name>.html`. Never write a twin.

## 1. The contract

- One file: `.clayo/pages/<name>.html`. Name in kebab-case from the title
Expand Down
41 changes: 31 additions & 10 deletions src/Clayo/Pages/PageIndex.cs
Original file line number Diff line number Diff line change
Expand Up @@ -51,18 +51,23 @@ public PageIndex(string? file = null)
/// <summary>The pages whose files are still there.</summary>
public int Count => _pages.Count(p => File.Exists(p.Path));

/// <summary>Adds the pages a session wrote, or brings the ones already known up to date.</summary>
/// <summary>
/// Adds the pages a session wrote, or brings the ones already known up to date, with their
/// text twins (PageTwin).
/// </summary>
public void Record(IEnumerable<string> paths, string project, string? sessionId, string agent)
{
foreach (var path in paths.Where(File.Exists))
var written = paths.Where(File.Exists).ToList();
foreach (var path in written)
{
var now = File.GetLastWriteTimeUtc(path);
int at = _pages.FindIndex(p => Same(p.Path, path));
var entry = new PageEntry(path, TitleOf(path), project, sessionId, agent, at < 0 ? now : _pages[at].Created, now);
if (at < 0) _pages.Add(entry);
else _pages[at] = entry;
PageTwin.Update(path);
}
Save();
Save(written);
}

/// <summary>
Expand All @@ -71,28 +76,37 @@ public void Record(IEnumerable<string> paths, string project, string? sessionId,
/// </summary>
public void Scan(IEnumerable<string> projects)
{
int before = _pages.Count;
var found = new List<string>();
foreach (var project in projects.Distinct(StringComparer.OrdinalIgnoreCase))
{
var folder = System.IO.Path.Combine(project, ".clayo", "pages");
if (!Directory.Exists(folder)) continue;
try
{
// Only the pages: their twins and index.md are .md.
foreach (var path in Directory.EnumerateFiles(folder, "*.html"))
if (!_pages.Any(p => Same(p.Path, path)))
{
_pages.Add(new PageEntry(path, TitleOf(path), project, null, "",
File.GetCreationTimeUtc(path), File.GetLastWriteTimeUtc(path)));
PageTwin.Update(path);
found.Add(path);
}
}
catch (Exception e) when (e is IOException or UnauthorizedAccessException) { }
}
if (_pages.Count != before) Save();
if (found.Count > 0) Save(found);
}

/// <summary>Takes these pages out of the index (their files are deleted by the caller).</summary>
/// <summary>Takes these pages and their twins out of the index (the pages are deleted by the caller).</summary>
public void Remove(IEnumerable<string> paths)
{
var gone = paths.ToHashSet(StringComparer.OrdinalIgnoreCase);
if (_pages.RemoveAll(p => gone.Contains(p.Path)) > 0) Save();
var removed = _pages.Where(p => gone.Contains(p.Path)).Select(p => p.Path).ToList();
if (removed.Count == 0) return;
_pages.RemoveAll(p => gone.Contains(p.Path));
removed.ForEach(PageTwin.Delete);
Save(removed);
}

/// <summary>
Expand All @@ -101,10 +115,14 @@ public void Remove(IEnumerable<string> paths)
/// </summary>
public IReadOnlyList<PageEntry> Recent(int max)
{
int before = _pages.Count;
var gone = _pages.Where(p => !File.Exists(p.Path)).Select(p => p.Path).ToList();
_pages = [.. _pages.Where(p => File.Exists(p.Path)).Select(p => p with { Changed = File.GetLastWriteTimeUtc(p.Path) })];
var recent = _pages.OrderByDescending(p => p.Changed).Take(max).Select(p => p with { Title = TitleOf(p.Path), Deck = IsDeck(p.Path) }).ToList();
if (_pages.Count != before) Save();
if (gone.Count > 0)
{
gone.ForEach(PageTwin.Delete);
Save(gone);
}
return recent;
}

Expand Down Expand Up @@ -158,8 +176,11 @@ public static string TitleOf(string path)
return System.IO.Path.GetFileNameWithoutExtension(path);
}

private void Save()
// Writes pages.json, and index.md in the folders of the pages that changed (PageTwin).
private void Save(IEnumerable<string> changed)
{
foreach (var folder in changed.Select(System.IO.Path.GetDirectoryName).OfType<string>().Distinct(StringComparer.OrdinalIgnoreCase))
PageTwin.WriteIndex(folder, _pages.Where(p => Same(System.IO.Path.GetDirectoryName(p.Path) ?? "", folder)));
try
{
Directory.CreateDirectory(System.IO.Path.GetDirectoryName(_file)!);
Expand Down
Loading