babavoss 0.0.1 → 0.12.0

package/src/gui/wizard.tsx

@@ -0,0 +1,227 @@
+// The New baba app, at voss's root: a folder browser and, in the folder
+// chosen, a baba made, or one already there remembered or opened. A list
+// moved by the keyboard as much as by the pointer: arrows move, Enter goes
+// into a folder, Backspace up, Cmd/Ctrl Enter makes. The daemon answers:
+// /api/dirs for a directory's folders, /api/projects/add to remember a baba
+// or make one.
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { apiHeaders } from "babavoss/web";
+
+export interface Project { name: string; title: string; dir?: string; parent: string | null }
+interface Folder { name: string; path: string; baba: boolean; known: boolean }
+interface Browsed { path: string; home: string; parent: string | null; baba: boolean; known: boolean; dirs: Folder[] }
+
+export const getJson = async <T,>(path: string): Promise<T> => {
+  const r = await fetch(path, { headers: apiHeaders() });
+  const j = await r.json() as T & { error?: { message: string } };
+  if (!r.ok || j.error) throw new Error(j.error?.message ?? r.statusText);
+  return j;
+};
+const postJson = async <T,>(path: string, body: unknown): Promise<T> => {
+  const r = await fetch(path, { method: "POST", headers: { "content-type": "application/json", ...apiHeaders() }, body: JSON.stringify(body) });
+  const j = await r.json() as T & { error?: { message: string } };
+  if (!r.ok || j.error) throw new Error(j.error?.message ?? r.statusText);
+  return j;
+};
+
+/** A path as a person reads it: under home, from ~. */
+export const tilde = (path: string, home: string) => (home && (path === home || path.startsWith(home + "/")) ? "~" + path.slice(home.length) : path);
+/** A path short enough for a row: its start and its last two folders, the middle elided. */
+export const short = (path: string, home: string, max = 52) => {
+  const t = tilde(path, home);
+  if (t.length <= max) return t;
+  const parts = t.split("/");
+  const head = parts[0] === "" ? "" : parts[0]!;
+  for (let keep = 3; keep >= 1; keep--) { const s = `${head}/…/${parts.slice(-keep).join("/")}`; if (s.length <= max || keep === 1) return s; }
+  return t;
+};
+/** A directory's name as a baba's name: what `voss init` would choose. */
+const slug = (s: string) => s.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+const isTyping = (e: KeyboardEvent) => e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement || e.target instanceof HTMLSelectElement;
+
+// ---- glyphs: drawn here, 16 on a 16 grid, in the current colour ------------
+
+const Svg = ({ children, size = 16 }: { children: ReactNode; size?: number }) => (
+  <svg width={size} height={size} viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">{children}</svg>
+);
+const FolderGlyph = () => <Svg><path d="M2 4.5c0-.6.4-1 1-1h3l1.5 1.5H13c.6 0 1 .4 1 1V12c0 .6-.4 1-1 1H3c-.6 0-1-.4-1-1z" /></Svg>;
+const BabaGlyph = () => <Svg><rect x="2.5" y="2.5" width="11" height="11" rx="3" /><circle cx="8" cy="8" r="2" fill="currentColor" stroke="none" /></Svg>;
+const Up = () => <Svg><path d="M8 13V3.5M4 7l4-4 4 4" /></Svg>;
+const Chevron = () => <Svg size={14}><path d="M6 4l4 4-4 4" /></Svg>;
+const Home = () => <Svg size={14}><path d="M2.5 7.5L8 3l5.5 4.5V13H10V9.5H6V13H2.5z" /></Svg>;
+const Search = () => <Svg size={14}><circle cx="7" cy="7" r="4" /><path d="M10 10l3 3" /></Svg>;
+const Spinner = () => <span className="pk-spin" aria-hidden="true" />;
+
+
+/** Keeps the active row in view as the keys move it. */
+function useInView(list: React.RefObject<HTMLElement | null>, active: number) {
+  useLayoutEffect(() => { list.current?.querySelector(`[data-i="${active}"]`)?.scrollIntoView({ block: "nearest" }); }, [list, active]);
+}
+
+// ---- the folder picker ---------------------------------------------------
+
+/** The wizard: from `start`, or the daemon's own choice of folder; `onOpened` with the baba's name once it is made, remembered or found; `onBack` on Escape. */
+export function Folders({ home, start, onBack, onOpened, onVerb }: { home: string; start?: string; onBack: () => void; onOpened: (name: string) => void; onVerb?: (verb: string) => void }) {
+  const [at, setAt] = useState<Browsed | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState<string | null>(null);
+  const [filter, setFilter] = useState("");
+  const [active, setActive] = useState(0);
+  const [name, setName] = useState("");
+  const [title, setTitle] = useState("");
+  const list = useRef<HTMLOListElement>(null);
+  const filterRef = useRef<HTMLInputElement>(null);
+  const homeDir = at?.home || home;
+
+  const walk = (path: string) => {
+    setLoading(true);
+    getJson<Browsed>(`/api/dirs?path=${encodeURIComponent(path)}`).then((b) => {
+      // Coming up out of a folder, the folder left is the one the keys are on.
+      const from = at?.path;
+      const back = from ? b.dirs.findIndex((d) => d.path === from) : -1;
+      setAt(b); setError(null); setFilter(""); setName(""); setTitle("");
+      onVerb?.(b.known ? "open" : b.baba ? "remember" : "make");
+      // The filter keeps the keys: whatever is typed next narrows the folders here.
+      if (!(document.activeElement instanceof HTMLInputElement) || document.activeElement === filterRef.current) filterRef.current?.focus();
+      setActive(back >= 0 ? back + (b.parent ? 1 : 0) : 0);
+    }, (e) => setError(String(e instanceof Error ? e.message : e))).finally(() => setLoading(false));
+  };
+  useEffect(() => { walk(start ?? ""); filterRef.current?.focus(); }, []);
+
+  const words = filter.toLowerCase().split(/\s+/).filter(Boolean);
+  const dirs = (at?.dirs ?? []).filter((d) => words.every((w) => d.name.toLowerCase().includes(w)));
+  // The rows the keys move over: up first when there is somewhere to go up to and nothing is filtered.
+  const rows: ({ kind: "up"; path: string } | { kind: "dir"; d: Folder })[] = [
+    ...(at?.parent && !words.length ? [{ kind: "up" as const, path: at.parent }] : []),
+    ...dirs.map((d) => ({ kind: "dir" as const, d })),
+  ];
+  const cur = Math.min(active, Math.max(0, rows.length - 1));
+  useInView(list, cur);
+
+  const act = async () => {
+    if (!at || busy) return;
+    if (at.known) { const p = await getJson<{ projects: Project[] }>("/api/projects"); const own = p.projects.find((x) => x.dir === at.path); if (own) onOpened(own.name); return; }
+    const init = !at.baba;
+    setBusy(init ? "Making the baba and installing its packages…" : "Opening the baba…");
+    setError(null);
+    try {
+      const made = await postJson<{ name: string }>("/api/projects/add", { dir: at.path, init, ...(name.trim() ? { name: name.trim() } : {}), ...(title.trim() ? { title: title.trim() } : {}) });
+      onOpened(made.name);
+    } catch (e) { setError(String(e instanceof Error ? e.message : e)); setBusy(null); }
+  };
+  const enter = (i: number) => { const r = rows[i]; if (r) walk(r.kind === "up" ? r.path : r.d.path); };
+
+  useEffect(() => {
+    const key = (e: KeyboardEvent) => {
+      // The shell's launcher has the keys while it is open over the wizard.
+      if (busy || document.querySelector(".desktop-launcher")) return;
+      const inField = isTyping(e) && e.target !== filterRef.current;
+      if ((e.metaKey || e.ctrlKey) && e.key === "Enter") { e.preventDefault(); void act(); return; }
+      if (e.key === "Escape") { e.preventDefault(); if (inField) (e.target as HTMLElement).blur(); else if (filter) setFilter(""); else onBack(); return; }
+      if (inField) return;
+      if (e.key === "ArrowDown") { e.preventDefault(); setActive(Math.min(rows.length - 1, cur + 1)); }
+      else if (e.key === "ArrowUp") { e.preventDefault(); setActive(Math.max(0, cur - 1)); }
+      else if (e.key === "Enter") { e.preventDefault(); enter(cur); }
+      else if (e.key === "ArrowRight" && rows[cur]?.kind === "dir") { e.preventDefault(); enter(cur); }
+      else if ((e.key === "Backspace" && !filter) || e.key === "ArrowLeft" && !filter) { if (at?.parent) { e.preventDefault(); walk(at.parent); } }
+      else if (e.key.length === 1 && !e.metaKey && !e.ctrlKey && !e.altKey && document.activeElement !== filterRef.current) filterRef.current?.focus();
+    };
+    addEventListener("keydown", key); return () => removeEventListener("keydown", key);
+  });
+
+  // The path as crumbs: home is ~, each part walks there.
+  const crumbs = useMemo(() => {
+    if (!at) return [];
+    const t = tilde(at.path, homeDir);
+    const parts = t.split("/").filter(Boolean);
+    const root = t.startsWith("~") ? homeDir : "";
+    return parts.map((part, i) => ({ label: part, path: part === "~" && i === 0 ? homeDir : (t.startsWith("~") ? root + "/" + parts.slice(1, i + 1).join("/") : "/" + parts.slice(0, i + 1).join("/")) }));
+  }, [at, homeDir]);
+  // Deep paths keep their first crumb and the last three; the ones between fold into one that goes to the nearest of them.
+  const shown = crumbs.length > 5 ? [crumbs[0]!, { label: "…", path: crumbs[crumbs.length - 4]!.path }, ...crumbs.slice(-3)] : crumbs;
+  const here = at ? short(at.path, homeDir, 44) : "";
+  const leaf = at ? at.path.split("/").filter(Boolean).pop() ?? "" : "";
+
+  return (
+    <div className="pk-pane pk-fade">
+      <header className="pk-strip">
+        <span className="pk-strip-title">New baba</span>
+        <span className="pk-gap" />
+        {loading && <Spinner />}
+      </header>
+      <div className="pk-path">
+        <nav className="pk-crumbs" aria-label="Folder">
+          {!crumbs.length && <span className="pk-crumb is-here">/</span>}
+          {shown.map((c, i) => (
+            <span key={c.path} className="pk-crumb-wrap">
+              {i > 0 && <span className="pk-crumb-sep">/</span>}
+              {c.label === "…" ? <button type="button" className="pk-crumb" onClick={() => walk(c.path)} title={tilde(c.path, homeDir)}>…</button>
+                : i === shown.length - 1 ? <span className="pk-crumb is-here">{c.label === "~" ? <Home /> : c.label}</span>
+                : <button type="button" className="pk-crumb" onClick={() => walk(c.path)} title={tilde(c.path, homeDir)}>{c.label === "~" ? <Home /> : c.label}</button>}
+            </span>
+          ))}
+        </nav>
+        <label className="pk-filter">
+          <Search />
+          <input ref={filterRef} value={filter} placeholder="Filter" aria-label="Filter folders" spellCheck={false} onChange={(e) => { setFilter(e.target.value); setActive(0); }} />
+        </label>
+      </div>
+      <ol ref={list} className={loading && at ? "pk-list pk-folders is-loading" : "pk-list pk-folders"} role="listbox" aria-label="Folders">
+        {!at && !error && [0, 1, 2, 3, 4].map((i) => <li key={i} className="pk-folder is-ghost"><span className="pk-folder-icon"><FolderGlyph /></span><span className="pk-ghost-line" style={{ width: `${30 + ((i * 17) % 35)}%` }} /></li>)}
+        {rows.map((r, i) => r.kind === "up" ? (
+          <li key=".." data-i={i} role="option" aria-selected={i === cur}>
+            <button type="button" className={i === cur ? "pk-folder is-active is-up" : "pk-folder is-up"} onClick={() => enter(i)} onMouseEnter={() => setActive(i)}>
+              <span className="pk-folder-icon"><Up /></span><span className="pk-folder-name">{tilde(r.path, homeDir) === "~" ? "Home" : r.path.split("/").filter(Boolean).pop() ?? "/"}</span><span className="pk-folder-note">up</span>
+            </button>
+          </li>
+        ) : (
+          <li key={r.d.path} data-i={i} role="option" aria-selected={i === cur}>
+            <button type="button" className={`pk-folder${i === cur ? " is-active" : ""}${r.d.baba ? " is-baba" : ""}`} onClick={() => enter(i)} onMouseEnter={() => setActive(i)}>
+              <span className="pk-folder-icon">{r.d.baba ? <BabaGlyph /> : <FolderGlyph />}</span>
+              <span className="pk-folder-name"><Marked text={r.d.name} words={words} /></span>
+              {r.d.known ? <span className="pk-pill is-known">remembered</span> : r.d.baba ? <span className="pk-pill">baba</span> : null}
+              <span className="pk-go"><Chevron /></span>
+            </button>
+          </li>
+        ))}
+        {at && rows.length === 0 && <li className="pk-none">{words.length ? <>No folder matches “{filter}”.</> : <>No folders in here. You can make the baba right here.</>}</li>}
+      </ol>
+      {error && <p className="pk-alert" role="alert">{error}</p>}
+      <footer className={`pk-dock${at?.known ? " is-known" : at?.baba ? " is-baba" : ""}`}>
+        <div className="pk-dock-line is-say">
+          <span className="pk-dock-icon">{at?.baba ? <BabaGlyph /> : <FolderGlyph />}</span>
+          <span className="pk-dock-text">
+            {!at ? "…" : at.known ? <>Voss already knows the baba in <span className="pk-here" title={at?.path}>{here}</span>.</>
+              : at.baba ? <>There is a baba in <span className="pk-here" title={at?.path}>{here}</span>. Remember it to open it here.</>
+              : <>A new baba goes in <span className="pk-here" title={at?.path}>{here}</span>, as <code>.baba/</code> beside what is there.</>}
+          </span>
+        </div>
+        <div className="pk-dock-line">
+          {at && !at.baba && <>
+            <label className="pk-field"><span>Name</span><input value={name} placeholder={slug(leaf) || "baba"} spellCheck={false} disabled={!!busy} onChange={(e) => setName(e.target.value)} onKeyDown={(e) => { if (e.key === "Enter") { e.preventDefault(); void act(); } }} /></label>
+            <label className="pk-field is-wide"><span>Title</span><input value={title} placeholder={name.trim() || slug(leaf) || "baba"} disabled={!!busy} onChange={(e) => setTitle(e.target.value)} onKeyDown={(e) => { if (e.key === "Enter") { e.preventDefault(); void act(); } }} /></label>
+          </>}
+          {busy && <span className="pk-busy"><Spinner />{busy}</span>}
+          <span className="pk-gap" />
+          <button type="button" className="pk-primary" disabled={!at || !!busy || loading} onClick={() => void act()}>
+            {!at ? "Make a baba here" : at.known ? "Open it" : at.baba ? "Remember this baba" : "Make a baba here"}
+            <kbd className="pk-kbd is-on-primary">⌘↵</kbd>
+          </button>
+        </div>
+      </footer>
+    </div>
+  );
+}
+
+/** A name with the filter's words marked in it. */
+function Marked({ text, words }: { text: string; words: string[] }) {
+  if (!words.length) return <>{text}</>;
+  const lower = text.toLowerCase();
+  const hit = new Array<boolean>(text.length).fill(false);
+  for (const w of words) { let i = lower.indexOf(w); while (i >= 0) { for (let k = i; k < i + w.length; k++) hit[k] = true; i = lower.indexOf(w, i + w.length); } }
+  const out: ReactNode[] = [];
+  let i = 0;
+  while (i < text.length) { const on = hit[i]; let j = i; while (j < text.length && hit[j] === on) j++; out.push(on ? <mark key={i}>{text.slice(i, j)}</mark> : text.slice(i, j)); i = j; }
+  return <>{out}</>;
+}

