feat(settings,docs): vault subpath becomes the chats folder, panel screenshots in the readme

Same two misses as the calendar's: the four-frame watch stopped before
Obsidian hid its navbar - a second move of the ground, after the keyboard's
own - and a trigger that arrived while a watch was running was dropped rather
than restarting it. The watch now needs twelve steady frames, restarts on
every trigger, and listens to Obsidian's Capacitor keyboard events too.

README.md

@@ -7,6 +7,10 @@ Two things:
 - **The panel**: Beaver's conversations next to your notes - the master thread, branches, deep chats - with the live tree of tool calls and subagents, the composer, and the same actions the admin has (branch with a seed, return a branch to Telegram or hide it, the memory flag, close with a digest). A narrow sidedock column, a full tab, or the phone screen. It follows the active note's `conversation_id` unless you pin it.
 - **Send the current note** to Beaver's markdown frontend (`POST /chat/stream`) and stream the agent's reply back into the buffer.
 
+![The panel as a tab: the conversation rail on the left, the master thread with its tool calls on the right](docs/panel-tab.webp)
+
+![The panel as a column in the right sidedock, next to the note](docs/panel-column.webp)
+
 ## Commands
 
 - **Beaver: Open panel in a tab** - the wide layout with the conversation rail on the left (also the ribbon icon).
@@ -20,7 +24,7 @@ The UI is `beaver-gateway/ui/src/lib/panel`, compiled into this plugin by `esbui
 
 Theme: `src/tailwind.css` maps the panel's tokens onto Obsidian's variables on `.beaver-root`, exactly as beaver-calendar does with `.bcal-root` - the app's font, accent, radii and the current theme, light or dark. Menus and dialogs portal to a `.beaver-root.beaver-portal` layer on `body`, above the sidedocks.
 
-Markdown in the thread goes through Obsidian's `MarkdownRenderer`: `[[links]]` open the note, external links open the browser. A deep chat's row offers **Open note** (its markdown binding, under the vault subpath).
+Markdown in the thread goes through Obsidian's `MarkdownRenderer`: `[[links]]` open the note, external links open the browser. A deep chat's row offers **Open note** (its markdown binding, under the chats folder).
 
 Layout: below 48rem of panel width the conversation switcher sits in the header (kind, title, live dot, follow toggle); wider than that the grouped rail (master, branches, deep chats, jobs) sits on the left. Right-click a row for its actions; on touch the `…` button is always visible. `↑`/`↓` walk the rows, `/` jumps to the search, `⌘↩` sends.
 
@@ -29,7 +33,7 @@ Layout: below 48rem of panel width the conversation switcher sits in the header
 - **Base URL** - markdown frontend root, e.g. `https://host/md`.
 - **API origin** - where `/api/…` lives; empty derives it from the base URL (`…/md` → `…`).
 - **Bearer token** - `messages` scope for sending, `api` scope for the panel (or a `*` bootstrap token).
-- **Vault subpath** - the folder in this vault that maps to the gateway's vault root.
+- **Chats folder** - the folder in this vault where the deep chats live, the one the gateway's markdown frontend writes to. Paths the gateway hands out are relative to it.
 
 Changing settings remounts open panels.
 

preview/entry.ts

