shadok-ai 0.9.7 → 0.9.8

package/README.md

@@ -144,13 +144,16 @@ Enter to skip; you can add it later from the web UI).
   rename, change profile, mirror to Telegram, close — and closing it brings the
   card back. Desktop only: the agents column is hidden on phones.
 - **Guided tour** — on a browser's first visit, a welcome card explains what
-  shadok-ai is, then a spotlight walks the real controls: the agents column, an
-  agent's ⋯ menu, the toolbar, the quota dials. Skip and Escape end it at any
-  point; ⋯ → *Guided tour* replays it. A step whose target isn't on screen is
-  **dropped rather than faked**, so the phone (no agents column) and an empty
-  cockpit (no agent tab) get a shorter tour instead of a spotlight on nothing.
-  On a brand-new instance it comes **before** the sign-in card — being asked to
-  authorise an OAuth flow before you know what the thing is takes it backwards.
+  shadok-ai is, then a spotlight walks the real controls: the agents list, an
+  agent's ⋯ menu, scheduled prompts, the toolbar, the quota dials. Skip and
+  Escape end it at any point; ⋯ → *Guided tour* replays it. A step whose target
+  isn't on screen is **dropped rather than faked** — an empty cockpit has no
+  agent menu, so it gets a shorter tour instead of a spotlight on nothing. The
+  **phone gets the whole tour**, because a step can name the landmark on either
+  layout (the agents column *or* the channel picker) and is framed on whichever
+  one is rendered. On a brand-new instance it comes **before** the sign-in card
+  — being asked to authorise an OAuth flow before you know what the thing is
+  takes it backwards.
 - **A lead agent from the start** — an instance with no channel at all gets one:
   `general`, running the **Shadok-Boss** profile, in the launch directory and
   without a worktree. It is created at boot, or right after the first sign-in on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shadok-ai",