package/src/guide/add-a-desktop.mdx

@@ -0,0 +1,100 @@
+export const prompt = { kind: "skill", name: "add-a-desktop", description: "Give a babavoss baba a desktop: windows of apps under a bar of pills, a launcher that lists what is open and what can be, Lucide icons by name, sessions, paths, memory per window, and the desktopAsk another system uses to open one. Read before adding an app to the desktop, composing Desktop in interface.tsx, or navigating the page from a system." };
+
+# Add a desktop
+
+Every baba runs voss's shell: the desktop system, which voss adds to every baba as it adds `maker` and `promptware`, over the apps the baba declares in `baba({ apps })`. The interface gives each app its component; the page is voss's. Three nouns and one verb: a **app** is a kind the baba registers; a **window** is one instance of it in a session, at a path; the **session** shows one window, or nothing. The verb is `desktop-open`: it brings the window at that path to the front, else the app's current window, else makes one; asked for a `fresh` window, an app declared `many` gets another, any other app gives the one it has. The launcher, a link in an app, the page's address, the CLI and another system's ask all go through it.
+
+The page is a bar over one app. At the bar's far left the mark, the two eyes, opens the launcher; then a pill per open window, its icon at the left and the one in front filled; pointing at a pill turns its icon into the × that closes it, and a middle click closes it too, as it closes a browser tab; closing the one in front brings the pill to its left forward, else the one to its right. The launcher is the page's, not the state's: it shows while its search has focus, and while nothing is in front, since there is nothing else to show. The mark or Cmd/Ctrl K gives the search focus; a click on the launcher's empty space keeps it; choosing a row, Escape or the mark again takes it, and the launcher goes. It covers the page and changes nothing beneath: the bar's row becomes the search, and below it one column of rows, a palette: the icon, beginning where the search begins, then the label; what is open first, then every app under its group. One dot under the mark says which row is chosen, by the keys or the pointer, and glides between them. Typing ranks both by the words, a word at the start of a name first, and drops the groups. An app's row opens a fresh window of it, or brings the one it has to the front; a window's row brings it to the front, and pointing at it turns its icon into its ×. A browser tab shows one window at a time: a pill on the bar brings an open one to the front, the mark then a row opens another. Below the apps, under Sessions, the tab's other sessions and New session. A page inside a baba is that baba only; the last row, Leave, and the `voss` link before the title on the bar go back to the picker, voss's root page, which has no state: it lists the babas voss knows, one inside another under its parent, and New baba, the wizard that makes a baba in a folder or remembers one already there.
+
+```ts
+// .baba/index.ts: the apps, as data, in launcher order
+export default baba({
+  systems: [tasks, …],
+  apps: [
+    { key: "tasks", title: "Tasks", icon: "list-checks", group: "Work", many: true, systems: ["tasks"], routes: ["/", "/task/:id"] },
+  ],
+});
+```
+
+```tsx
+// .baba/apps/tasks.tsx: an app is a component, reading the state through the hooks
+import { route, type AppProps } from "babavoss/web";
+export function Tasks({ params, navigate, open, setTitle, memory, remember }: AppProps) {
+  /* the board, or the task params.id; navigate(route("/task/:id", { id })) opens one */
+}
+
+// .baba/interface.tsx: a component for every app, checked against the keys
+import { compose } from "babavoss/web";
+import type baba from "./index.ts";
+import { Tasks } from "./apps/tasks.tsx";
+export default compose<typeof baba>({ apps: { tasks: Tasks } });
+```
+
+An app missing from `compose`, or a component for an app the baba does not declare, is a type error. After the baba's apps come voss's own, under Voss: `maker` the specs run live, `state` the entities and resources, `contract` the actions and queries as forms, `promptware` the know-how, `settings` the theme. A baba never declares them; its interface may give one a component of its own to draw it otherwise, `compose<typeof baba>({ apps: { …, promptware: Mine } })`. A baba that declares no apps has one, `view`, which draws its interface whole. A baba whose interface fails to build or load still has its shell: its apps say why, voss's work. The old addresses, `/NAME/run`, `/inspect`, `/proofs`, open the app they became, unless the baba has an app by that name. The old form, `compose({ shell })`, still loads for one release, in the `view` app; a baba cannot declare apps and keep a desktop system of its own.
+
+An app's component receives `AppProps`: `{ session, window, path, route, params, active, memory, navigate, open, setTitle, remember }`. It never names an action: `navigate(path)` moves its own window, `open(app, path)` opens any app by the one rule, `setTitle(title)` names its window after what it shows, the pill's tooltip, `remember(key, value)` keeps a filter, a selection or a fold on its window, in the state, and `memory` reads it back. Windows stay mounted when hidden. A path begins with one `/`.
+
+## Addresses and routes
+
+The page's address is the window in front: `/NAME/APP/PATH`, the baba's name, the app's key, the window's path. `/NAME/APP` is the app at `/`, its home; `/NAME/` alone is the launcher. Arriving at an app's address opens it by the one rule, so a link, a bookmark, Back and Forward all land where they name, in the tab's session; arriving at `/NAME/` opens the launcher over whatever is in front, and the address stays until something is chosen. The address names what is shown, never the session: `?session=KEY` joins one, and the tab keeps it. The launcher's rows resume an app as it was left; an address is exact. An old `#desktop/SESSION/APP/PATH` link still opens, rewritten to the path.
+
+An app's `routes` are the paths its windows may be at: segments after one `/`, each a word, a `:name` for one segment, or last a `*` for the rest. One must take `/`. `desktop-open`, an ask and an address with a path no route takes answer an error, and the window stays; an app that declares no routes takes any path. The route that took the path, `/task/:id`, and its parameters, decoded, `{ id: "7" }`, come in `route` and `params`; the most specific route wins, a word before a name, a name before the rest, and a route that ends before the rest. A path is kept in one spelling, each segment encoded as `route` encodes it, so `/task/a b` and `/task/a%20b` are one window; `.` and `..` segments are refused. A window whose path the app's routes no longer take, after a change to them, goes home. `route("/task/:id", { id })`, from `babavoss` or `babavoss/web`, builds a path with each parameter encoded, so a system's ask and an app's link spell it the same way.
+
+A routed app is one component reading `params`, or a component per route, a system of views, checked against the routes it declares, every one and none other where the table is written inline; the route the shell matched picks the component:
+
+```tsx
+export default compose<typeof baba>({ apps: { tasks: { "/": Board, "/task/:id": Task } } });
+```
+
+Kinds of app, by how they use the path: a **view** declares no routes and ignores its path; a **routed** app declares its routes, one view per route or one component over them all; a **document** app is a routed app declared `many`, each window its own instance at its own path.
+
+An app's `systems` names the systems it shows, so the Maker offers it as a view of every spec that holds them (see `compose-an-interface`). An app's `icon` is a Lucide icon's name, as lucide.dev writes it: `list-checks`, `git-merge`. The desktop system reads its drawing once from the baba's own Lucide package, `lucide-static` if installed, else `lucide-react`, which the kit installs, and keeps it on the app in the state, so the bar and the launcher draw it; nothing is imported for it. A name the baba has no icon for, or no name, draws a small dot.
+
+## What the system owns
+
+- `desktopApp`, the catalog as declared, synced every round: an app no longer declared closes its windows everywhere. `desktopIcon` beside it: its icon's shapes, as read.
+- `desktopWindow`, one per instance, in the order opened: its session, its app, its path, its title, its `memory`.
+- `desktopSession`, one per session: the selected window and when it was last touched. A browser tab owns one: on load it takes the address's `?session=KEY`, else the one the tab had (its `sessionStorage`), else enters a new one, which the system names after a tree, `oak`, `ash`, `elm`. A link with `?session=KEY` joins a session, and two tabs on one key move together; the launcher lists the other sessions, to go to one or end it, and New session. A session with nothing open goes after a day untouched. The launcher and what is typed into it are the page's.
+- A call that names no session reaches the current session, the one last touched: a tab touches its session on load and on focus, so `voss baba desktop-open '{"app":"tasks","path":"/task/7"}'` lands in the tab last used. Name one to reach another.
+- `desktopSettings`, one resource: the theme, the same on every page.
+- Its contract, the same at the CLI, by MCP and in the page: `desktop-open`, `desktop-select`, `desktop-close`, `desktop-title`, `desktop-remember`, `desktop-enter`, `desktop-leave`, `desktop-settings` and the query `desktop-state`, which also lists every session. Read them with `voss baba`.
+
+## Opening an app from a system
+
+Never import the desktop's interface. Name the desktop in your `reads`, add its ask, `shell.desktopAsk`, to your own entity; the desktop answers beside it next round.
+
+```ts
+// a system that wants the page to show the task it just made
+import { system, s, route } from "babavoss";
+import { shell } from "babavoss/desktop";   // voss's desktop system
+
+export default system({
+  name: "tasks",
+  model: { task: { id: s.key(s.string()) } },
+  reads: [shell],
+}, (tasks, p) => [
+  p.action("task-make", {
+    summary: "make a task and show it",
+    args: { id: s.string() },
+    result: s.object({ entity: s.entity("task") }),
+    run: (w, { id }) => {
+      const e = w.spawn(tasks.task, { id });
+      w.add(e, shell.desktopAsk, { app: "tasks", path: route("/task/:id", { id }) });   // an ask, on your own entity
+      return { entity: e };
+    },
+  }),
+]);
+// next round, on e: desktopAnswer = { session: <entity> | null, error: string | null }
+```
+
+The ask takes `{ app, path?, fresh?, session? }`; an unknown app, a bad path or one no route takes answers an error, not a throw. See `systems-together` for how asks work.
+
+## Rules
+
+- The address records the window in front, `/NAME/APP/PATH`, with Back and Forward; opening the launcher from the page leaves no entry; pass `address={false}` for a desktop embedded in another page.
+- A baba's name is the first segment of its address, so `api`, `assets`, `view` and `ws`, the page's own, are not names a baba can take.
+- Cmd/Ctrl K opens the launcher; Cmd/Ctrl W or the front pill's × closes the window in front; Escape clears the search, then leaves the launcher; arrows move down the rows, Enter opens. The theme is `desktop-settings`, with no control in the launcher yet.
+- The shell inherits voss's theme tokens; the session's theme applies inside the desktop.
+- Reload keeps compatible desktop state and drops apps no longer declared; stopping the baba ends it with the rest of the state.
+- Prove an app's navigation like any system: a scenario that fires `desktop-open` and checks `desktop-state`.
+- The old spellings, `surfaces` and `SurfaceProps`, still work for one release; `dock` in the options is accepted and ignored.

