diff --git a/README.md b/README.md
index 7b0c8a8..788423e 100644
--- a/README.md
+++ b/README.md
@@ -57,6 +57,27 @@ If you want to contribute or develop the plugin:
 - Server starts automatically when you open the panel
 
 
+## How it works (OpenCode 2.x)
+
+OpenCode 2 changed both the shape of its web app and its HTTP API. The plugin now:
+
+- hands the server a password via `OPENCODE_SERVER_PASSWORD` and authenticates
+  every API call with HTTP Basic (`opencode:<password>`), because 2.x requires
+  authentication for `/api/*`;
+- opens the app at `<server>/server/<serverKey>/session/<id>`, where
+  `<serverKey>` is the base64url encoding of the server URL - the old
+  `/<base64-directory>` path is no longer a valid route (it made the app throw
+  `Unrecognised route!` / `Cannot read properties of undefined (reading 'type')`);
+- creates the session for the vault, so file tree, `@`-mentions, terminal and git
+  are scoped to it;
+- embeds the app in an Electron `<webview>` instead of an `<iframe>`: the app
+  keeps its known servers (url + password) in `localStorage`, which can only be
+  written from inside the guest, and the pairing-link cookie is `SameSite=Lax`
+  and therefore never sent from an embedded frame;
+- talks to the API through `node:http` rather than `fetch`, because the
+  renderer's `fetch` is subject to CORS and OpenCode sends no
+  `access-control-allow-origin` for the `app://obsidian.md` origin.
+
 ## Settings
 
 ### Custom Command Mode