@@ -54,11 +54,11 @@ async function main(): Promise<void> {
   mount(App, {
     props: {
       app: app as never,
+      chatsFolder: () => "💬 чаты",
       client: scene === "offline" ? null : client,
       component: new Component() as never,
       onOpenSettings: () => console.log("settings"),
       state,
-      vaultSubpath: () => "💬 чаты",
     },
     target: document.getElementById("app") as HTMLElement,
   });

preview/fake-client.ts

@@ -8,7 +8,12 @@ import type {
 
 const MINUTE = 60_000;
 const HOUR = 60 * MINUTE;
-const now = Date.now();
+// Anchored inside the day rather than at the wall clock: the fixtures are
+// spread over hours, and a run just after midnight would push half of them
+// into yesterday and empty the "Today" group the rail is checked against.
+const wall = new Date();
+const now =
+  wall.getHours() < 12 ? new Date(wall).setHours(12, 0, 0, 0) : wall.getTime();
 const ago = (ms: number) => new Date(now - ms).toISOString();
 
 export const MASTER = "c1master0000";

src/inset.ts

@@ -0,0 +1,47 @@
+/**
+ * How much of a leaf's bottom is covered by something the operator cannot
+ * move: Obsidian's desktop status bar, a phone's navbar (which paints over a
+ * leaf rather than shortening it), and the software keyboard, which shrinks
+ * the visual viewport while the layout keeps its full height.
+ *
+ * Pure on purpose - the view feeds it live rectangles, the tests feed it the
+ * numbers a phone actually reports.
+ */
+
+export interface Rect {
+  bottom: number;
+  height: number;
+  left: number;
+  right: number;
+  top: number;
+}
+
+export interface Visible {
+  /** `visualViewport.height`: what is left once the keyboard is up. */
+  height: number;
+  /** `visualViewport.offsetTop`: where the visible area starts. */
+  offsetTop: number;
+}
+
+export function insetFor(
+  leaf: Rect,
+  bars: Rect[],
+  visible: Visible | null
+): number {
+  if (leaf.height <= 0) {
+    return 0;
+  }
+  let overlap = 0;
+  for (const bar of bars) {
+    // A bar that does not sit over this leaf horizontally covers nothing of
+    // it - the desktop status bar next to a left-hand sidedock, say.
+    if (bar.height > 0 && bar.left < leaf.right && bar.right > leaf.left) {
+      overlap = Math.max(overlap, leaf.bottom - bar.top);
+    }
+  }
+  if (visible) {
+    const floor = visible.offsetTop + visible.height;
+    overlap = Math.max(overlap, leaf.bottom - floor);
+  }
+  return Math.max(0, Math.round(overlap));
+}

src/main.ts

@@ -230,7 +230,16 @@ export default class BeaverPlugin extends Plugin {
   }
 
   async loadSettings(): Promise<void> {
-    this.settings = { ...DEFAULT_SETTINGS, ...(await this.loadData()) };
+    const stored = ((await this.loadData()) ??
+      {}) as Partial<BeaverSettings> & {
+      vaultSubpath?: string;
+    };
+    // The setting used to be called "vault subpath"; carry the value over.
+    const { vaultSubpath, ...rest } = stored;
+    this.settings = { ...DEFAULT_SETTINGS, ...rest };
+    if (vaultSubpath && !rest.chatsFolder) {
+      this.settings.chatsFolder = vaultSubpath;
+    }
   }
 
   async saveSettings(): Promise<void> {
@@ -431,16 +440,16 @@ export default class BeaverPlugin extends Plugin {
   }
 
   private gatewayFilename(file: TFile): string | null {
-    const subpath = this.settings.vaultSubpath;
+    const folder = this.settings.chatsFolder;
-    if (!subpath) {
+    if (!folder) {
       return file.path;
     }
-    const prefix = `${subpath}/`;
+    const prefix = `${folder}/`;
-    if (file.path === subpath || file.path.startsWith(prefix)) {
+    if (file.path === folder || file.path.startsWith(prefix)) {
       return file.path.slice(prefix.length);
     }
     new Notice(
-      `Beaver: file ${file.path} is outside the configured vault subpath (${subpath})`,
+      `Beaver: file ${file.path} is outside the chats folder (${folder})`,
       8000
     );
     return null;

src/settings.ts

@@ -5,18 +5,20 @@ import type BeaverPlugin from "./main";
 export interface BeaverSettings {
   apiBaseUrl: string;
   baseUrl: string;
+  // Folder in this vault where the deep chats live: the gateway's markdown
+  // frontend reads and writes there, so paths it hands out are relative to it.
+  chatsFolder: string;
   token: string;
-  vaultSubpath: string;
 }
 
 export const DEFAULT_SETTINGS: BeaverSettings = {
   apiBaseUrl: "",
   baseUrl: "http://localhost:62993",
+  chatsFolder: "",
   token: "",
-  vaultSubpath: "",
 };
 
-export function normalizeSubpath(raw: string): string {
+export function normalizeFolder(raw: string): string {
   return raw.trim().replace(/^\/+|\/+$/g, "");
 }
 
@@ -93,17 +95,18 @@ export class BeaverSettingsTab extends PluginSettingTab {
       });
 
     new Setting(containerEl)
-      .setName("Vault subpath")
+      .setName("Chats folder")
       .setDesc(
-        "Folder in this Obsidian vault that maps to the gateway's vault root. " +
+        "Folder in this vault where the deep chats live - the one the gateway's " +
-          "Leave empty if the two vault roots match. Example: `💬 чаты`."
+          "markdown frontend writes to. Leave empty if the chats sit at the vault root. " +
+          "Example: `💬 чаты`."
       )
       .addText((text) =>
         text
           .setPlaceholder("")
-          .setValue(this.plugin.settings.vaultSubpath)
+          .setValue(this.plugin.settings.chatsFolder)
           .onChange(async (value) => {
-            this.plugin.settings.vaultSubpath = normalizeSubpath(value);
+            this.plugin.settings.chatsFolder = normalizeFolder(value);
             await this.plugin.saveSettings();
           })
       );

src/tailwind.css

@@ -201,6 +201,12 @@
   cursor: pointer;
 }
 
+/* A grid button centres by `place-items`, which the rule above would override
+   for its inline axis: an icon-only button ends up pinned to its left edge. */
+.beaver-root.beaver-root button:is(.grid, .inline-grid) {
+  justify-content: initial;
+}
+
 .beaver-root.beaver-root button:hover {
   background: transparent;
 }

src/ui/app.svelte

@@ -14,14 +14,14 @@
 
   interface Props {
     app: ObsidianApp;
+    chatsFolder: () => string;
     client: ApiClient | null;
     component: Component;
     onOpenSettings: () => void;
     state: PanelState;
-    vaultSubpath: () => string;
   }
 
-  let { app, client, component, onOpenSettings, state, vaultSubpath }: Props =
+  let { app, client, component, onOpenSettings, state, chatsFolder }: Props =
     $props();
 
   // Menus hang off body, not off the view: Obsidian's sidedocks paint above
@@ -41,9 +41,9 @@
   const host = providePanelHost({
     ...obsidianHost({
       app,
+      chatsFolder,
       component,
       sourcePath: () => state.sourcePath,
-      vaultSubpath,
     }),
     cache,
   });
@@ -58,6 +58,7 @@
       <PanelShell
         {client}
         companion={state.companion}
+        fallbackToMaster
         {index}
         onOpenFile={(path) => host.openNote?.(`мета/бобер/${path}`)}
         showFollow

src/ui/host.ts

@@ -4,11 +4,12 @@ import type { PanelHost } from "$lib/panel/host";
 
 export interface HostOptions {
   app: App;
+  // Folder in this vault that maps to the gateway's vault root.
+  // Where the deep chats live in this vault; gateway paths are relative to it.
+  chatsFolder: () => string;
   component: Component;
   // The note the panel currently follows; link resolution starts from it.
   sourcePath: () => string;
-  // Folder in this vault that maps to the gateway's vault root.
-  vaultSubpath: () => string;
 }
 
 // The Obsidian side of the panel: markdown through the app's own renderer,
@@ -47,8 +48,8 @@ export function obsidianHost(options: HostOptions): PanelHost {
       window.open(target);
     },
     openNote(path) {
-      const subpath = options.vaultSubpath();
+      const folder = options.chatsFolder();
-      const full = subpath ? `${subpath}/${path}` : path;
+      const full = folder ? `${folder}/${path}` : path;
       app.workspace.openLinkText(full, "", false).catch(() => undefined);
     },
     touch: Platform.isMobile,

src/view.ts

@@ -1,12 +1,31 @@
 import type { ViewStateResult, WorkspaceLeaf } from "obsidian";
 import { ItemView, TFile } from "obsidian";
 import { mount, unmount } from "svelte";
+import type { Rect } from "./inset";
+import { insetFor } from "./inset";
 import type BeaverPlugin from "./main";
 import { PanelState } from "./state.svelte";
 import App from "./ui/app.svelte";
 
 export const VIEW_TYPE_PANEL = "beaver-panel";
 
+// Bars that paint over a leaf instead of shortening it. On a phone the navbar
+// sits under every view, including the one filling the screen.
+const BOTTOM_BARS = [".status-bar", ".mobile-navbar", ".mobile-toolbar"];
+
+// The keyboard and the navbar both animate, and Obsidian hides the navbar
+// *after* the keyboard is up: the inset is re-measured every frame until the
+// reading has held still long enough to outlast both moves.
+const STEADY_FRAMES = 12;
+
+/** Obsidian's Capacitor keyboard events on mobile; absent on the desktop. */
+const KEYBOARD_EVENTS = [
+  "keyboardWillShow",
+  "keyboardDidShow",
+  "keyboardWillHide",
+  "keyboardDidHide",
+] as const;
+
 interface SavedState {
   follow?: unknown;
   selected?: unknown;
@@ -19,6 +38,7 @@ export class PanelView extends ItemView {
   readonly state = new PanelState();
   private readonly plugin: BeaverPlugin;
   private root: Record<string, unknown> | null = null;
+  private settling: number | null = null;
 
   constructor(leaf: WorkspaceLeaf, plugin: BeaverPlugin) {
     super(leaf);
@@ -75,29 +95,98 @@ export class PanelView extends ItemView {
         }
       })
     );
-    this.registerEvent(this.app.workspace.on("resize", () => this.inset()));
+    this.registerEvent(this.app.workspace.on("resize", () => this.settle()));
     this.registerEvent(
-      this.app.workspace.on("layout-change", () => this.inset())
+      this.app.workspace.on("layout-change", () => this.settle())
     );
+    // The keyboard resizes the visual viewport only: no workspace event
+    // fires, so the composer would stay behind it without these two.
+    const vv = window.visualViewport;
+    if (vv) {
+      const onViewport = () => this.settle();
+      vv.addEventListener("resize", onViewport);
+      vv.addEventListener("scroll", onViewport);
+      this.register(() => {
+        vv.removeEventListener("resize", onViewport);
+        vv.removeEventListener("scroll", onViewport);
+      });
+    }
+    // Focus opens the keyboard, blur closes it; both animate, and on the way
+    // out the navbar comes back, so the leaf has to be re-measured after.
+    this.registerDomEvent(this.contentEl, "focusin", () => this.settle());
+    this.registerDomEvent(this.contentEl, "focusout", () => this.settle());
+    // Obsidian's own keyboard events (Capacitor, mobile only) fire before the
+    // animation and again as the navbar returns, which visualViewport alone
+    // does not always report.
+    for (const name of KEYBOARD_EVENTS) {
+      const onKeyboard = () => this.settle();
+      window.addEventListener(name, onKeyboard);
+      this.register(() => window.removeEventListener(name, onKeyboard));
+    }
     this.follow(this.app.workspace.getActiveFile());
     this.plugin.views.add(this);
     this.mountApp();
-    requestAnimationFrame(() => this.inset());
+    this.settle();
     return Promise.resolve();
   }
 
-  // Obsidian's status bar floats over the bottom-right of the workspace; a
+  /**
-  // leaf that reaches down there gets padding so the composer stays clear.
+   * Re-measure until the viewport stops moving. The keyboard animates both
-  private inset(): void {
+   * ways and Obsidian hides its navbar while it is up, so a fixed delay lands
-    const bar = document.querySelector<HTMLElement>(".status-bar");
+   * mid-animation; a frame loop that stops once two readings agree does not
-    const box = this.contentEl.getBoundingClientRect();
+   * care how long the animation takes, or whether any event fires at all -
-    let overlap = 0;
+   * which is the case in a sidedock drawer.
-    if (bar && box.height > 0) {
+   */
-      const b = bar.getBoundingClientRect();
+  private settle(): void {
-      const crosses = b.left < box.right && b.right > box.left;
+    let last = Number.NaN;
-      overlap = crosses ? Math.max(0, box.bottom - b.top) : 0;
+    let steady = 0;
+    // A fresh trigger restarts the watch rather than being dropped: the navbar
+    // coming back is a second move, after the first one has settled.
+    if (this.settling !== null) {
+      cancelAnimationFrame(this.settling);
     }
-    this.contentEl.style.setProperty("--beaver-inset-bottom", `${overlap}px`);
+    const tick = () => {
+      const floor = this.inset();
+      steady = floor === last ? steady + 1 : 0;
+      last = floor;
+      if (steady >= STEADY_FRAMES) {
+        this.settling = null;
+        return;
+      }
+      this.settling = requestAnimationFrame(tick);
+    };
+    this.settling = requestAnimationFrame(tick);
+    this.register(() => {
+      if (this.settling !== null) {
+        cancelAnimationFrame(this.settling);
+        this.settling = null;
+      }
+    });
+  }
+
+  // Whatever floats over the bottom of this leaf, measured rather than
+  // guessed. Returns the inset it wrote, so the settle loop can tell when the
+  // reading stops changing; the arithmetic itself lives in ``inset.ts``.
+  private inset(): number {
+    const box = this.contentEl.getBoundingClientRect();
+    if (box.height <= 0) {
+      return Number.NaN;
+    }
+    const bars: Rect[] = [];
+    for (const selector of BOTTOM_BARS) {
+      const node = document.querySelector<HTMLElement>(selector);
+      if (node && node.offsetParent !== null) {
+        bars.push(node.getBoundingClientRect());
+      }
+    }
+    const vv = window.visualViewport;
+    const inset = insetFor(
+      box,
+      bars,
+      vv ? { height: vv.height, offsetTop: vv.offsetTop } : null
+    );
+    this.contentEl.style.setProperty("--beaver-inset-bottom", `${inset}px`);
+    return inset;
   }
 
   async onClose(): Promise<void> {
@@ -142,11 +231,11 @@ export class PanelView extends ItemView {
     this.root = mount(App, {
       props: {
         app: this.app,
+        chatsFolder: () => this.plugin.settings.chatsFolder,
         client: this.plugin.apiClient(),
         component: this,
         onOpenSettings: () => this.plugin.openSettings(),
         state: this.state,
-        vaultSubpath: () => this.plugin.settings.vaultSubpath,
       },
       target: this.contentEl,
     });

t/cdp-eval.ts

@@ -0,0 +1,35 @@
+// Evaluate an expression inside a running Obsidian started with
+// --remote-debugging-port. Usage: bun t/cdp-eval.ts <port> "<js expression>"
+const [port, expression] = process.argv.slice(2);
+const targets = (await (
+  await fetch(`http://localhost:${port}/json`)
+).json()) as {
+  type: string;
+  title: string;
+  webSocketDebuggerUrl: string;
+}[];
+const page = targets.find((t) => t.type === "page");
+if (!page) {
+  throw new Error("no page target");
+}
+const ws = new WebSocket(page.webSocketDebuggerUrl);
+await new Promise((resolve) => ws.addEventListener("open", resolve));
+const reply = new Promise<string>((resolve) => {
+  ws.addEventListener("message", (event) => {
+    const data = JSON.parse(String(event.data));
+    if (data.id === 1) {
+      resolve(
+        JSON.stringify(data.result?.result?.value ?? data.result ?? data)
+      );
+    }
+  });
+});
+ws.send(
+  JSON.stringify({
+    id: 1,
+    method: "Runtime.evaluate",
+    params: { awaitPromise: true, expression, returnByValue: true },
+  })
+);
+console.log(await reply);
+ws.close();

tests/inset.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import type { Rect } from "../src/inset";
+import { insetFor } from "../src/inset";
+
+const rect = (over: Partial<Rect> = {}): Rect => ({
+  bottom: 780,
+  height: 780,
+  left: 0,
+  right: 390,
+  top: 0,
+  ...over,
+});
+
+// A phone: 780 tall, a 56px navbar over the bottom, 340px of keyboard.
+const NAVBAR = rect({ bottom: 780, height: 56, top: 724 });
+
+describe("insetFor", () => {
+  it("clears nothing when the leaf stands alone", () => {
+    expect(insetFor(rect(), [], null)).toBe(0);
+  });
+
+  it("clears the navbar that paints over the leaf", () => {
+    expect(insetFor(rect(), [NAVBAR], null)).toBe(56);
+  });
+
+  it("clears the keyboard, which shortens no layout", () => {
+    expect(insetFor(rect(), [], { height: 440, offsetTop: 0 })).toBe(340);
+  });
+
+  it("takes the deeper of the two rather than their sum", () => {
+    // While the keyboard is up the navbar is behind it: adding them would
+    // push the composer twice as far as it has to go.
+    expect(insetFor(rect(), [NAVBAR], { height: 440, offsetTop: 0 })).toBe(340);
+  });
+
+  it("comes back to the navbar once the keyboard goes", () => {
+    expect(insetFor(rect(), [NAVBAR], { height: 780, offsetTop: 0 })).toBe(56);
+  });
+
+  it("ignores a bar that sits beside the leaf, not over it", () => {
+    // The desktop status bar floats bottom-right; a left-hand sidedock never
+    // reaches it.
+    const sidedock = rect({ right: 300 });
+    const statusBar = rect({
+      bottom: 780,
+      height: 20,
+      left: 700,
+      right: 980,
+      top: 760,
+    });
+    expect(insetFor(sidedock, [statusBar], null)).toBe(0);
+  });
+
+  it("measures from where the visible area starts, not from zero", () => {
+    // iOS scrolls the page up under the keyboard instead of resizing it.
+    expect(insetFor(rect(), [], { height: 440, offsetTop: 100 })).toBe(240);
+  });
+
+  it("says nothing about a leaf with no height yet", () => {
+    expect(insetFor(rect({ bottom: 0, height: 0 }), [NAVBAR], null)).toBe(0);
+  });
+
+  it("never returns a negative inset", () => {
+    const short = rect({ bottom: 300, height: 300 });
+    expect(insetFor(short, [], { height: 780, offsetTop: 0 })).toBe(0);
+  });
+});

tests/smoke.mjs

@@ -137,11 +137,11 @@ const target = dom.window.document.body;
 const instance = mount(App, {
   props: {
     app,
+    chatsFolder: () => "💬 чаты",
     client,
     component: new Component(),
     onOpenSettings: () => {},
     state,
-    vaultSubpath: () => "💬 чаты",
   },
   target,
 });
@@ -191,6 +191,23 @@ check(
   text().includes("Xiaomi Mi Blaster")
 );
 
+// Nothing picked - the panel just opened on a phone - lands on the master
+// rather than on a prompt to pick something.
+state.selected = null;
+flushSync();
+await settle();
+flushSync();
+check(
+  "with nothing picked it falls back to the master",
+  state.selected === MASTER,
+  String(state.selected)
+);
+state.selected = BRANCH_BLASTER;
+flushSync();
+await settle();
+flushSync();
+check("an explicit pick still wins", state.selected === BRANCH_BLASTER);
+
 const composer = target.querySelector("textarea");
 check("composer is there", composer !== null);
 if (composer) {

tests/styles.test.ts

@@ -89,4 +89,12 @@ describe("cascade against Obsidian", () => {
     expect(source).not.toMatch(/@import "tailwindcss"\s*[;l]/);
     expect(source).not.toMatch(/@import\s+"tailwindcss\/preflight/);
   });
+
+  // Obsidian's own `button` rules are what the reset answers, but a grid
+  // button must keep centring itself or an icon-only one drifts left.
+  it("leaves grid buttons to their own placement", () => {
+    expect(source).toMatch(
+      /button:is\(\.grid, \.inline-grid\) \{\s*justify-content: initial/
+    );
+  });
 });