package/src/guide/compose-an-interface.mdx

@@ -0,0 +1,84 @@
+export const prompt = { kind: "skill", name: "compose-an-interface", description: "Compose a babavoss baba's interface: interface.tsx, an app for each the baba declares, written as a component in .baba/apps/ that reads the state through hooks and acts with the hand, drawn the same over the live state and a simulated one in the Maker. Read before writing or changing interface.tsx or any app under .baba/apps/." };
+
+# Compose an interface
+
+Every view is an app: a plain React component in `.baba/apps/NAME.tsx`, reading the state through hooks that follow the rounds and acting through the hand. A system has no look of its own; its directory is `index.ts` and `spec.ts`. `interface.tsx` composes the components only, one for each app the baba declares in `baba({ apps })`; voss's shell, served at `/NAME/`, opens them as windows (see `add-a-desktop`), each a view into the one state. An interface reads what it shows and no more: the server sends a page only what its hooks asked for.
+
+```ts
+// .baba/index.ts: the apps, as data; `systems` names what each one shows
+export default baba({
+  systems: [tasks, pond],
+  apps: [
+    { key: "tasks", title: "Tasks", icon: "list-checks", group: "Work", systems: ["tasks"] },
+    { key: "pond", title: "Pond", icon: "fish", group: "Explore", systems: ["pond"] },
+  ],
+});
+```
+
+```tsx
+// .baba/apps/tasks.tsx
+import { select, useComponent, useCount, useHand, useQuery } from "babavoss/web";
+import { Button } from "@/ui/button";
+import tasks from "../systems/tasks/index.ts";
+
+const all = select(tasks.task).by(tasks.task, (a, b) => a.dir.localeCompare(b.dir));   // declared once, at module level
+
+function Row({ e }: { e: number }) {
+  const t = useComponent(e, tasks.task);          // wakes only when this task is written
+  return t ? <li>{t.dir}</li> : null;
+}
+export function TasksApp() {
+  const ids = useQuery(all);                       // the same array until a task comes, goes or moves
+  const n = useCount(all);
+  const hand = useHand();                          // undefined where the app may not act
+  return <main><h1>{n} tasks</h1><ul>{ids.map((e) => <Row key={e} e={e} />)}</ul>{hand && <Button onClick={() => hand.fire("refresh")}>Refresh</Button>}</main>;
+}
+```
+
+```tsx
+// .baba/interface.tsx: a component for every app, checked against the keys; the Maker is one of them
+import { compose, Maker, type AppProps } from "babavoss/web";
+import specs from "babavoss:specs";
+import type baba from "./index.ts";
+import { TasksApp } from "./apps/tasks.tsx";
+import { PondApp } from "./apps/pond.tsx";
+
+const apps = { tasks: TasksApp, pond: PondApp };
+function MakerApp({ path, navigate, setTitle }: AppProps) { return <Maker specs={specs} apps={apps} path={path} navigate={navigate} setTitle={setTitle} />; }
+export default compose<typeof baba>({ apps: { ...apps, maker: MakerApp } });
+```
+
+## Two ways to read
+
+- **`useBabaState(baba)`** gives `w`, a replica of the whole state at the latest round, with `w.query`, `w.get`, `w.has`, `w.count` and the change terms, `added(c)`, `changed(c)`, `removed(c)`, meaning what the last round moved, and `fire`. Every round re-renders the component. Right for a small baba, an app drawn whole, a debug page.
+- **The targeted hooks** each ask for one thing and wake only when it moves, so a page of them costs what it shows: `useQuery(select)` the ids a select answers; `useComponent(e, c)` one component of one entity, the same object until written; `useColumn(select, c)` one component of every member, for a layer drawn at once; `useCount(select)`; `useHas(e, c)`; `useAlive(e)`; `useResource(r)`; `useRound()`. Declare a `select(...)` once at module level, with `.where(fn)` and `.by(c, cmp)` on it, so the table knows which values can change the answer; one made in a render is a new one every time.
+- **`useBaba(baba)`** gives `fire`, `read` and `raw` without the state, for a page built on the targeted hooks. `fireIn` answers the round an action ran in, and `useSettled(round)` says when the page has seen it, so a row shows pending until its effect is in view.
+- `ready` is the first frame landed; `connected` the socket up, and down, calls still go over the API and the state waits. `useProbe()` is what following costs this window, round by round.
+
+## Any state: live, simulated, a frame
+
+The hooks read whatever state the app is shown over: the page's live store, the Maker's simulated state, or a fixed frame. An app that reads only through them, and acts only through `useBabaState().fire` or `useHand()`, draws the same in all three, so the one component is the app and its picture in the Maker.
+
+- **The hand.** `useHand()` answers `{ fire(name, args) }`, or undefined where the app may not act, so a control renders only when it can: `{hand && <Button onClick={() => hand.fire("feed")}>Feed</Button>}`. Live and in the Maker it fires into the state shown; without one the app is a picture.
+- **A state of your own.** To show an app over a replica, a sketch, a preview, a test, wrap it: `<AppState w={replica} hand={hand}>…</AppState>`; every hook inside reads `w`, and `useHand` answers `hand`, none when it is not given.
+- **Time in a spec is small.** `w.now` starts near zero; an app that shows times formats small numbers as seconds and large ones as clock time.
+
+## Apps in the Maker
+
+The Maker is an app like the others: `<Maker specs={specs} apps={apps} />`, the specs from `babavoss:specs` and the baba's apps. A spec open shows its model, its spec (the verdicts, run, step, scrub), and an app: one of the baba's apps drawn over the simulated state, with the hand acting on it, or the desktop with every app that fits, for a spec that has the desktop or is the whole baba. An app fits a spec when every system it names in `systems` is in that spec; an app that names none fits every spec. The person picks the app, and the pick is kept per spec. Name in `systems` every system the app draws, so the Maker offers it where it can draw.
+
+## An app draws objects
+
+Start from the Maker's model lens: every object the systems make is already drawn there as a card, with its attributes, what rides beside it, its links and its calls to action. An app is an arrangement of those: the yard board is version objects with issue and feature objects nested in their columns.
+
+## Rules
+
+- **Pixels come from the kit.** Import controls from `@/ui`: `import { Button } from "@/ui/button"`. `voss baba ui` lists what the kit has; `voss baba ui-add '{"names":["checkbox"]}'` brings a component from shadcn's registry. Lay out with Tailwind classes; color, type and space are the theme's tokens, `--primary`, `--muted-foreground`, `--border`, `--card`, `--success`, `--destructive`, `--warning`. The demo's hello app is the pattern: hooks, `useHand`, the kit, one component live and in the Maker.
+- **Read through the hooks only.** No fetching, nothing the state does not hold; what an app shows comes from the state it is shown over.
+- **Nothing the interface knows is its own.** Selection, filters, a remembered path: if two windows should agree on it, or a scenario should see it, it is a component in the state, written by an action. A text field's draft may stay in React state; a window's own state, its filter or its fold, goes to the desktop with `remember` (see `add-a-desktop`).
+- **Keys are entities**: `key={e}` on every row, so the DOM follows the entity across rounds and transitions read as motion.
+- **Fire actions, read queries.** The interface has no other way to move or ask the state, so what it does is what the CLI and an agent could do. `raw` is the inspector's.
+- **The desktop is optional.** A baba of several apps composes `Desktop` from `babavoss/web` as its shell; see `add-a-desktop`.
+- An app's markup may be tested with plain bun test beside it, `.baba/apps/NAME.test.tsx`; the systems' behaviour is proved in their specs (see `spec-a-system`).
+- An interface's build, load or render failure shows on its page. voss's own apps, the state, the contract, the Maker, stand without one, so a baba needs none to be used.
+- The old spellings, `view.tsx`, `view({ component })` and `compose({ shell })`, still load for one release, drawn whole in one app, `view`.