-  "version": "0.9.7",
+  "version": "0.9.8",
   "main": "dist/session.js",
   "scripts": {
     "test": "node --import tsx --test test/*.ts context/*/test/*.test.mjs",

package/public/tour-steps.js

@@ -13,6 +13,13 @@
  *
  * `target` is a CSS selector, an array of them (framed as one rectangle), or
  * null for the centred welcome card.
+ *
+ * An array is also how a step survives BOTH layouts: the phone and the desktop
+ * put the same landmark in different elements (the agents column becomes a
+ * `<select>`), and only one of the two is ever on screen. `unionRect` drops the
+ * absent one, so the group frames whichever exists. Before that, three of the
+ * six steps were silently filtered out on a phone — including every step that
+ * mentioned agents at all, i.e. the subject of the product.
  */
 export const TOUR_STEPS = [
   {
@@ -28,18 +35,34 @@ export const TOUR_STEPS = [
     id: "agents",
     title: "Your agents live here",
     body:
-      "Start one with “new agent”, and group them once there are a few. " +
-      "At the bottom, “Tweak Shadok-AI” starts an agent on the cockpit's own source — " +
-      "it delivers its work as a pull request.",
-    target: "#tabbar",
+      "Every agent gets its own git worktree and branch, so several never collide. " +
+      "Pick one here to follow it, and “＋ New agent” starts another. One of them is this " +
+      "cockpit's home agent: the only one that cannot be closed.",
+    // The column on desktop, the channel picker on a phone — never both at once.
+    //
+    // Which is also why this body says neither "at the top" nor "at the bottom",
+    // and no longer points at "Tweak Shadok-AI": those describe the COLUMN, and
+    // the phone's `<select>` holds one option per agent plus "＋ New agent" and
+    // nothing else. A tour that names a control the reader cannot find is the
+    // same failure as a spotlight on empty space, just harder to notice.
+    // (That Tweak is unreachable on a phone at all is a real gap — in the UI,
+    // not in the tour.)
+    target: ["#tabbar", "#chanSelect"],
   },
   {
     id: "tab",
     title: "Each agent has its own menu",
     body:
-      "The ⋯ on an agent's tab is where its controls live: mute it, reload it, " +
-      "rename it, change its profile, mirror it to Telegram, or close it.",
-    target: ".tab.active",
+      "This ⋯ holds an agent's controls: mute, reload, rename, change its profile, mirror it " +
+      "to a Telegram topic, or have it report to another agent when it finishes. " +
+      "“Context sent” shows exactly what shadok told it at spawn — and, except for the home " +
+      "agent, this is where you close it.",
+    // `#chanMenu`, NOT `.tab.active`. Two reasons, and the second is why it
+    // changed: it is literally the button this body tells you to press (the
+    // tab's own ⋯ opens the same menu), and it exists on BOTH layouts, whereas
+    // a phone has no `.tab` at all — so this step, and the schedule step below
+    // it, simply did not happen there.
+    target: "#chanMenu",
   },
   {
     // Deliberately its own stop, against this file's own "group landmarks"
@@ -53,24 +76,45 @@ export const TOUR_STEPS = [
       "“Schedule”, in that same ⋯ menu, pairs a recurring prompt with a shell check that runs " +
       "without the model. Silent check → nothing happened, the agent stays asleep at zero " +
       "tokens. Otherwise it wakes up holding the finding, and tells you here or on Telegram.",
-    target: ".tab.active",
+    target: "#chanMenu",
   },
   {
     id: "tools",
     title: "The toolbar",
-    // Named in the order the spotlight frames them, NOT drawn as glyphs: this
-    // body is set with textContent, so an inline SVG icon would show as raw
-    // markup — and spelling the buttons out as emoji (🔑/👤/🔔) drifts the
-    // moment those buttons stop being emoji, which is exactly what happened.
+    // Not drawn as glyphs: this body is set with textContent, so an inline SVG
+    // icon would show as raw markup — and spelling the buttons out as emoji
+    // (🔑/👤/🔔) drifted the moment those buttons stopped being emoji.
+    //
+    // And no longer "left to right" either, which drifted the same way for the
+    // same reason: adding the ledger between secrets and profiles shifted every
+    // later name onto the wrong icon, so a reader counting along the row was
+    // told the ledger was "profiles". An order is a claim about the DOM that
+    // no test here can hold; a list of functions is not.
     body:
-      "Left to right: secrets injected into agents that need them, profiles " +
-      "(role, guardrails, model), Telegram settings, and the notification sound. " +
-      "The ⋯ holds the diff of what an agent changed — and replays this tour.",
+      "The secret vault injected into agents that need it, the shared ledger of what your " +
+      "agents have already resolved, profiles (role, guardrails, model), Telegram, and the " +
+      "notification sound. On a narrow screen they fold into the ⋯ — which also holds the " +
+      "diff of an agent's work, the palette, and replays this tour.",
     // NOT `.hdr-tools`, which is `display: contents` on desktop and therefore
     // generates no box at all — its rect is all zeros, so the step would have
     // been dropped as "not visible" on the very layout where the toolbar is
     // most obvious. Framing the buttons themselves works on both layouts.
-    target: ["#secretsBtn", "#profilesBtn", "#telegramBtn", "#muteNotif", "#moreBtn", "#starBtn"],
+    //
+    // Every tool is listed, including the ones `reflowHeaderTools` parks inside
+    // the closed ⋯ menu on a phone: those measure {0,0,0,0} and `unionRect`
+    // now drops them, so the group frames exactly what is on screen. Listing
+    // only some of them was the older bug in the other direction — `#usersBtn`
+    // sits left of `#secretsBtn` and stayed outside the spotlight.
+    target: [
+      "#usersBtn",
+      "#secretsBtn",
+      "#ledgerBtn",
+      "#profilesBtn",
+      "#telegramBtn",
+      "#muteNotif",
+      "#moreBtn",
+      "#starBtn",
+    ],
   },
   {
     id: "quota",
@@ -78,7 +122,8 @@ export const TOUR_STEPS = [
     body:
       "Your 5h and 7d subscription usage. The needle's centre is the pace that would " +
       "spend the window exactly on time, so leaning right means you're burning faster. " +
-      "The version number next to the cockpit's name opens updates and the permission mode.",
+      "To the left, the cockpit's name is yours to change, and the version beside it opens " +
+      "updates and the permission mode.",
     target: ["#quota5h", "#quota7d"],
   },
 ];
@@ -93,13 +138,26 @@ export function visibleSteps(steps, isVisible) {
  *
  * Null rather than a zero rect: a caller that framed {0,0,0,0} would put the
  * spotlight on the page's top-left corner instead of skipping the step.
+ *
+ * EMPTY RECTS ARE NOT POINTS AT THE ORIGIN, and treating them as such is what
+ * broke the toolbar step on every phone. `reflowHeaderTools` moves five of the
+ * eight tool buttons into the closed ⋯ menu below 640px; a hidden element
+ * measures {0,0,0,0}, so the union's `Math.min` pinned top and left to zero and
+ * the spotlight stretched from the viewport's corner across the header —
+ * framing the brand, the version and both gauges while the body described
+ * buttons that were not on screen at all. Same family as the `.hdr-tools`
+ * zero-rect trap noted above, except that one dropped the step honestly and
+ * this one kept it and lied. Dropping the empty ones here means a group target
+ * frames whatever part of it is actually rendered, and yields null — hence a
+ * skipped step — only when none of it is.
  */
 export function unionRect(rects) {
-  if (!rects || !rects.length) return null;
-  const top = Math.min(...rects.map((r) => r.top));
-  const left = Math.min(...rects.map((r) => r.left));
-  const bottom = Math.max(...rects.map((r) => r.top + r.height));
-  const right = Math.max(...rects.map((r) => r.left + r.width));
+  const real = (rects ?? []).filter((r) => r && r.width > 0 && r.height > 0);
+  if (!real.length) return null;
+  const top = Math.min(...real.map((r) => r.top));
+  const left = Math.min(...real.map((r) => r.left));
+  const bottom = Math.max(...real.map((r) => r.top + r.height));
+  const right = Math.max(...real.map((r) => r.left + r.width));
   return { top, left, width: right - left, height: bottom - top };
 }