diff --git a/src/client/OpenCodeClient.ts b/src/client/OpenCodeClient.ts
index 716b2a7..02a3667 100644
--- a/src/client/OpenCodeClient.ts
+++ b/src/client/OpenCodeClient.ts
@@ -1,27 +1,10 @@
-type OpenCodePart = {
-  id: string;
-  messageID: string;
-  sessionID: string;
-  type: string;
-  text?: string;
-  ignored?: boolean;
-  synthetic?: boolean;
-  metadata?: Record<string, unknown>;
-  time?: {
-    start: number;
-    end?: number;
-  };
-};
-
-type OpenCodeMessageInfo = {
-  id: string;
-  sessionID: string;
-};
-
-type OpenCodeMessageWithParts = {
-  info: OpenCodeMessageInfo;
-  parts: OpenCodePart[];
-};
+import {
+  buildAuthHeader,
+  buildSessionUrl,
+  normalizeServerUrl,
+  resolveSessionId,
+} from "../lib/serverUrl";
+import { httpRequestJson, type HttpResponse } from "../lib/http";
 
 type OpenCodeSession = {
   id?: string;
@@ -29,22 +12,28 @@ type OpenCodeSession = {
 
 type OpenCodeResponse<T> = T | { data?: T } | { message?: T } | null;
 
+/**
+ * Thin client for the OpenCode 2.x HTTP API (`/api/*`), used for the things the
+ * plugin needs outside the embedded web UI: resolving the project for the vault
+ * directory, creating a session to open, and injecting workspace context.
+ */
 export class OpenCodeClient {
   private apiBaseUrl: string;
   private uiBaseUrl: string;
   private projectDirectory: string;
+  private password = "";
   private trackedSessionId: string | null = null;
-  private lastPart: OpenCodePart | null = null;
+  private lastContextText: string | null = null;
 
   constructor(apiBaseUrl: string, uiBaseUrl: string, projectDirectory: string) {
-    this.apiBaseUrl = this.normalizeBaseUrl(apiBaseUrl);
-    this.uiBaseUrl = this.normalizeBaseUrl(uiBaseUrl);
+    this.apiBaseUrl = normalizeServerUrl(apiBaseUrl);
+    this.uiBaseUrl = normalizeServerUrl(uiBaseUrl);
     this.projectDirectory = projectDirectory;
   }
 
   updateBaseUrl(apiBaseUrl: string, uiBaseUrl: string, projectDirectory: string): void {
-    const nextApiUrl = this.normalizeBaseUrl(apiBaseUrl);
-    const nextUiUrl = this.normalizeBaseUrl(uiBaseUrl);
+    const nextApiUrl = normalizeServerUrl(apiBaseUrl);
+    const nextUiUrl = normalizeServerUrl(uiBaseUrl);
     if (
       nextApiUrl !== this.apiBaseUrl ||
       nextUiUrl !== this.uiBaseUrl ||
@@ -57,28 +46,37 @@ export class OpenCodeClient {
     }
   }
 
+  setPassword(password: string): void {
+    if (password !== this.password) {
+      this.password = password;
+      this.resetTracking();
+    }
+  }
+
   resetTracking(): void {
     this.trackedSessionId = null;
-    this.lastPart = null;
+    this.lastContextText = null;
+  }
+
+  getApiBaseUrl(): string {
+    return this.apiBaseUrl;
   }
 
+  /** Make sure the server knows the vault directory as a project. */
   async initializeProject(): Promise<boolean> {
     try {
-      const url = `${this.apiBaseUrl}/session?directory=${encodeURIComponent(this.projectDirectory)}`;
-      const response = await fetch(url, {
-        method: "GET",
-        headers: {
-          "x-opencode-directory": this.projectDirectory,
-        },
-      });
+      const response = await this.request(
+        "GET",
+        `/api/location?location[directory]=${encodeURIComponent(this.projectDirectory)}`
+      );
 
       if (response.ok) {
         console.log("[OpenCode] Project initialized:", this.projectDirectory);
         return true;
-      } else {
-        console.warn("[OpenCode] Project initialization failed:", response.status);
-        return false;
       }
+
+      console.warn("[OpenCode] Project initialization failed:", response.status);
+      return false;
     } catch (error) {
       console.error("[OpenCode] Project initialization error:", error);
       return false;
@@ -86,133 +84,106 @@ export class OpenCodeClient {
   }
 
   getSessionUrl(sessionId: string): string {
-    return `${this.uiBaseUrl}/session/${sessionId}`;
+    return buildSessionUrl(this.uiBaseUrl, sessionId);
   }
 
-  resolveSessionId(iframeUrl: string): string | null {
-    const match = iframeUrl.match(/\/session\/([^/?#]+)/);
-    return match?.[1] ?? null;
+  resolveSessionId(embedUrl: string): string | null {
+    return resolveSessionId(embedUrl);
   }
 
   async createSession(): Promise<string | null> {
-    const result = await this.request<OpenCodeSession>("POST", "/session", {
+    const result = await this.json<OpenCodeSession>("POST", "/api/session", {
       title: "Obsidian",
+      location: { directory: this.projectDirectory },
     });
-    const session = this.unwrap(result);
+    const session = this.unwrap<OpenCodeSession>(result);
     return session?.id ?? null;
   }
 
+  /**
+   * Attach the current workspace context to the session.
+   *
+   * v1 stored this as a hidden message part and patched it in place. v2 has no
+   * part update endpoint; synthetic input is durable instead, so a new message is
+   * only added when the context actually changed.
+   */
   async updateContext(params: {
     sessionId: string;
     contextText: string | null;
   }): Promise<void> {
     const { sessionId, contextText } = params;
 
-    if (this.trackedSessionId && this.trackedSessionId !== sessionId) {
+    if (this.trackedSessionId !== sessionId) {
       this.resetTracking();
+      this.trackedSessionId = sessionId;
     }
-    this.trackedSessionId = sessionId;
 
-    if (!contextText) {
-      await this.ignorePreviousPart();
+    if (!contextText || contextText === this.lastContextText) {
       return;
     }
 
-    if (this.lastPart) {
-      const updated = await this.updatePart(this.lastPart, { text: contextText });
-      if (updated) {
-        return;
-      }
-      await this.ignorePreviousPart();
-    }
+    const response = await this.request("POST", `/api/session/${sessionId}/synthetic`, {
+      text: contextText,
+      resume: false,
+    });
 
-    const message = await this.sendPrompt(sessionId, contextText);
-    if (message?.info?.id) {
-      this.lastPart = message.parts?.[0] ?? null;
+    if (!response.ok) {
+      console.warn("[OpenCode] Context injection failed:", response.status);
+      return;
     }
-  }
-
-  private async sendPrompt(sessionId: string, contextText: string): Promise<OpenCodeMessageWithParts | null> {
-    const result = await this.request<OpenCodeMessageWithParts>(
-      "POST",
-      `/session/${sessionId}/message`,
-      {
-        noReply: true,
-        parts: [{ type: "text", text: contextText }],
-      }
-    );
 
+    this.lastContextText = contextText;
     console.log("[OpenCode] Injected context message");
-    console.log(contextText)
-
-    const message = this.unwrap(result);
-    if (!message) {
-      console.error("[OpenCode] Failed to inject context message");
-    }
-    return message;
-  }
-
-  private async updatePart(part: OpenCodePart, updates: { text?: string; ignored?: boolean }): Promise<boolean> {
-    const result = await this.request<OpenCodePart>(
-      "PATCH",
-      `/session/${part.sessionID}/message/${part.messageID}/part/${part.id}`,
-      {
-        ...part,
-        ...updates,
-      }
-    );
-    const updated = this.unwrap(result);
-    if (updated) {
-      this.lastPart = updated;
-      return true;
-    }
-    return false;
   }
 
-  private async ignorePreviousPart(): Promise<boolean> {
-    if (!this.lastPart) {
-      return false;
-    }
-
-    const ignored = await this.updatePart(this.lastPart, { ignored: true });
-    if (!ignored) {
-      return false;
-    }
-
-    this.lastPart = null;
-    return true;
+  private async request(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<HttpResponse> {
+    // node:http instead of fetch: the renderer's fetch is CORS-blocked against
+    // the OpenCode server (its preflight carries no allow-origin header).
+    return httpRequestJson(method, `${this.apiBaseUrl}${path}`, {
+      headers: this.headers(),
+      body: body ? JSON.stringify(body) : undefined,
+      timeoutMs: 15000,
+    });
   }
 
-  private async request<T>(method: string, path: string, body?: unknown): Promise<OpenCodeResponse<T>> {
+  private async json<T>(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<OpenCodeResponse<T>> {
     try {
-      const url = `${this.apiBaseUrl}${path}`;
-      const response = await fetch(url, {
-        method,
-        headers: {
-          "Content-Type": "application/json",
-          "x-opencode-directory": this.projectDirectory,
-        },
-        body: body ? JSON.stringify(body) : undefined,
-      });
+      const response = await this.request(method, path, body);
 
       if (!response.ok) {
-        console.error("[OpenCode] API request failed", {
-          path,
-          status: response.status,
-        });
+        console.error("[OpenCode] API request failed", { path, status: response.status });
         return null;
       }
 
-      const json = await response
-        .json()
-        .catch(() => null);
-      return json as OpenCodeResponse<T>;
+      const text = response.body;
+      if (!text) {
+        return null;
+      }
+      return JSON.parse(text) as OpenCodeResponse<T>;
     } catch (error) {
       console.error("[OpenCode] API request error", error);
       return null;
     }
   }
 
+  private headers(): Record<string, string> {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (this.password) {
+      headers.Authorization = buildAuthHeader(this.password);
+    }
+    return headers;
+  }
+
   private unwrap<T>(result: OpenCodeResponse<T>): T | null {
     if (!result) {
       return null;
@@ -228,8 +199,4 @@ export class OpenCodeClient {
     }
     return result as T;
   }
-
-  private normalizeBaseUrl(baseUrl: string): string {
-    return baseUrl.replace(/\/+$/, "");
-  }
 }
diff --git a/src/lib/http.ts b/src/lib/http.ts
new file mode 100644
index 0000000..c61b2d3
--- /dev/null
+++ b/src/lib/http.ts
@@ -0,0 +1,68 @@
+import { request as httpRequest } from "http";
+import { request as httpsRequest } from "https";
+import { URL } from "url";
+
+export interface HttpResponse {
+  status: number;
+  ok: boolean;
+  body: string;
+}
+
+/**
+ * Minimal HTTP client on top of node:http.
+ *
+ * Obsidian plugins run in the renderer, where `fetch` to the OpenCode server is
+ * subject to CORS: any request carrying an Authorization header is preflighted,
+ * and the shared service answers that preflight without
+ * `access-control-allow-origin` - the browser then blocks the request. Node's
+ * http module has no such restriction, so all plugin-side API calls go through
+ * here. The embedded webview is unaffected (same origin).
+ */
+export function httpRequestJson(
+  method: string,
+  url: string,
+  options: { headers?: Record<string, string>; body?: string; timeoutMs?: number } = {}
+): Promise<HttpResponse> {
+  const target = new URL(url);
+  const requestFn = target.protocol === "https:" ? httpsRequest : httpRequest;
+  const timeoutMs = options.timeoutMs ?? 10000;
+  const payload = options.body;
+  const headers: Record<string, string> = { ...(options.headers ?? {}) };
+  if (payload !== undefined) {
+    headers["Content-Length"] = Buffer.byteLength(payload).toString();
+  }
+
+  return new Promise((resolve, reject) => {
+    const req = requestFn(
+      {
+        protocol: target.protocol,
+        hostname: target.hostname,
+        port: target.port,
+        path: `${target.pathname}${target.search}`,
+        method,
+        headers,
+      },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on("data", (chunk: Buffer) => chunks.push(chunk));
+        res.on("end", () => {
+          const status = res.statusCode ?? 0;
+          resolve({
+            status,
+            ok: status >= 200 && status < 300,
+            body: Buffer.concat(chunks).toString("utf8"),
+          });
+        });
+      }
+    );
+
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error(`Request to ${url} timed out after ${timeoutMs}ms`));
+    });
+    req.on("error", reject);
+    if (payload !== undefined) {
+      req.write(payload);
+    }
+    req.end();
+  });
+}
diff --git a/src/lib/serverUrl.ts b/src/lib/serverUrl.ts
new file mode 100644
index 0000000..5299c05
--- /dev/null
+++ b/src/lib/serverUrl.ts
@@ -0,0 +1,57 @@
+/**
+ * URL and auth helpers for the OpenCode 2.x server.
+ *
+ * OpenCode 2 dropped the per-project URL scheme (`http://host:port/<base64dir>`)
+ * in favour of a single web app whose routes are:
+ *
+ *   /                                    home / project picker
+ *   /server/<serverKey>/session/<id>     one session
+ *
+ * where <serverKey> is the base64url encoding of the server URL. The server also
+ * requires HTTP Basic authentication (user "opencode", password printed by
+ * `opencode serve` or taken from OPENCODE_SERVER_PASSWORD).
+ */
+
+const AUTH_USERNAME = "opencode";
+
+/** localStorage key the web app uses to persist known servers. */
+export const STORAGE_KEY_SERVER = "opencode.global.dat:server";
+
+/** Strip trailing slashes so a server URL can be joined safely. */
+export function normalizeServerUrl(serverUrl: string): string {
+  return serverUrl.replace(/\/+$/, "");
+}
+
+/** Encode a server URL the way the OpenCode web app expects in a session route. */
+export function encodeServerKey(serverUrl: string): string {
+  return Buffer.from(normalizeServerUrl(serverUrl), "utf8")
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+/** URL to load in the webview: the app entry point for this server. */
+export function buildUiUrl(serverUrl: string): string {
+  return normalizeServerUrl(serverUrl);
+}
+
+/** URL of a specific session inside the web app. */
+export function buildSessionUrl(serverUrl: string, sessionId: string): string {
+  return `${normalizeServerUrl(serverUrl)}/server/${encodeServerKey(
+    serverUrl
+  )}/session/${sessionId}`;
+}
+
+/** HTTP Basic header value for the OpenCode server API. */
+export function buildAuthHeader(password: string): string {
+  return `Basic ${Buffer.from(`${AUTH_USERNAME}:${password}`, "utf8").toString(
+    "base64"
+  )}`;
+}
+
+/** True when the given URL is a session URL of the form /server/<key>/session/<id>. */
+export function resolveSessionId(url: string): string | null {
+  const match = url.match(/\/session\/([^/?#]+)/);
+  return match?.[1] ?? null;
+}
diff --git a/src/main.ts b/src/main.ts
index c925699..fb0f7c3 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -52,6 +52,7 @@ export default class OpenCodePlugin extends Plugin {
       this.getServerUrl(),
       projectDirectory
     );
+    this.openCodeClient.setPassword(this.processManager.getPassword());
     this.lastBaseUrl = this.getServerUrl();
 
     this.contextManager = new ContextManager({
@@ -227,6 +228,11 @@ export default class OpenCodePlugin extends Plugin {
     return this.processManager.getUrl();
   }
 
+  /** Password the embedded OpenCode web UI must use to talk to its server. */
+  getServerPassword(): string {
+    return this.processManager.getPassword();
+  }
+
   getApiBaseUrl(): string {
     return `http://${this.settings.hostname}:${this.settings.port}`;
   }
@@ -260,6 +266,7 @@ export default class OpenCodePlugin extends Plugin {
     const nextApiBaseUrl = this.getApiBaseUrl();
     const projectDirectory = this.getProjectDirectory();
     this.openCodeClient.updateBaseUrl(nextApiBaseUrl, nextUiBaseUrl, projectDirectory);
+    this.openCodeClient.setPassword(this.processManager.getPassword());
 
     if (this.lastBaseUrl && this.lastBaseUrl !== nextUiBaseUrl) {
       this.cachedIframeUrl = null;
diff --git a/src/server/ServerManager.ts b/src/server/ServerManager.ts
index aac8c92..1e0b844 100644
--- a/src/server/ServerManager.ts
+++ b/src/server/ServerManager.ts
@@ -1,14 +1,20 @@
 import { ChildProcess, SpawnOptions } from "child_process";
 import { EventEmitter } from "events";
+import { createHash } from "crypto";
 import { OpenCodeSettings } from "../types";
 import { ServerState } from "./types";
 import { OpenCodeProcess } from "./process/OpenCodeProcess";
 import { WindowsProcess } from "./process/WindowsProcess";
 import { PosixProcess } from "./process/PosixProcess";
 import { ExecutableResolver } from "./ExecutableResolver";
+import { buildAuthHeader, normalizeServerUrl } from "../lib/serverUrl";
+import { httpRequestJson } from "../lib/http";
 
 export type { ServerState } from "./types";
 
+/** Health probe outcome: authenticated, rejected, or nothing listening. */
+type HealthStatus = "ok" | "unauthorized" | "down";
+
 export class ServerManager extends EventEmitter {
   private process: ChildProcess | null = null;
   private state: ServerState = "stopped";
@@ -43,9 +49,31 @@ export class ServerManager extends EventEmitter {
     return this.lastError;
   }
 
+  /**
+   * OpenCode 2 serves one web app per server and no longer encodes the project
+   * directory in the URL; the directory is selected by the session instead.
+   */
   getUrl(): string {
-    const encodedPath = Buffer.from(this.projectDirectory).toString('base64');
-    return `http://${this.settings.hostname}:${this.settings.port}/${encodedPath}`;
+    return normalizeServerUrl(`http://${this.settings.hostname}:${this.settings.port}`);
+  }
+
+  /**
+   * Password handed to the server via OPENCODE_SERVER_PASSWORD.
+   *
+   * It is derived from host and port so that a server left over from a previous
+   * Obsidian session still accepts our credentials instead of failing with 401
+   * "port already in use". Derived from port/host only (not the vault path) so
+   * switching the project directory does not invalidate a running server.
+   */
+  getPassword(): string {
+    return createHash("sha256")
+      .update(`obsidian-opencode:${this.settings.hostname}:${this.settings.port}`)
+      .digest("hex")
+      .slice(0, 32);
+  }
+
+  getAuthHeader(): string {
+    return buildAuthHeader(this.getPassword());
   }
 
   async start(): Promise<boolean> {
@@ -64,41 +92,44 @@ export class ServerManager extends EventEmitter {
     // Determine execution mode and resolve executable path
     let executablePath: string;
     let spawnOptions: SpawnOptions;
-    
+
     if (this.settings.useCustomCommand) {
       // Custom command mode: use custom command directly with shell
       executablePath = this.settings.customCommand;
       spawnOptions = {
         cwd: this.projectDirectory,
-        env: { ...process.env, NODE_USE_SYSTEM_CA: "1" },
+        env: this.buildEnv(),
         stdio: ["ignore", "pipe", "pipe"],
         shell: true,
       };
     } else {
       // Path mode: resolve executable and verify
       executablePath = ExecutableResolver.resolve(this.settings.opencodePath);
-      
+
       // Pre-flight check: verify executable exists (only for path mode)
       const commandError = await this.processImpl.verifyCommand(executablePath);
       if (commandError) {
         return this.setError(commandError);
       }
-      
+
       spawnOptions = {
         cwd: this.projectDirectory,
-        env: { ...process.env, NODE_USE_SYSTEM_CA: "1" },
+        env: this.buildEnv(),
         stdio: ["ignore", "pipe", "pipe"],
       };
     }
 
-    if (await this.checkServerHealth()) {
-      console.log(
-        "[OpenCode] Server already running on port",
-        this.settings.port
-      );
+    const health = await this.checkServerHealth();
+    if (health === "ok") {
+      console.log("[OpenCode] Server already running on port", this.settings.port);
       this.setState("running");
       return true;
     }
+    if (health === "unauthorized") {
+      return this.setError(
+        `Port ${this.settings.port} is already used by an OpenCode server that rejects this plugin's password. Stop that server (or change the port in the plugin settings) and retry.`
+      );
+    }
 
     console.log("[OpenCode] Starting server:", {
       mode: this.settings.useCustomCommand ? "custom" : "path",
@@ -163,12 +194,10 @@ export class ServerManager extends EventEmitter {
       this.process = null;
 
       if (err.code === "ENOENT") {
-        const command = this.settings.useCustomCommand 
-          ? this.settings.customCommand 
+        const command = this.settings.useCustomCommand
+          ? this.settings.customCommand
           : this.settings.opencodePath;
-        this.setError(
-          `Executable not found: '${command}'`
-        );
+        this.setError(`Executable not found: '${command}'`);
       } else {
         this.setError(`Failed to start: ${err.message}`);
       }
@@ -210,6 +239,16 @@ export class ServerManager extends EventEmitter {
     await this.processImpl.stop(proc);
   }
 
+  private buildEnv(): NodeJS.ProcessEnv {
+    return {
+      ...process.env,
+      NODE_USE_SYSTEM_CA: "1",
+      // OpenCode 2 prints a random password unless one is supplied. Supplying a
+      // stable one keeps the embedded web UI authenticated across restarts.
+      OPENCODE_SERVER_PASSWORD: this.getPassword(),
+    };
+  }
+
   private setState(state: ServerState): void {
     this.state = state;
     this.emit("stateChange", state);
@@ -222,15 +261,27 @@ export class ServerManager extends EventEmitter {
     return false;
   }
 
-  private async checkServerHealth(): Promise<boolean> {
+  /**
+   * OpenCode 2 exposes its API under /api. A request without valid credentials
+   * returns 401 - which distinguishes "server we may talk to" from "some other
+   * server squatting on our port".
+   */
+  private async checkServerHealth(): Promise<HealthStatus> {
     try {
-      const response = await fetch(`${this.getUrl()}/global/health`, {
-        method: "GET",
-        signal: AbortSignal.timeout(2000),
+      // node:http, not fetch: renderer fetch is CORS-blocked against the server.
+      const response = await httpRequestJson("GET", `${this.getUrl()}/api/info`, {
+        headers: { Authorization: this.getAuthHeader() },
+        timeoutMs: 2000,
       });
-      return response.ok;
+      if (response.ok) {
+        return "ok";
+      }
+      if (response.status === 401) {
+        return "unauthorized";
+      }
+      return "down";
     } catch {
-      return false;
+      return "down";
     }
   }
 
@@ -244,7 +295,7 @@ export class ServerManager extends EventEmitter {
         return false;
       }
 
-      if (await this.checkServerHealth()) {
+      if ((await this.checkServerHealth()) === "ok") {
         return true;
       }
       await this.sleep(pollInterval);
diff --git a/src/ui/OpenCodeView.ts b/src/ui/OpenCodeView.ts
index db49d3e..e623d5b 100644
--- a/src/ui/OpenCodeView.ts
+++ b/src/ui/OpenCodeView.ts
@@ -3,10 +3,22 @@ import { OPENCODE_VIEW_TYPE } from "../types";
 import { OPENCODE_ICON_NAME } from "../icons";
 import type OpenCodePlugin from "../main";
 import type { ServerState } from "../server/types";
+import {
+  buildCredentialSeedScript,
+  isWebviewSupported,
+  type OpenCodeEmbedElement,
+} from "./embed";
+
+/** How long to wait for the webview to boot before falling back to an iframe. */
+const WEBVIEW_READY_TIMEOUT_MS = 10000;
 
 export class OpenCodeView extends ItemView {
   plugin: OpenCodePlugin;
-  private iframeEl: HTMLIFrameElement | null = null;
+  private embedEl: OpenCodeEmbedElement | HTMLIFrameElement | null = null;
+  private embedKind: "webview" | "iframe" | null = null;
+  private embedReady = false;
+  private seedReloaded = false;
+  private readyWatchdog: number | null = null;
   private currentState: ServerState = "stopped";
   private unsubscribeStateChange: (() => void) | null = null;
 
@@ -53,16 +65,23 @@ export class OpenCodeView extends ItemView {
       this.unsubscribeStateChange();
       this.unsubscribeStateChange = null;
     }
-    
-    // Clean up iframe
-    if (this.iframeEl) {
-      const iframeUrl = this.iframeEl.src;
-      if (iframeUrl.includes("/session/")) {
-        this.plugin.setCachedIframeUrl(iframeUrl);
+
+    this.clearWatchdog();
+
+    // Clean up embed element
+    if (this.embedEl) {
+      const embedUrl = this.getIframeUrl();
+      if (embedUrl && embedUrl.includes("/session/")) {
+        this.plugin.setCachedIframeUrl(embedUrl);
       }
-      this.iframeEl.src = "about:blank";
-      this.iframeEl = null;
+      this.embedEl.setAttribute("src", "about:blank");
+      this.embedEl.detach();
+      this.embedEl = null;
+      this.embedKind = null;
     }
+
+    this.embedReady = false;
+    this.seedReloaded = false;
   }
 
   private updateView(): void {
@@ -126,6 +145,8 @@ export class OpenCodeView extends ItemView {
 
   private renderRunningState(): void {
     this.contentEl.empty();
+    this.embedReady = false;
+    this.seedReloaded = false;
 
     const headerEl = this.contentEl.createDiv({ cls: "opencode-header" });
 
@@ -141,7 +162,7 @@ export class OpenCodeView extends ItemView {
     });
     setIcon(reloadButton, "refresh-cw");
     reloadButton.addEventListener("click", () => {
-      this.reloadIframe();
+      this.reloadEmbed();
     });
 
     const stopButton = actionsEl.createEl("button", {
@@ -152,31 +173,136 @@ export class OpenCodeView extends ItemView {
       this.plugin.stopServer();
     });
 
-    const iframeContainer = this.contentEl.createDiv({
+    const embedContainer = this.contentEl.createDiv({
       cls: "opencode-iframe-container",
     });
 
-    const iframeUrl = this.plugin.getStoredIframeUrl() ?? this.plugin.getServerUrl();
-    console.log("[OpenCode] Loading iframe with URL:", iframeUrl);
+    const serverUrl = this.plugin.getServerUrl();
+    const startUrl = this.plugin.getStoredIframeUrl() ?? serverUrl;
+    console.log("[OpenCode] Loading UI with URL:", startUrl);
+
+    if (isWebviewSupported()) {
+      this.mountWebview(embedContainer, startUrl, serverUrl);
+    } else {
+      this.mountIframe(embedContainer, startUrl, serverUrl, false);
+    }
+  }
+
+  /**
+   * Mount the OpenCode web app in an Electron <webview>.
+   *
+   * The app is served from 127.0.0.1 and is cross-origin to app://obsidian.md,
+   * which means its localStorage can only be written from inside the guest
+   * process - that is what <webview>.executeJavaScript is for.
+   */
+  private mountWebview(
+    container: HTMLElement,
+    startUrl: string,
+    serverUrl: string
+  ): void {
+    const webview = document.createElement("webview") as OpenCodeEmbedElement;
+    webview.addClass("opencode-webview");
+    webview.setAttribute("src", startUrl);
+    webview.setAttribute("allowpopups", "true");
+    container.appendChild(webview);
+
+    this.embedEl = webview;
+    this.embedKind = "webview";
+
+    webview.addEventListener("dom-ready", () => {
+      this.embedReady = true;
+      this.clearWatchdog();
+      void this.handleWebviewReady(webview, serverUrl);
+    });
+
+    webview.addEventListener("did-fail-load", (event: Event) => {
+      const detail = event as unknown as { errorDescription?: string };
+      console.error("[OpenCode] Webview failed to load:", detail.errorDescription);
+    });
+
+    webview.addEventListener("focus", () => {
+      this.plugin.refreshContextForView(this);
+    });
+
+    webview.addEventListener("pointerdown", () => {
+      this.plugin.refreshContextForView(this);
+    });
+
+    this.readyWatchdog = window.setTimeout(() => {
+      if (this.embedReady || this.embedEl !== webview) {
+        return;
+      }
+      console.warn("[OpenCode] Webview did not become ready, falling back to iframe");
+      webview.detach();
+      container.empty();
+      this.mountIframe(container, startUrl, serverUrl, true);
+    }, WEBVIEW_READY_TIMEOUT_MS);
+  }
+
+  /**
+   * Runs on every dom-ready. Seeds the server credential into the web app's
+   * storage (the app keeps its server list there and authenticates API calls
+   * with the stored password), reloading once so the value is picked up during
+   * startup, then navigates to the session for this vault.
+   */
+  private async handleWebviewReady(
+    webview: OpenCodeEmbedElement,
+    serverUrl: string
+  ): Promise<void> {
+    const password = this.plugin.getServerPassword();
+
+    if (password && !this.seedReloaded) {
+      try {
+        const changed = await webview.executeJavaScript(
+          buildCredentialSeedScript(serverUrl, password)
+        );
+        if (this.embedEl !== webview) {
+          return;
+        }
+        if (changed === true) {
+          this.seedReloaded = true;
+          this.embedReady = false;
+          webview.reload();
+          return;
+        }
+      } catch (error) {
+        console.warn("[OpenCode] Failed to seed server credentials", error);
+      }
+    }
+
+    void this.plugin.ensureSessionUrl(this);
+  }
 
-    this.iframeEl = iframeContainer.createEl("iframe", {
+  private mountIframe(
+    container: HTMLElement,
+    startUrl: string,
+    _serverUrl: string,
+    afterFallback: boolean
+  ): void {
+    const notice = container.createDiv({ cls: "opencode-notice" });
+    notice.setText(
+      afterFallback
+        ? "Electron webview unavailable - OpenCode must be connected manually: run `opencode pair`, then paste the pairing link into the embedded window."
+        : "OpenCode 2 needs a pairing link: run `opencode pair`, then paste it into the window below."
+    );
+
+    const frame = container.createEl("iframe", {
       cls: "opencode-iframe",
       attr: {
-        src: iframeUrl,
+        src: startUrl,
         frameborder: "0",
         allow: "clipboard-read; clipboard-write",
       },
     });
 
-    this.iframeEl.addEventListener("error", () => {
-      console.error("Failed to load OpenCode iframe");
-    });
+    this.embedEl = frame;
+    this.embedKind = "iframe";
 
-    this.iframeEl.addEventListener("focus", () => {
+    frame.addEventListener("focus", () => {
       this.plugin.refreshContextForView(this);
     });
 
-    this.iframeEl.addEventListener("pointerdown", () => {
+    frame.addEventListener("pointerdown", () => {
       this.plugin.refreshContextForView(this);
     });
 
@@ -184,12 +310,15 @@ export class OpenCodeView extends ItemView {
   }
 
   getIframeUrl(): string | null {
-    return this.iframeEl?.src ?? null;
+    return this.embedEl?.getAttribute("src") ?? null;
   }
 
   setIframeUrl(url: string): void {
-    if (this.iframeEl && this.iframeEl.src !== url) {
-      this.iframeEl.src = url;
+    if (!this.embedEl) {
+      return;
+    }
+    if (this.getIframeUrl() !== url) {
+      this.embedEl.setAttribute("src", url);
     }
   }
 
@@ -204,7 +333,7 @@ export class OpenCodeView extends ItemView {
     setIcon(iconEl, "alert-circle");
 
     statusContainer.createEl("h3", { text: "Failed to start OpenCode" });
-    
+
     const errorMessage = this.plugin.getLastError();
     if (errorMessage) {
       statusContainer.createEl("p", {
@@ -239,15 +368,32 @@ export class OpenCodeView extends ItemView {
     });
   }
 
-  private reloadIframe(): void {
-    if (this.iframeEl) {
-      const src = this.iframeEl.src;
-      this.iframeEl.src = "about:blank";
-      setTimeout(() => {
-        if (this.iframeEl) {
-          this.iframeEl.src = src;
-        }
-      }, 100);
+  private reloadEmbed(): void {
+    const embed = this.embedEl;
+    if (!embed) {
+      return;
+    }
+
+    if (this.embedKind === "webview") {
+      this.embedReady = false;
+      this.seedReloaded = false;
+      (embed as OpenCodeEmbedElement).reload();
+      return;
+    }
+
+    const src = embed.getAttribute("src") ?? "";
+    embed.setAttribute("src", "about:blank");
+    setTimeout(() => {
+      if (this.embedEl === embed) {
+        embed.setAttribute("src", src);
+      }
+    }, 100);
+  }
+
+  private clearWatchdog(): void {
+    if (this.readyWatchdog !== null) {
+      window.clearTimeout(this.readyWatchdog);
+      this.readyWatchdog = null;
     }
   }
 }
diff --git a/src/ui/embed.ts b/src/ui/embed.ts
new file mode 100644
index 0000000..630b684
--- /dev/null
+++ b/src/ui/embed.ts
@@ -0,0 +1,115 @@
+import { STORAGE_KEY_SERVER, normalizeServerUrl } from "../lib/serverUrl";
+
+/**
+ * Electron <webview> element as used by Obsidian (webviewTag is enabled in the
+ * main window). Only the members we rely on are typed.
+ */
+export interface OpenCodeEmbedElement extends HTMLElement {
+  executeJavaScript(code: string): Promise<unknown>;
+  reload(): void;
+}
+
+/**
+ * `<webview>` is the only way to run script inside the embedded page: the
+ * OpenCode web app is served from 127.0.0.1 and is therefore cross-origin to
+ * `app://obsidian.md`, so an <iframe> can neither read nor write its storage.
+ */
+export function isWebviewSupported(): boolean {
+  const probe = document.createElement("webview") as unknown as OpenCodeEmbedElement;
+  return (
+    typeof probe.executeJavaScript === "function" && typeof probe.reload === "function"
+  );
+}
+
+/**
+ * Script that writes the server credential into the OpenCode web app storage.
+ *
+ * The app keeps its server list in localStorage and authenticates API calls
+ * with the password stored there, so seeding this entry is enough to skip the
+ * "Connect to a server" screen. Pairing links are not an alternative here: the
+ * session cookie they set is SameSite=Lax and is never sent from inside an
+ * embedded frame.
+ *
+ * Returns true when a value changed; the caller reloads once so the app picks
+ * it up during startup. The second pass finds a matching value and returns
+ * false, so no reload loop is possible.
+ */
+export function buildCredentialSeedScript(serverUrl: string, password: string): string {
+  const url = normalizeServerUrl(serverUrl);
+
+  return `(function () {
+  var key = ${JSON.stringify(STORAGE_KEY_SERVER)};
+  var url = ${JSON.stringify(url)};
+  var password = ${JSON.stringify(password)};
+
+  var stored = null;
+  try {
+    stored = window.localStorage.getItem(key);
+  } catch (error) {
+    return false;
+  }
+
+  var state = null;
+  try {
+    state = stored ? JSON.parse(stored) : null;
+  } catch (error) {
+    state = null;
+  }
+
+  if (!state || typeof state !== "object") {
+    state = {};
+  }
+  if (!Array.isArray(state.list)) {
+    state.list = [];
+  }
+  // Match the shape the app itself writes (it normalises and drops unknown
+  // keys on startup, so inventing fields risks the whole entry being reset).
+  if (!state.hidden) {
+    state.hidden = {};
+  }
+  if (!state.projects) {
+    state.projects = {};
+  }
+  if (!state.lastProjectID) {
+    state.lastProjectID = {};
+  }
+  if (!state.usedProjectIDs) {
+    state.usedProjectIDs = {};
+  }
+  if (!state.hostnames) {
+    state.hostnames = {};
+  }
+
+  var entry = null;
+  for (var i = 0; i < state.list.length; i += 1) {
+    var candidate = state.list[i];
+    if (
+      candidate &&
+      candidate.type === "http" &&
+      candidate.http &&
+      candidate.http.url === url
+    ) {
+      entry = candidate;
+      break;
+    }
+  }
+
+  if (entry && entry.http.password === password) {
+    return false;
+  }
+
+  if (entry) {
+    entry.http.password = password;
+  } else {
+    state.list.push({ type: "http", http: { url: url, password: password } });
+  }
+
+  try {
+    window.localStorage.setItem(key, JSON.stringify(state));
+  } catch (error) {
+    return false;
+  }
+
+  return true;
+})();`;
+}
diff --git a/styles.css b/styles.css
index 2bce793..14970f9 100644
--- a/styles.css
+++ b/styles.css
@@ -69,6 +69,25 @@
   background-color: var(--background-primary);
 }
 
+/* Electron webview embed (used when webviewTag is available) */
+.opencode-webview {
+  display: inline-flex;
+  width: 100%;
+  height: 100%;
+  border: none;
+  background-color: var(--background-primary);
+}
+
+/* Hint shown above the iframe fallback */
+.opencode-notice {
+  flex: none;
+  padding: 8px 12px;
+  font-size: 0.85em;
+  color: var(--text-muted);
+  background-color: var(--background-secondary);
+  border-bottom: 1px solid var(--background-modifier-border);
+}
+
 /* Status container (for stopped/starting/error states) */
 .opencode-status-container {
   display: flex;
diff --git a/tests/ServerManager.test.ts b/tests/ServerManager.test.ts
index 6cf4c1b..2bd0f21 100644
--- a/tests/ServerManager.test.ts
+++ b/tests/ServerManager.test.ts
@@ -81,19 +81,31 @@ describe("ServerManager", () => {
       expect(stateHistory).toContain("running");
     }, 30000); // Increased timeout for database migration on first run
 
-     test("reports correct server URL with encoded project directory", async () => {
+     test("reports the plain server URL (v2 has no project path segment)", async () => {
        const port = getNextPort();
        const settings = createTestSettings(port);
 
        currentManager = new ServerManager(settings, PROJECT_DIR);
 
-      const url = currentManager.getUrl();
-      const expectedBase = `http://127.0.0.1:${port}`;
-      const expectedPath = Buffer.from(PROJECT_DIR).toString('base64');
-
-      expect(url).toBe(`${expectedBase}/${expectedPath}`);
+      expect(currentManager.getUrl()).toBe(`http://127.0.0.1:${port}`);
     });
 
+     test("derives a stable password for the server", async () => {
+       const port = getNextPort();
+       const settings = createTestSettings(port);
+
+       const first = new ServerManager(settings, PROJECT_DIR);
+       const second = new ServerManager(settings, PROJECT_DIR);
+
+       // Same host/port must yield the same password so a server left over from
+       // a previous session still accepts our credentials.
+       expect(first.getPassword()).toBe(second.getPassword());
+       expect(first.getPassword().length).toBeGreaterThan(0);
+
+       const other = new ServerManager({ ...settings, port: port + 1 }, PROJECT_DIR);
+       expect(other.getPassword()).not.toBe(first.getPassword());
+     });
+
      test("stops server gracefully and transitions to stopped state", async () => {
        const port = getNextPort();
        const settings = createTestSettings(port);
@@ -190,11 +202,11 @@ describe("ServerManager", () => {
 
       await currentManager.start();
 
-      // Verify we can hit the health endpoint
+      // Verify we can hit the API with the credentials we handed to the server
       const url = currentManager.getUrl();
-      const healthUrl = `${url}/global/health`;
 
-      const response = await fetch(healthUrl, {
+      const response = await fetch(`${url}/api/info`, {
+        headers: { Authorization: currentManager.getAuthHeader() },
         signal: AbortSignal.timeout(2000),
       });
 
@@ -287,35 +299,27 @@ describe("ServerManager", () => {
   });
 
   describe("Unicode path support", () => {
-    test("getUrl handles Chinese characters in project directory", () => {
+    // OpenCode 2 no longer encodes the project directory in the URL, so a
+    // non-Latin1 vault path must simply not leak into it (issue #28 regression).
+    test("getUrl is independent of the project directory (Chinese)", () => {
       const settings = createTestSettings(getNextPort());
-      const chinesePath = "C:/用户/Notes";
-      const manager = new ServerManager(settings, chinesePath);
-
-      const url = manager.getUrl();
+      const manager = new ServerManager(settings, "C:/用户/Notes");
 
-      expect(url).toContain("http://127.0.0.1:");
-      expect(url).toContain(Buffer.from(chinesePath).toString('base64'));
+      expect(manager.getUrl()).toBe(`http://127.0.0.1:${settings.port}`);
     });
 
-    test("getUrl handles Japanese characters in project directory", () => {
+    test("getUrl is independent of the project directory (Japanese)", () => {
       const settings = createTestSettings(getNextPort());
-      const japanesePath = "/home/ユーザー/ノート";
-      const manager = new ServerManager(settings, japanesePath);
+      const manager = new ServerManager(settings, "/home/ユーザー/ノート");
 
-      const url = manager.getUrl();
-
-      expect(url).toContain(Buffer.from(japanesePath).toString('base64'));
+      expect(manager.getUrl()).toBe(`http://127.0.0.1:${settings.port}`);
     });
 
-    test("getUrl handles emoji in project directory", () => {
+    test("getUrl is independent of the project directory (emoji)", () => {
       const settings = createTestSettings(getNextPort());
-      const emojiPath = "/home/user/📁Notes";
-      const manager = new ServerManager(settings, emojiPath);
-
-      const url = manager.getUrl();
+      const manager = new ServerManager(settings, "/home/user/📁Notes");
 
-      expect(url).toContain(Buffer.from(emojiPath).toString('base64'));
+      expect(manager.getUrl()).toBe(`http://127.0.0.1:${settings.port}`);
     });
   });
 });
diff --git a/tests/serverUrl.test.ts b/tests/serverUrl.test.ts
new file mode 100644
index 0000000..edafb30
--- /dev/null
+++ b/tests/serverUrl.test.ts
@@ -0,0 +1,43 @@
+import { describe, test, expect } from "bun:test";
+import {
+  buildAuthHeader,
+  buildSessionUrl,
+  buildUiUrl,
+  encodeServerKey,
+  normalizeServerUrl,
+  resolveSessionId,
+} from "../src/lib/serverUrl";
+
+describe("serverUrl", () => {
+  test("normalizes trailing slashes", () => {
+    expect(normalizeServerUrl("http://127.0.0.1:14096/")).toBe("http://127.0.0.1:14096");
+    expect(normalizeServerUrl("http://127.0.0.1:14096")).toBe("http://127.0.0.1:14096");
+  });
+
+  test("builds the plain UI url without a project path segment", () => {
+    expect(buildUiUrl("http://127.0.0.1:14096/")).toBe("http://127.0.0.1:14096");
+  });
+
+  test("encodes the server key as base64url without padding", () => {
+    expect(encodeServerKey("http://127.0.0.1:14099")).toBe(
+      "aHR0cDovLzEyNy4wLjAuMToxNDA5OQ"
+    );
+  });
+
+  test("builds a v2 session url", () => {
+    expect(buildSessionUrl("http://127.0.0.1:14099/", "ses_abc")).toBe(
+      "http://127.0.0.1:14099/server/aHR0cDovLzEyNy4wLjAuMToxNDA5OQ/session/ses_abc"
+    );
+  });
+
+  test("builds a basic auth header for the opencode user", () => {
+    expect(buildAuthHeader("secret")).toBe(`Basic ${Buffer.from("opencode:secret").toString("base64")}`);
+  });
+
+  test("extracts the session id from a session url", () => {
+    expect(resolveSessionId("http://127.0.0.1:14099/server/abc/session/ses_123")).toBe(
+      "ses_123"
+    );
+    expect(resolveSessionId("http://127.0.0.1:14099/")).toBeNull();
+  });
+});