package/src/guide/index.ts

@@ -0,0 +1,13 @@
+// voss's own know-how for agents, given to every baba after its own: how to
+// write, prove and compose systems, how to draw the page as apps and give it
+// a desktop, and how to write promptware.
+import type { Prompt } from "../prompt/index.ts";
+import writeASystem from "./write-a-system.mdx";
+import reachOutside from "./reach-outside.mdx";
+import systemsTogether from "./systems-together.mdx";
+import composeAnInterface from "./compose-an-interface.mdx";
+import addADesktop from "./add-a-desktop.mdx";
+import writePromptware from "./write-promptware.mdx";
+import specASystem from "./spec-a-system.mdx";
+
+export const guide: readonly Prompt[] = [writeASystem, reachOutside, systemsTogether, specASystem, composeAnInterface, addADesktop, writePromptware];

package/src/guide/reach-outside.mdx

@@ -0,0 +1,112 @@
+export const prompt = { kind: "skill", name: "reach-outside", description: "Give a babavoss system the outside: requests and sources through the port (fs, http, exec, secrets), mirrors of a directory or an API, streams, and the on bindings that run them. Read before writing an effect, a source, or anything async in a system." };
+
+# Reach outside
+
+Nothing in a round touches the outside. A system asks for a job; the runtime runs it through the port, `ctx`, outside the round; what comes back lands as data in a later round. Two kinds of job:
+
+- an **effect** answers once: a request, a write, a command;
+- a **source** keeps answering: a directory watched, an API followed, a stream.
+
+A job is declared in the system's `effects` and bound by a piece in its list, `p.on(pages.fetch, { for, done, failed })`: which entities want it, and how its answers land.
+
+```ts
+import { system, effect, source, s, not, changed } from "babavoss";
+
+export default system({
+  name: "pages",
+  model: { page: { url: s.key(s.string()) }, body: { text: s.string() } },
+  effects: {
+    fetch: effect({
+      summary: "a page's text",
+      args: s.object({ url: s.string() }),
+      result: s.object({ text: s.string() }),
+      retry: 30_000,                                     // a failure runs again after this; omit to fail once
+      run: async ({ url }, ctx) => ({ text: (await ctx.http.fetch(url)).body }),
+    }),
+  },
+}, (pages, p) => [
+  // Every page without a body is fetched; the body lands beside it.
+  p.on(pages.fetch, {
+    for: (w) => w.query(pages.page, not(pages.body)).map((r) => [r.entity, { url: r.page.url }] as const),   // who wants it, every round
+    done: (w, e, r) => w.add(e!, pages.body, { text: r.text }),                                              // lands next round, as this system
+    failed: (w, e, error) => { /* write state that stops the want, or let retry run */ },
+  }),
+]);
+```
+
+## How jobs work
+
+- A binding is `p.on(effect, …)` of one of the system's own effects, listed with its other pieces: `for(w)`, `done(w, entity, result)`, `failed(w, entity, error)`. A `result` is typed by the effect's `result`. A binding has no name; another system's effect, or one effect bound twice, is refused.
+- `for` is asked every round: which entities want this effect, with what args. An entity already running it is skipped, and the round its answer lands it is skipped too. A want that `done` does not change is asked again.
+- `every: ms` runs the effect for the system itself (entity `null`) on a schedule. `w.run(effect, args, entity)` asks by hand, for the system's own effects only.
+- The job is a row in the state: `state` shows it, `follow` waits on it, despawning the entity cancels it and aborts `ctx.signal`. Hold no in-flight state in the system.
+- `repeat: false` marks an effect not safe to run twice: cut off by a crash, it lands once as failed, "interrupted".
+- Results are checked against `result`; a bad one lands as failed.
+- A job shows its `status`, `attempt` and last `error` in `state`. `w.settlement(entity)` is how the entity's last job ended, `{ effect, ok, error, at }`; `w.done(effect)` is this round's answers of one effect, for a step that wants them without a `done` binding. Both are read in the round the answer lands.
+
+## The port
+
+`ctx.fs` (`read`, `readBytes`, `write`, `list`, `stat`, `remove`, `mkdir`, `watch`), `ctx.http.fetch(url, { method, headers, body })`, `ctx.exec.run(program, args, { cwd, input, env })`, `ctx.secrets`, `ctx.env`, `ctx.signal`. Paths are inside the project only; a symlink out is refused. Never `process`, `Bun`, `fs` or `fetch` directly: the type guard refuses them, and the wall would too.
+
+## Processes
+
+- Use `ctx.exec.run(program, args, { cwd, input, env, timeout })` for a final `{ code, stdout, stderr }`. The default timeout is ten minutes, for `stream` too; `null` explicitly allows an unlimited lifetime. Collected output is capped at 8 MiB. A program may close stdin before reading all of `input`; its exit code still decides. Launch arguments and environment together are limited to 128 KiB.
+- Use `ctx.exec.stream` inside a source's `watch` for `started`, `stdout`, `stderr`, and `exit`. Chunks are `Uint8Array`s of at most 16 KiB, not protocol messages: decode with a streaming `TextDecoder` and keep incomplete messages inside `watch`. Readiness is the system's reading of output or an HTTP probe; yield progress or readiness events and read them with `w.events`. The started event's PID is for diagnostics only.
+- Set `interactive: true` to keep stdin open. The started event's `process` reference can be passed to `ctx.exec.write(reference, text)` by another effect in the same system and generation. `null` closes stdin. Serialize writes, each at most 16 KiB; a write is refused while initial input or another write is pending. An acknowledgement means bytes accepted by the pipe, not application completion, and cancellation can leave delivery uncertain.
+- The job owns the process. Job settlement or cancellation stops its executions; replacement waits for cleanup. Reload prepares the new code without running jobs, retires the old generation, waits for cleanup, then activates; a failed preparation leaves the old one running. References expire with their execution and never survive a reload: re-establish readiness, and treat saved URLs and references as history.
+- Run foreground programs. The macOS launchd runner and sentinel monitor each other and clean up their own process group after runtime, kernel, or either helper is lost. Simultaneous forced loss of both helpers is outside the guarantee. Daemonizing, changing groups, elevation, and externally installed services escape that scope; run installers in their foreground, noninteractive mode. Execution currently requires a macOS GUI login; other platforms refuse it.
+- Keep media bytes in files or network connections. Output delivery is bounded; output that cannot drain within five seconds after exit fails the execution. Coalesce progress instead of filling the baba's inbox.
+- For finite work, stop the want on completion. A source can set `repeat: false` like an effect; interruption then lands as failed. This neither disables configured retries nor proves that an external command did not already execute. Recover partial files and unknown outcomes in the system.
+
+## Sources: the outside as components
+
+A source with a `mirror` keeps one of this system's keyed components as a faithful copy of a slice of the outside. The runtime does the reconciling; you declare how to read the slice.
+
+```ts
+export default system({
+  name: "files",
+  model: {
+    project: { dir: s.key(s.string()) },
+    file: { path: s.key(s.string()), of: s.entity("project"), size: s.integer() },   // `of`: the job's entity, filled by the runtime
+  },
+  effects: {
+    files: source({
+      summary: "a project's files as the disk has them",
+      args: s.object({ dir: s.string() }),
+      mirror: "file",                                                                                                              // one of the model's components, by name
+      list: async ({ dir }, ctx) => (await ctx.fs.list(dir)).filter((e) => !e.dir).map((e) => ({ path: e.path, size: e.size })),   // the slice as it is
+      watch: async function* ({ dir }, ctx) {                                                                                      // its changes
+        for await (const c of ctx.fs.watch(dir)) yield "gone" in c ? { gone: c.path } : "resync" in c ? { changed: true } : { path: c.path, size: c.size };
+      },
+      every: 60_000,                                                                                                               // list again on a schedule too
+    }),
+  },
+}, (files, p) => [
+  p.on(files.files, { for: (w) => w.query(files.project).map((r) => [r.entity, { dir: r.project.dir }] as const) }),
+]);
+```
+
+- `mirror` names one of this system's components, as a string, checked against the model: a name the model does not have, or a `list` answering items of another shape, does not type-check.
+- Items are the component's values, put by the key field. Unchanged rows do not tick. Rows a listing did not name are taken away. `{ gone: key }` takes one; `{ changed: true }` lists again.
+- `list` + `every` with no `watch` is a poll. `list` + `watch` lists, then follows. The runtime lists again on a retry, a reload, a resync.
+- The system's own steps never write a mirrored component. Put what the system says about a file in a component beside it. React with `added(file)`, `changed(file)`, `removed(file)`.
+- A mirror kept per entity needs the `s.entity` field for the job's entity; keys must be unique within the component, so include what scopes them.
+- `for` is the set wanted: an entity that leaves it loses its watch, changed args restart it.
+
+A source without a mirror is a stream: `event` is the schema of what `watch` yields; every event lands in the next round; a step reads them with `w.events(effect)`, in order, for that round only.
+
+```ts
+effects: { tokens: source({ event: s.object({ text: s.string() }), watch: async function* ({ prompt }, ctx, last) { /* yield { text } */ } }) },
+// a step in chat's list:
+p.step("grow", (w) => { for (const { entity, event } of w.events(chat.tokens)) w.update(entity!, chat.draft, (d) => ({ text: d.text + event.text })); }),
+```
+
+`last` is the last event this job landed, for a stream that resumes after a failure. Big data stays in the job: write it with `ctx.fs.write` inside `watch` and yield progress.
+
+## Patterns
+
+- **Derive the want from state, never from a flag you set.** "every page without a body" asks once per page and stops when the body lands. On failure, write something (`missing`) that stops the want, or let `retry` handle a transient one.
+- **Echo of your own writes**: a system that writes files and mirrors the same directory sees its write come back; compare a hash you kept, or ignore `changed` on rows whose value you just wrote.
+- **Conflicts are state**: a row with both a fresh stamp from the disk and a pending `edit` is "they disagree"; a step decides, not a binding.
+- **Rate limits and queues live in `for`**: yield only as many entities as may run; the rest wait as visible, unanswered state.
+- **One binding for several sources**: a helper typed `(w: StateOf<typeof pages>, …)`, called from the `done` and `failed` of each source's binding.