diff --git a/AGENTS.md b/AGENTS.md
index faae68b8..a29521b7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -217,7 +217,7 @@ OpenCode/Pi: event handler intercepts command
         ↓
 Input type detected:
   .md/.mdx   → file read from disk
-  .html/.htm → file read, converted to markdown via Turndown (or rendered as-is with --render-html)
+  .html/.htm → file read, rendered as raw HTML by default (or converted to markdown with --markdown)
   https://   → fetched via Jina Reader (default) or fetch+Turndown (--no-jina)
   folder/    → file browser opened, files converted on demand
         ↓
@@ -330,6 +330,8 @@ During normal plan review, an Archive sidebar tab provides the same browsing via
 | `/api/feedback`       | POST   | Submit annotations (body: feedback, annotations) |
 | `/api/approve`        | POST   | Approve without feedback (review-gate UX, `--gate`) |
 | `/api/exit`           | POST   | Close session without feedback |
+| `/api/html-assets/<token>/<path>` | GET | Serve relative support assets for raw HTML annotation sessions |
+| `/api/share-html`     | GET    | Lazily prepare portable raw HTML for sharing (`?path=<html-file>` optional) |
 | `/api/image`          | GET    | Serve image by path query param            |
 | `/api/upload`         | POST   | Upload image, returns `{ path, originalName }` |
 | `/api/doc`            | GET    | Serve linked .md/.mdx/.html file or code file (`?path=<path>&base=<dir>`) |
@@ -486,7 +488,7 @@ interface SharePayload {
   g?: ShareableImage[]; // Global attachments
   d?: (string | null)[]; // diffContext per annotation, parallel to `a`
   s?: (string | undefined)[]; // source per annotation (external tool identifier), parallel to `a`
-  h?: string; // Raw HTML content (--render-html mode)
+  h?: string; // Raw HTML content (direct HTML rendering mode)
   r?: 'html'; // Render mode flag (omitted = markdown)
 }
 
diff --git a/apps/amp-plugin/plannotator.test.ts b/apps/amp-plugin/plannotator.test.ts
index 8b12a5aa..0d4f59f9 100644
--- a/apps/amp-plugin/plannotator.test.ts
+++ b/apps/amp-plugin/plannotator.test.ts
@@ -91,6 +91,7 @@ describe("Amp Plannotator plugin helpers", () => {
 
   test("finds annotate target after flags", () => {
     expect(findFirstPositionalArg(["--no-jina", "https://example.com"])).toBe("https://example.com");
+    expect(findFirstPositionalArg(["--markdown", "docs/page.html"])).toBe("docs/page.html");
     expect(findFirstPositionalArg(["--browser", "Google Chrome", "docs/plan.md"])).toBe("docs/plan.md");
   });
 
diff --git a/apps/hook/README.md b/apps/hook/README.md
index 437969c7..373e590a 100644
--- a/apps/hook/README.md
+++ b/apps/hook/README.md
@@ -111,7 +111,7 @@ Plannotator's slash commands are installed as Claude Code skills in `~/.claude/s
 | Command | Description |
 |---------|-------------|
 | `/plannotator-review [--git]` | Open code review UI for current changes or a GitHub PR; `--git` forces Git in JJ workspaces |
-| `/plannotator-annotate <file.md>` | Annotate any markdown file |
+| `/plannotator-annotate <file.md \| file.html \| https://... \| folder/>` | Annotate a file, URL, or folder |
 | `/plannotator-last` | Annotate the agent's last message |
 
 ## Obsidian Integration
diff --git a/apps/hook/server/cli.test.ts b/apps/hook/server/cli.test.ts
index fb51ce33..1f094ef4 100644
--- a/apps/hook/server/cli.test.ts
+++ b/apps/hook/server/cli.test.ts
@@ -23,6 +23,7 @@ describe("CLI top-level help", () => {
     expect(output).toContain("plannotator [--browser <name>]");
     expect(output).toContain("plannotator review [--git] [PR_URL]");
     expect(output).toContain("plannotator annotate <file.md | file.html | https://... | folder/>");
+    expect(output).toContain("[--markdown] [--no-jina]");
     expect(output).toContain("plannotator annotate-last [--stdin]");
     expect(output).toContain("plannotator setup-goal <interview|facts>");
     expect(output).toContain("running 'plannotator' without arguments is for hook integration");
diff --git a/apps/hook/server/cli.ts b/apps/hook/server/cli.ts
index e2028705..3ddde914 100644
--- a/apps/hook/server/cli.ts
+++ b/apps/hook/server/cli.ts
@@ -26,7 +26,7 @@ export function formatTopLevelHelp(): string {
     "  plannotator --version, -v",
     "  plannotator [--browser <name>]",
     "  plannotator review [--git] [PR_URL]",
-    "  plannotator annotate <file.md | file.html | https://... | folder/>  [--no-jina] [--gate] [--json] [--hook]",
+    "  plannotator annotate <file.md | file.html | https://... | folder/>  [--markdown] [--no-jina] [--gate] [--json] [--hook]",
     "  plannotator annotate-last [--stdin] [--gate] [--json] [--hook]",
     "  plannotator setup-goal <interview|facts> <bundle.json | -> [--json]",
     "  plannotator last",
diff --git a/apps/hook/server/index.ts b/apps/hook/server/index.ts
index e30f6293..33fd0ad0 100644
--- a/apps/hook/server/index.ts
+++ b/apps/hook/server/index.ts
@@ -109,6 +109,7 @@ import {
 } from "@plannotator/shared/prompts";
 import { registerSession, unregisterSession, listSessions } from "@plannotator/server/sessions";
 import { openBrowser } from "@plannotator/server/browser";
+import { inlineHtmlLocalAssets } from "@plannotator/server/html-assets";
 import { detectProjectName } from "@plannotator/server/project";
 import { hostnameOrFallback } from "@plannotator/shared/project";
 import { readImprovementHook } from "@plannotator/shared/improvement-hooks";
@@ -178,8 +179,10 @@ const hookFlag = hookIdx !== -1;
 if (hookFlag) args.splice(hookIdx, 1);
 if (hookFlag) gateFlag = true;
 const renderHtmlIdx = args.indexOf("--render-html");
-const renderHtmlFlag = renderHtmlIdx !== -1;
-if (renderHtmlFlag) args.splice(renderHtmlIdx, 1);
+if (renderHtmlIdx !== -1) args.splice(renderHtmlIdx, 1);
+const renderMarkdownIdx = args.indexOf("--markdown");
+const renderMarkdownFlag = renderMarkdownIdx !== -1;
+if (renderMarkdownFlag) args.splice(renderMarkdownIdx, 1);
 
 // Stdout matrix for annotate / annotate-last / copilot annotate-last.
 //
@@ -867,7 +870,7 @@ if (args[0] === "sessions") {
 
   const rawFilePath = args[1];
   if (!rawFilePath) {
-    console.error("Usage: plannotator annotate <file.md | file.html | https://... | folder/>  [--no-jina] [--gate] [--json] [--hook]");
+    console.error("Usage: plannotator annotate <file.md | file.html | https://... | folder/>  [--markdown] [--no-jina] [--gate] [--json] [--hook]");
     process.exit(1);
   }
 
@@ -940,12 +943,9 @@ if (args[0] === "sessions") {
       if (htmlCandidate !== null) {
         const resolvedArg = resolveUserPath(htmlCandidate, projectRoot);
         const htmlFile = Bun.file(resolvedArg);
-        if (htmlFile.size > 10 * 1024 * 1024) {
-          console.error(`File too large (${Math.round(htmlFile.size / 1024 / 1024)}MB, max 10MB): ${resolvedArg}`);
-          process.exit(1);
-        }
         const html = await htmlFile.text();
-        if (renderHtmlFlag) {
+        const renderHtmlForFile = !renderMarkdownFlag;
+        if (renderHtmlForFile) {
           rawHtml = html;
           markdown = "";
         } else {
@@ -954,7 +954,7 @@ if (args[0] === "sessions") {
         }
         absolutePath = resolvedArg;
         sourceInfo = path.basename(resolvedArg);
-        console.error(`${renderHtmlFlag ? "Raw HTML" : "Converted"}: ${absolutePath}`);
+        console.error(`${renderHtmlForFile ? "Raw HTML" : "Converted"}: ${absolutePath}`);
       } else {
         // Single markdown file annotation mode
         // Strip-first with literal-@ fallback (scoped-package-style names).
@@ -1011,13 +1011,21 @@ if (args[0] === "sessions") {
     pasteApiUrl,
     gate: gateFlag,
     rawHtml,
-    renderHtml: renderHtmlFlag,
+    renderHtml: !!rawHtml,
+    convertHtml: renderMarkdownFlag,
     htmlContent: planHtmlContent,
     onReady: async (url, isRemote, port) => {
       handleAnnotateServerReady(url, isRemote, port);
 
-      if (isRemote && sharingEnabled && markdown) {
-        await writeRemoteShareLink(markdown, shareBaseUrl, "annotate", "document only").catch(() => {});
+      if (isRemote && sharingEnabled) {
+        if (rawHtml) {
+          await writeRemoteShareLink("", shareBaseUrl, "annotate", "HTML document only", {
+            rawHtml: inlineHtmlLocalAssets(rawHtml, absolutePath),
+            pasteApiUrl,
+          }).catch(() => {});
+        } else if (markdown) {
+          await writeRemoteShareLink(markdown, shareBaseUrl, "annotate", "document only").catch(() => {});
+        }
       }
     },
   });
diff --git a/apps/marketing/src/content/blog/annotate-any-web-page-or-html-file.md b/apps/marketing/src/content/blog/annotate-any-web-page-or-html-file.md
index d3b2abfe..4ce849b8 100644
--- a/apps/marketing/src/content/blog/annotate-any-web-page-or-html-file.md
+++ b/apps/marketing/src/content/blog/annotate-any-web-page-or-html-file.md
@@ -1,12 +1,12 @@
 ---
 title: "Annotate Any Web Page or HTML File"
-description: "Plannotator's /plannotator-annotate command now accepts URLs and HTML files, not just markdown. Fetch any web page, convert it to markdown, and annotate it with structured feedback for your coding agent."
+description: "Plannotator's /plannotator-annotate command now accepts URLs and HTML files, not just markdown. Fetch any web page, render local HTML, and annotate it with structured feedback for your coding agent."
 date: 2026-04-12
 author: "backnotprop"
 tags: ["annotate", "url", "html", "jina-reader"]
 ---
 
-**Plannotator is an open-source review UI for AI coding agents.** The `/plannotator-annotate` command now accepts URLs and HTML files alongside markdown, so you can pull in any external documentation, convert it on the fly, and send structured annotations back to your agent session.
+**Plannotator is an open-source review UI for AI coding agents.** The `/plannotator-annotate` command now accepts URLs and HTML files alongside markdown, so you can pull in any external documentation, render local HTML directly, and send structured annotations back to your agent session.
 
 <video width="100%" style="aspect-ratio: 16/9; border-radius: 8px; margin-bottom: 1.5rem;" autoplay loop muted playsinline controls><source src="https://d17ygohy796f9l.cloudfront.net/videos/annotate-url.mp4" type="video/mp4" /></video>
 
@@ -22,12 +22,13 @@ This was a [community-requested feature](https://github.com/backnotprop/plannota
 plannotator annotate https://docs.stripe.com/api      # remote URL
 plannotator annotate docs/guide.html                  # local HTML file
 plannotator annotate ./docs/                          # folder (now includes .html files)
+plannotator annotate docs/guide.html --markdown       # convert local HTML to markdown
 plannotator annotate https://... --no-jina            # direct fetch, no Jina
 ```
 
-All inputs are converted to markdown before reaching the annotation editor. You annotate, highlight, comment, and when you click Send Annotations, structured feedback goes back to the agent session.
+URLs are converted to markdown before reaching the annotation editor. Local HTML renders as HTML by default, with `--markdown` available when you want the old Turndown conversion path. You annotate, highlight, comment, and when you click Send Annotations, structured feedback goes back to the agent session.
 
-Local HTML files are read from disk and converted via Turndown. Folders now show `.html` and `.htm` files alongside markdown in the file browser, with conversion happening on demand. A source attribution badge appears under the document title so you know what you're looking at.
+Folders now show `.html` and `.htm` files alongside markdown in the file browser. A source attribution badge appears under the document title so you know what you're looking at.
 
 ## How URL fetching works
 
diff --git a/apps/marketing/src/content/docs/commands/annotate.md b/apps/marketing/src/content/docs/commands/annotate.md
index 0f002dfa..497b9cc6 100644
--- a/apps/marketing/src/content/docs/commands/annotate.md
+++ b/apps/marketing/src/content/docs/commands/annotate.md
@@ -13,7 +13,7 @@ The `/plannotator-annotate` command opens files, URLs, or folders in the Plannot
 | Input | Command | What happens |
 |-------|---------|--------------|
 | Markdown file | `plannotator annotate README.md` | Opens the file directly |
-| HTML file | `plannotator annotate docs/guide.html` | Converts to markdown via Turndown, then opens |
+| HTML file | `plannotator annotate docs/guide.html` | Renders the HTML directly |
 | URL | `plannotator annotate https://docs.stripe.com/api` | Fetches the page, converts to markdown, then opens |
 | Folder | `plannotator annotate ./docs/` | Opens a file browser showing all `.md`, `.mdx`, `.html`, and `.htm` files |
 
@@ -82,10 +82,20 @@ If none of these are set, Jina is enabled by default.
 
 ## HTML files
 
-Local `.html` and `.htm` files are read from disk and converted to markdown using [Turndown](https://github.com/mixmark-io/turndown) with GFM table support. `<script>`, `<style>`, and `<noscript>` tags are stripped before conversion.
+Local `.html` and `.htm` files are read from disk and rendered as HTML by default. If you want Plannotator to convert the file to markdown first, pass `--markdown`.
+
+```bash
+plannotator annotate docs/guide.html --markdown
+```
+
+Markdown conversion uses [Turndown](https://github.com/mixmark-io/turndown) with GFM table support. `<script>`, `<style>`, and `<noscript>` tags are stripped before conversion.
 
 HTML files must be within your current working directory. Files outside the project root return a 403 error.
 
+### `--markdown`
+
+For local HTML files, `--markdown` switches from raw HTML rendering to markdown conversion. In folder mode, the same setting applies when you open `.html` or `.htm` files from the file browser.
+
 ## Source badge
 
 When annotating an HTML file or URL (not plain markdown), a small badge appears under the document title showing where the content came from. For URLs it shows the hostname (e.g. "stripe.com"). For HTML files it shows the filename (e.g. "guide.html").
diff --git a/apps/marketing/src/content/docs/guides/self-hosting.md b/apps/marketing/src/content/docs/guides/self-hosting.md
index 246c4e59..41ff4323 100644
--- a/apps/marketing/src/content/docs/guides/self-hosting.md
+++ b/apps/marketing/src/content/docs/guides/self-hosting.md
@@ -96,7 +96,7 @@ Pastes stored to `~/.plannotator/pastes/` by default.
 | `PASTE_PORT` | `19433` | Server port |
 | `PASTE_DATA_DIR` | `~/.plannotator/pastes` | Storage directory |
 | `PASTE_TTL_DAYS` | `7` | Auto-delete after N days |
-| `PASTE_MAX_SIZE` | `524288` | Max payload size (512KB) |
+| `PASTE_MAX_SIZE` | `5242880` | Max encrypted payload size (5 MB) |
 | `PASTE_ALLOWED_ORIGINS` | (see defaults) | CORS allowed origins |
 
 ## 4. Connect the Components
diff --git a/apps/marketing/src/content/docs/reference/api-endpoints.md b/apps/marketing/src/content/docs/reference/api-endpoints.md
index dce40166..b1511e93 100644
--- a/apps/marketing/src/content/docs/reference/api-endpoints.md
+++ b/apps/marketing/src/content/docs/reference/api-endpoints.md
@@ -117,6 +117,7 @@ Used during file annotation (`/plannotator-annotate`).
 |----------|--------|---------|
 | `/api/plan` | GET | Returns the file content in annotate mode |
 | `/api/feedback` | POST | Submit annotation feedback |
+| `/api/share-html` | GET | Lazily prepare portable raw HTML for sharing |
 | `/api/image` | GET | Serve a local image by path |
 | `/api/upload` | POST | Upload an image attachment |
 | `/api/external-annotations/stream` | GET | SSE stream for real-time external annotations |
@@ -172,7 +173,7 @@ Body:
 
 Returns: `{ "id": "aBcDeFgH" }` (201 Created)
 
-Limits: 512KB max payload. Auto-deleted after configured TTL (default: 7 days).
+Limits: 5 MB max encrypted payload. Auto-deleted after configured TTL (default: 7 days).
 
 ### GET `/api/paste/:id`
 
diff --git a/apps/marketing/src/content/docs/reference/environment-variables.md b/apps/marketing/src/content/docs/reference/environment-variables.md
index a5b1626e..0fab9d8c 100644
--- a/apps/marketing/src/content/docs/reference/environment-variables.md
+++ b/apps/marketing/src/content/docs/reference/environment-variables.md
@@ -56,7 +56,7 @@ When running your own paste service binary, these variables configure it:
 | `PASTE_PORT` | `19433` | Server port |
 | `PASTE_DATA_DIR` | `~/.plannotator/pastes` | Filesystem storage directory |
 | `PASTE_TTL_DAYS` | `7` | Paste expiration in days |
-| `PASTE_MAX_SIZE` | `524288` | Max payload size in bytes (512KB) |
+| `PASTE_MAX_SIZE` | `5242880` | Max encrypted payload size in bytes (5 MB) |
 | `PASTE_ALLOWED_ORIGINS` | `https://share.plannotator.ai,http://localhost:3001` | CORS allowed origins (comma-separated) |
 
 ## Install script variables
diff --git a/apps/opencode-plugin/cli-bridge.test.ts b/apps/opencode-plugin/cli-bridge.test.ts
index 51acc498..9e21ae08 100644
--- a/apps/opencode-plugin/cli-bridge.test.ts
+++ b/apps/opencode-plugin/cli-bridge.test.ts
@@ -36,6 +36,7 @@ describe("OpenCode CLI bridge helpers", () => {
       json: false,
       hook: false,
       renderHtml: true,
+      renderMarkdown: false,
       noJina: true,
     });
 
@@ -49,6 +50,26 @@ describe("OpenCode CLI bridge helpers", () => {
     ]);
   });
 
+  test("passes annotate markdown flag through to the child CLI", () => {
+    const args = buildAnnotateCliArgs({
+      filePath: "plan.html",
+      rawFilePath: "plan.html",
+      gate: false,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      renderMarkdown: true,
+      noJina: false,
+    });
+
+    expect(args).toEqual([
+      "annotate",
+      "plan.html",
+      "--json",
+      "--markdown",
+    ]);
+  });
+
   test("surfaces remote share-link stderr lines and ignores noisy stderr", () => {
     expect(formatUserFacingCliStderrLine("  Open this link on your local machine to review the plan:")).toBe(
       "Open this link on your local machine to review the plan:",
diff --git a/apps/opencode-plugin/cli-bridge.ts b/apps/opencode-plugin/cli-bridge.ts
index 6d4b0479..337d9eea 100644
--- a/apps/opencode-plugin/cli-bridge.ts
+++ b/apps/opencode-plugin/cli-bridge.ts
@@ -325,6 +325,7 @@ export function buildAnnotateCliArgs(parsed: ParsedAnnotateArgs): string[] {
   const args = ["annotate", parsed.rawFilePath, "--json"];
   if (parsed.gate) args.push("--gate");
   if (parsed.renderHtml) args.push("--render-html");
+  if (parsed.renderMarkdown) args.push("--markdown");
   if (parsed.noJina) args.push("--no-jina");
   return args;
 }
@@ -492,7 +493,7 @@ export async function handleCliCommand(input: {
     if (input.command === "plannotator-annotate") {
       const parsed = parseAnnotateArgs(input.rawArgs);
       if (!parsed.filePath) {
-        log(input.client, "error", "Usage: /plannotator-annotate <file.md | file.html | https://... | folder/> [--no-jina] [--gate] [--json]");
+        log(input.client, "error", "Usage: /plannotator-annotate <file.md | file.html | https://... | folder/> [--markdown] [--no-jina] [--gate] [--json]");
         return;
       }
 
diff --git a/apps/opencode-plugin/commands.test.ts b/apps/opencode-plugin/commands.test.ts
index 678e0fbe..37d15c02 100644
--- a/apps/opencode-plugin/commands.test.ts
+++ b/apps/opencode-plugin/commands.test.ts
@@ -72,7 +72,36 @@ describe("handleAnnotateCommand", () => {
     expect(options.mode).toBe("annotate");
     expect(options.pasteApiUrl).toBe("https://paste.example.test");
     expect(options.shareBaseUrl).toBe("https://share.example.test");
-    expect(options.markdown).toContain("Design Spec");
+    expect(options.markdown).toBe("");
+    expect(options.rawHtml).toContain("<h1>Design Spec</h1>");
+    expect(options.renderHtml).toBe(true);
+    expect(options.convertHtml).toBe(false);
+    expect(options.sourceConverted).toBe(false);
+  });
+
+  test("--markdown converts HTML paths via Turndown", async () => {
+    const projectRoot = makeTempDir();
+    const docsDir = path.join(projectRoot, "docs");
+    mkdirSync(docsDir, { recursive: true });
+    const htmlPath = path.join(docsDir, "Design Spec.html");
+    writeFileSync(htmlPath, "<h1>Design Spec</h1><p>Body</p>");
+
+    const deps = makeDeps();
+    deps.directory = projectRoot;
+
+    await handleAnnotateCommand(
+      { properties: { arguments: "\"docs/Design Spec.html\" --markdown" } },
+      deps,
+    );
+
+    expect(startAnnotateServerMock).toHaveBeenCalledTimes(1);
+    const options = startAnnotateServerMock.mock.calls[0]?.[0];
+    expect(options.filePath).toBe(htmlPath);
+    expect(options.markdown).toContain("# Design Spec");
+    expect(options.rawHtml).toBeUndefined();
+    expect(options.renderHtml).toBe(false);
+    expect(options.convertHtml).toBe(true);
+    expect(options.sourceConverted).toBe(true);
   });
 
   test("supports quoted folder paths and opens annotate-folder mode", async () => {
diff --git a/apps/opencode-plugin/commands.ts b/apps/opencode-plugin/commands.ts
index daa576e4..33826285 100644
--- a/apps/opencode-plugin/commands.ts
+++ b/apps/opencode-plugin/commands.ts
@@ -201,10 +201,10 @@ export async function handleAnnotateCommand(
   // --json is accepted silently (OpenCode writes to session, not stdout).
   // parseAnnotateArgs strips leading @ on filePath (reference-mode convention).
   // `rawFilePath` preserves it for the scoped-package markdown fallback.
-  const { filePath, rawFilePath, gate, renderHtml: renderHtmlFlag, noJina } = parseAnnotateArgs(rawArgs);
+  const { filePath, rawFilePath, gate, renderMarkdown: renderMarkdownFlag, noJina } = parseAnnotateArgs(rawArgs);
 
   if (!filePath) {
-    client.app.log({ level: "error", message: "Usage: /plannotator-annotate <file.md | file.html | https://... | folder/> [--no-jina] [--gate] [--json]" });
+    client.app.log({ level: "error", message: "Usage: /plannotator-annotate <file.md | file.html | https://... | folder/> [--markdown] [--no-jina] [--gate] [--json]" });
     return;
   }
 
@@ -254,19 +254,15 @@ export async function handleAnnotateCommand(
       annotateMode = "annotate-folder";
       client.app.log({ level: "info", message: `Opening annotation UI for folder ${resolvedArg}...` });
     } else if (/\.html?$/i.test(resolvedArg)) {
-      let fileSize: number;
       try {
-        fileSize = statSync(resolvedArg).size;
+        statSync(resolvedArg);
       } catch {
         client.app.log({ level: "error", message: `File not found: ${filePath}` });
         return;
       }
-      if (fileSize > 10 * 1024 * 1024) {
-        client.app.log({ level: "error", message: `File too large (${Math.round(fileSize / 1024 / 1024)}MB, max 10MB)` });
-        return;
-      }
       const html = await Bun.file(resolvedArg).text();
-      if (renderHtmlFlag) {
+      const renderHtmlForFile = !renderMarkdownFlag;
+      if (renderHtmlForFile) {
         rawHtml = html;
         markdown = "";
       } else {
@@ -275,7 +271,7 @@ export async function handleAnnotateCommand(
       }
       absolutePath = resolvedArg;
       sourceInfo = path.basename(resolvedArg);
-      client.app.log({ level: "info", message: `${renderHtmlFlag ? "Raw HTML" : "Converted"}: ${absolutePath}` });
+      client.app.log({ level: "info", message: `${renderHtmlForFile ? "Raw HTML" : "Converted"}: ${absolutePath}` });
     } else {
       // Markdown file annotation
       client.app.log({ level: "info", message: `Opening annotation UI for ${filePath}...` });
@@ -312,7 +308,8 @@ export async function handleAnnotateCommand(
     sourceInfo,
     sourceConverted,
     rawHtml,
-    renderHtml: renderHtmlFlag,
+    renderHtml: !!rawHtml,
+    convertHtml: renderMarkdownFlag,
     sharingEnabled: await getSharingEnabled(),
     shareBaseUrl: getShareBaseUrl(),
     pasteApiUrl: getPasteApiUrl(),
diff --git a/apps/opencode-plugin/commands/plannotator-annotate.md b/apps/opencode-plugin/commands/plannotator-annotate.md
index 6a9c58fb..ae16d4a2 100644
--- a/apps/opencode-plugin/commands/plannotator-annotate.md
+++ b/apps/opencode-plugin/commands/plannotator-annotate.md
@@ -1,3 +1,3 @@
 ---
-description: Open interactive annotation UI for a markdown file, HTML file, or URL
+description: Open interactive annotation UI for a file, folder, or URL
 ---
diff --git a/apps/paste-service/core/handler.test.ts b/apps/paste-service/core/handler.test.ts
new file mode 100644
index 00000000..e1ed1856
--- /dev/null
+++ b/apps/paste-service/core/handler.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createPaste,
+  DEFAULT_PASTE_MAX_SIZE,
+} from "./handler";
+import type { PasteStore } from "./storage";
+
+class MemoryPasteStore implements PasteStore {
+  values = new Map<string, string>();
+
+  async put(id: string, data: string): Promise<void> {
+    this.values.set(id, data);
+  }
+
+  async get(id: string): Promise<string | null> {
+    return this.values.get(id) ?? null;
+  }
+}
+
+describe("paste payload limits", () => {
+  test("default limit accepts HTML-scale encrypted payloads above the old 512 KB ceiling", async () => {
+    const store = new MemoryPasteStore();
+
+    const result = await createPaste("x".repeat(600 * 1024), store);
+
+    expect(result.id).toHaveLength(8);
+    expect(store.values.get(result.id)).toHaveLength(600 * 1024);
+  });
+
+  test("rejects payloads above the default encrypted payload limit", async () => {
+    const store = new MemoryPasteStore();
+
+    await expect(createPaste("x".repeat(DEFAULT_PASTE_MAX_SIZE + 1), store))
+      .rejects
+      .toMatchObject({
+        status: 413,
+        message: "Payload too large (max 5 MB encrypted)",
+      });
+  });
+});
diff --git a/apps/paste-service/core/handler.ts b/apps/paste-service/core/handler.ts
index 716316b7..0a56bc16 100644
--- a/apps/paste-service/core/handler.ts
+++ b/apps/paste-service/core/handler.ts
@@ -6,8 +6,10 @@ export interface PasteOptions {
   ttlSeconds: number;
 }
 
+export const DEFAULT_PASTE_MAX_SIZE = 5 * 1024 * 1024;
+
 const DEFAULT_OPTIONS: PasteOptions = {
-  maxSize: 524_288, // 512 KB
+  maxSize: DEFAULT_PASTE_MAX_SIZE,
   ttlSeconds: 7 * 24 * 60 * 60, // 7 days
 };
 
@@ -48,7 +50,7 @@ export async function createPaste(
 
   if (data.length > opts.maxSize) {
     throw new PasteError(
-      `Payload too large (max ${Math.round(opts.maxSize / 1024)} KB compressed)`,
+      `Payload too large (max ${formatByteLimit(opts.maxSize)} encrypted)`,
       413
     );
   }
@@ -58,6 +60,13 @@ export async function createPaste(
   return { id };
 }
 
+function formatByteLimit(bytes: number): string {
+  if (bytes >= 1024 * 1024) {
+    return `${Math.round(bytes / 1024 / 1024)} MB`;
+  }
+  return `${Math.round(bytes / 1024)} KB`;
+}
+
 export async function getPaste(
   id: string,
   store: PasteStore
diff --git a/apps/paste-service/targets/bun.ts b/apps/paste-service/targets/bun.ts
index a670e924..25651220 100644
--- a/apps/paste-service/targets/bun.ts
+++ b/apps/paste-service/targets/bun.ts
@@ -1,6 +1,6 @@
 import { homedir } from "os";
 import { join } from "path";
-import { handleRequest } from "../core/handler";
+import { DEFAULT_PASTE_MAX_SIZE, handleRequest } from "../core/handler";
 import { corsHeaders, getAllowedOrigins } from "../core/cors";
 import { FsPasteStore } from "../stores/fs";
 
@@ -9,7 +9,7 @@ const dataDir =
   process.env.PASTE_DATA_DIR || join(homedir(), ".plannotator", "pastes");
 const ttlDays = parseInt(process.env.PASTE_TTL_DAYS || "7", 10);
 const ttlSeconds = ttlDays * 24 * 60 * 60;
-const maxSize = parseInt(process.env.PASTE_MAX_SIZE || "524288", 10);
+const maxSize = parseInt(process.env.PASTE_MAX_SIZE || String(DEFAULT_PASTE_MAX_SIZE), 10);
 const allowedOrigins = getAllowedOrigins(process.env.PASTE_ALLOWED_ORIGINS);
 
 const store = new FsPasteStore(dataDir);
diff --git a/apps/pi-extension/index.ts b/apps/pi-extension/index.ts
index 2867b405..c93660c2 100644
--- a/apps/pi-extension/index.ts
+++ b/apps/pi-extension/index.ts
@@ -488,9 +488,9 @@ export default function plannotator(pi: ExtensionAPI): void {
 			// accepted (Pi writes back via sendUserMessage, not stdout).
 			// `rawFilePath` keeps any leading `@` for the literal-@ fallback
 			// (scoped-package-style names).
-			const { filePath, rawFilePath, gate, renderHtml: renderHtmlFlag, noJina } = parseAnnotateArgs(args ?? "");
+			const { filePath, rawFilePath, gate, renderMarkdown: renderMarkdownFlag, noJina } = parseAnnotateArgs(args ?? "");
 			if (!filePath) {
-				ctx.ui.notify("Usage: /plannotator-annotate <file.md | file.html | https://... | folder/> [--no-jina] [--gate] [--json]", "error");
+				ctx.ui.notify("Usage: /plannotator-annotate <file.md | file.html | https://... | folder/> [--markdown] [--no-jina] [--gate] [--json]", "error");
 				return;
 			}
 			if (!hasPlanBrowserHtml()) {
@@ -559,14 +559,9 @@ export default function plannotator(pi: ExtensionAPI): void {
 					mode = "annotate-folder";
 					ctx.ui.notify(`Opening annotation UI for folder ${filePath}...`, "info");
 				} else if (/\.html?$/i.test(absolutePath)) {
-					// HTML file annotation — convert to markdown via Turndown
-					const fileSize = statSync(absolutePath).size;
-					if (fileSize > 10 * 1024 * 1024) {
-						ctx.ui.notify(`File too large (${Math.round(fileSize / 1024 / 1024)}MB, max 10MB)`, "error");
-						return;
-					}
 					const html = readFileSync(absolutePath, "utf-8");
-					if (renderHtmlFlag) {
+					const renderHtmlForFile = !renderMarkdownFlag;
+					if (renderHtmlForFile) {
 						rawHtml = html;
 						markdown = "";
 					} else {
@@ -595,7 +590,8 @@ export default function plannotator(pi: ExtensionAPI): void {
 					sourceConverted,
 					gate,
 					rawHtml,
-					renderHtmlFlag,
+					!!rawHtml,
+					renderMarkdownFlag,
 				);
 				ctx.ui.notify("Annotation opened. You can keep chatting while it runs.", "info");
 				void session
diff --git a/apps/pi-extension/package.json b/apps/pi-extension/package.json
index e00ef06c..06eea1c8 100644
--- a/apps/pi-extension/package.json
+++ b/apps/pi-extension/package.json
@@ -41,6 +41,7 @@
   "dependencies": {
     "@joplin/turndown-plugin-gfm": "^1.0.64",
     "@pierre/diffs": "1.2.8",
+    "parse5": "^7.3.0",
     "turndown": "^7.2.4"
   },
   "peerDependencies": {
diff --git a/apps/pi-extension/plannotator-browser.ts b/apps/pi-extension/plannotator-browser.ts
index e9396e19..82d366f0 100644
--- a/apps/pi-extension/plannotator-browser.ts
+++ b/apps/pi-extension/plannotator-browser.ts
@@ -523,6 +523,7 @@ export async function startMarkdownAnnotationSession(
 	gate?: boolean,
 	rawHtml?: string,
 	renderHtml?: boolean,
+	convertHtml?: boolean,
 	recentMessages?: { messageId: string; text: string; timestamp?: string }[],
 ): Promise<BrowserDecisionSession<{ feedback: string; exit?: boolean; approved?: boolean; selectedMessageId?: string; feedbackScope?: "message" | "messages" }>> {
 	if (!ctx.hasUI || !planHtmlContent) {
@@ -553,6 +554,7 @@ export async function startMarkdownAnnotationSession(
 		gate,
 		rawHtml,
 		renderHtml,
+		convertHtml,
 		htmlContent: planHtmlContent,
 		sharingEnabled: process.env.PLANNOTATOR_SHARE !== "disabled",
 		shareBaseUrl: process.env.PLANNOTATOR_SHARE_URL || undefined,
@@ -589,6 +591,7 @@ export async function startLastMessageAnnotationSession(
 		gate,
 		undefined,
 		undefined,
+		undefined,
 		recentMessages,
 	);
 }
diff --git a/apps/pi-extension/server/reference.ts b/apps/pi-extension/server/reference.ts
index f71dfe6f..5b1354fe 100644
--- a/apps/pi-extension/server/reference.ts
+++ b/apps/pi-extension/server/reference.ts
@@ -38,6 +38,10 @@ import { preloadFile } from "@pierre/diffs/ssr";
 
 type Res = ServerResponse;
 
+export interface HandleDocOptions {
+	rewriteHtml?: (html: string, filepath: string) => string;
+}
+
 /** Recursively walk a directory collecting files by extension, skipping ignored dirs. */
 function walkMarkdownFiles(dir: string, root: string, results: string[], extensions: RegExp = /\.(mdx?|html?)$/i): void {
 	let entries: Dirent[];
@@ -60,7 +64,7 @@ function walkMarkdownFiles(dir: string, root: string, results: string[], extensi
 }
 
 /** Serve a linked markdown document. Uses shared resolveMarkdownFile for parity with Bun server. */
-export async function handleDocRequest(res: Res, url: URL): Promise<void> {
+export async function handleDocRequest(res: Res, url: URL, options: HandleDocOptions = {}): Promise<void> {
 	const requestedPath = url.searchParams.get("path");
 	if (!requestedPath) {
 		json(res, { error: "Missing path parameter" }, 400);
@@ -77,6 +81,7 @@ export async function handleDocRequest(res: Res, url: URL): Promise<void> {
 	// block below (no base) retains its cwd-based containment check.
 	const base = url.searchParams.get("base");
 	const resolvedBase = base ? resolveUserPath(base) : null;
+	const convert = url.searchParams.get("convert") === "1";
 	if (
 		resolvedBase &&
 		!isAbsoluteUserPath(requestedPath) &&
@@ -87,8 +92,13 @@ export async function handleDocRequest(res: Res, url: URL): Promise<void> {
 			if (existsSync(fromBase)) {
 				const raw = readFileSync(fromBase, "utf-8");
 				const isHtml = /\.html?$/i.test(requestedPath);
+				if (isHtml && !convert) {
+					const rawHtml = options.rewriteHtml ? options.rewriteHtml(raw, fromBase) : raw;
+					json(res, { rawHtml, renderAs: "html", filepath: fromBase });
+					return;
+				}
 				const markdown = isHtml ? htmlToMarkdown(raw) : raw;
-				json(res, { markdown, filepath: fromBase, isConverted: isHtml });
+				json(res, { markdown, filepath: fromBase, isConverted: isHtml, renderAs: "markdown" });
 				return;
 			}
 		} catch {
@@ -107,7 +117,12 @@ export async function handleDocRequest(res: Res, url: URL): Promise<void> {
 		try {
 			if (existsSync(resolvedHtml)) {
 				const html = readFileSync(resolvedHtml, "utf-8");
-				json(res, { markdown: htmlToMarkdown(html), filepath: resolvedHtml, isConverted: true });
+				if (!convert) {
+					const rawHtml = options.rewriteHtml ? options.rewriteHtml(html, resolvedHtml) : html;
+					json(res, { rawHtml, renderAs: "html", filepath: resolvedHtml });
+					return;
+				}
+				json(res, { markdown: htmlToMarkdown(html), filepath: resolvedHtml, isConverted: true, renderAs: "markdown" });
 				return;
 			}
 		} catch { /* fall through to 404 */ }
diff --git a/apps/pi-extension/server/serverAnnotate.ts b/apps/pi-extension/server/serverAnnotate.ts
index a8e797ba..0f7ecaa5 100644
--- a/apps/pi-extension/server/serverAnnotate.ts
+++ b/apps/pi-extension/server/serverAnnotate.ts
@@ -1,5 +1,7 @@
 import { createServer } from "node:http";
-import { dirname, resolve as resolvePath } from "node:path";
+import { dirname, isAbsolute, relative, resolve as resolvePath } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 
 import { contentHash, deleteDraft } from "../generated/draft.js";
 import { saveConfig, detectGitUser, getServerConfig } from "../generated/config.js";
@@ -26,6 +28,14 @@ import {
 } from "./reference.js";
 import { warmFileListCache } from "../generated/resolve-file.js";
 import { createExternalAnnotationHandler } from "./external-annotations.js";
+import {
+	HTML_ASSET_ROUTE_PREFIX,
+	encodeHtmlAssetPath,
+	htmlAssetContentType,
+	normalizeHtmlAssetRoutePath,
+	rewriteHtmlAssetReferences,
+} from "../generated/html-assets.js";
+import { inlineHtmlLocalAssets, MAX_HTML_ASSET_BYTES } from "../generated/html-assets-node.js";
 
 export interface AnnotateServerResult {
 	port: number;
@@ -35,6 +45,105 @@ export interface AnnotateServerResult {
 	stop: () => void;
 }
 
+function createHtmlAssetRegistry() {
+	const rootsByToken = new Map<string, string>();
+	const tokensByRoot = new Map<string, string>();
+
+	function register(baseDir: string): string {
+		const root = resolvePath(baseDir);
+		const existing = tokensByRoot.get(root);
+		if (existing) return existing;
+		const token = randomUUID().replace(/-/g, "").slice(0, 16);
+		tokensByRoot.set(root, token);
+		rootsByToken.set(token, root);
+		return token;
+	}
+
+	function rewriteHtml(htmlContent: string, htmlFilePath: string): string {
+		if (/^https?:\/\//i.test(htmlFilePath)) return htmlContent;
+		try {
+			const token = register(dirname(resolvePath(htmlFilePath)));
+			return rewriteHtmlAssetReferences(
+				htmlContent,
+				(assetPath) => `${HTML_ASSET_ROUTE_PREFIX}/${token}/${encodeHtmlAssetPath(assetPath)}`,
+			);
+		} catch {
+			return htmlContent;
+		}
+	}
+
+	function inlineHtml(htmlContent: string, htmlFilePath: string): string {
+		return inlineHtmlLocalAssets(htmlContent, htmlFilePath);
+	}
+
+	function handle(res: import("node:http").ServerResponse, url: URL): boolean {
+		const prefix = `${HTML_ASSET_ROUTE_PREFIX}/`;
+		if (!url.pathname.startsWith(prefix)) return false;
+
+		const rest = url.pathname.slice(prefix.length);
+		const slash = rest.indexOf("/");
+		if (slash <= 0) {
+			json(res, { error: "Missing asset token or path" }, 404);
+			return true;
+		}
+
+		const token = rest.slice(0, slash);
+		const root = rootsByToken.get(token);
+		if (!root) {
+			json(res, { error: "Unknown asset root" }, 404);
+			return true;
+		}
+
+		const assetPath = normalizeHtmlAssetRoutePath(rest.slice(slash + 1));
+		if (!assetPath) {
+			json(res, { error: "Invalid asset path" }, 400);
+			return true;
+		}
+
+		const contentType = htmlAssetContentType(assetPath);
+		if (!contentType) {
+			json(res, { error: "Unsupported asset type" }, 415);
+			return true;
+		}
+
+		const resolved = resolvePath(root, assetPath);
+		if (!isWithinDirectory(resolved, root)) {
+			json(res, { error: "Access denied" }, 403);
+			return true;
+		}
+
+		try {
+			if (!existsSync(resolved)) {
+				json(res, { error: "Asset not found" }, 404);
+				return true;
+			}
+			const stat = statSync(resolved);
+			if (stat.size > MAX_HTML_ASSET_BYTES) {
+				json(res, { error: "Asset too large" }, 413);
+				return true;
+			}
+			res.writeHead(200, {
+				"Content-Type": contentType,
+				"Cache-Control": "no-store",
+				"Access-Control-Allow-Origin": "*",
+			});
+			res.end(readFileSync(resolved));
+		} catch {
+			json(res, { error: "Failed to read asset" }, 500);
+		}
+		return true;
+	}
+
+	return { rewriteHtml, inlineHtml, handle };
+}
+
+function isWithinDirectory(filePath: string, root: string): boolean {
+	const resolved = resolvePath(filePath);
+	const resolvedRoot = resolvePath(root);
+	const rel = relative(resolvedRoot, resolved);
+	return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
+
 export async function startAnnotateServer(options: {
 	markdown: string;
 	filePath: string;
@@ -51,6 +160,7 @@ export async function startAnnotateServer(options: {
 	gate?: boolean;
 	rawHtml?: string;
 	renderHtml?: boolean;
+	convertHtml?: boolean;
 }): Promise<AnnotateServerResult> {
 	// Side-channel pre-warm so /api/doc/exists POSTs land on warm cache.
 	void warmFileListCache(process.cwd(), "code");
@@ -93,6 +203,46 @@ export async function startAnnotateServer(options: {
 
 	const externalAnnotations = createExternalAnnotationHandler("plan");
 	const aiRuntime = await createPiAIRuntime();
+	const htmlAssets = createHtmlAssetRegistry();
+
+	function isAllowedHtmlSharePath(targetPath: string): boolean {
+		const roots = new Set<string>([process.cwd()]);
+		if (options.folderPath) roots.add(options.folderPath);
+		if (!/^https?:\/\//i.test(options.filePath)) roots.add(dirname(options.filePath));
+		for (const root of roots) {
+			if (isWithinDirectory(targetPath, root)) return true;
+		}
+		return false;
+	}
+
+	function handleShareHtml(res: import("node:http").ServerResponse, url: URL): void {
+		if (/^https?:\/\//i.test(options.filePath)) {
+			json(res, { error: "Raw HTML sharing is unavailable for URL annotations" }, 400);
+			return;
+		}
+
+		const sourcePath = resolvePath(options.filePath);
+		const requestedPath = url.searchParams.get("path")
+			? resolvePath(url.searchParams.get("path")!)
+			: sourcePath;
+		if (!/\.html?$/i.test(requestedPath)) {
+			json(res, { error: "Share HTML is only available for HTML documents" }, 400);
+			return;
+		}
+		if (!isAllowedHtmlSharePath(requestedPath)) {
+			json(res, { error: "Access denied" }, 403);
+			return;
+		}
+
+		try {
+			const htmlContent = options.renderHtml && options.rawHtml && requestedPath === sourcePath
+				? options.rawHtml
+				: readFileSync(requestedPath, "utf-8");
+			json(res, { shareHtml: htmlAssets.inlineHtml(htmlContent, requestedPath) });
+		} catch {
+			json(res, { error: "Failed to prepare share HTML" }, 500);
+		}
+	}
 
 	const server = createServer(async (req, res) => {
 		const url = requestUrl(req);
@@ -101,6 +251,9 @@ export async function startAnnotateServer(options: {
 		if (url.pathname.startsWith("/api/ai/") && await handlePiAIRequest(req, res, url, aiRuntime)) return;
 
 		if (url.pathname === "/api/plan" && req.method === "GET") {
+			const displayRawHtml = options.renderHtml && options.rawHtml
+				? htmlAssets.rewriteHtml(options.rawHtml, options.filePath)
+				: undefined;
 			json(res, {
 				plan: options.markdown,
 				origin: options.origin ?? "pi",
@@ -109,8 +262,9 @@ export async function startAnnotateServer(options: {
 				sourceInfo: options.sourceInfo,
 				sourceConverted: options.sourceConverted ?? false,
 				gate: options.gate ?? false,
-				renderAs: options.renderHtml && options.rawHtml ? 'html' : 'markdown',
-				...(options.renderHtml && options.rawHtml ? { rawHtml: options.rawHtml } : {}),
+				renderAs: displayRawHtml ? 'html' : 'markdown',
+				...(displayRawHtml ? { rawHtml: displayRawHtml } : {}),
+				convertHtml: options.convertHtml ?? false,
 				sharingEnabled,
 				shareBaseUrl,
 				pasteApiUrl,
@@ -119,6 +273,8 @@ export async function startAnnotateServer(options: {
 				serverConfig: getServerConfig(gitUser),
 				...(options.recentMessages ? { recentMessages: options.recentMessages } : {}),
 			});
+		} else if (url.pathname === "/api/share-html" && req.method === "GET") {
+			handleShareHtml(res, url);
 		} else if (url.pathname === "/api/config" && req.method === "POST") {
 			try {
 				const body = (await parseBody(req)) as { displayName?: string; diffOptions?: Record<string, unknown>; conventionalComments?: boolean };
@@ -133,6 +289,8 @@ export async function startAnnotateServer(options: {
 			}
 		} else if (url.pathname === "/api/image") {
 			handleImageRequest(res, url);
+		} else if (htmlAssets.handle(res, url)) {
+			return;
 		} else if (url.pathname === "/api/upload" && req.method === "POST") {
 			await handleUploadRequest(req, res);
 		} else if (url.pathname === "/api/draft") {
@@ -143,7 +301,12 @@ export async function startAnnotateServer(options: {
 			if (!url.searchParams.has("base") && options.filePath && !/^https?:\/\//i.test(options.filePath)) {
 				url.searchParams.set("base", dirname(resolvePath(options.filePath)));
 			}
-			await handleDocRequest(res, url);
+			if (options.convertHtml && !url.searchParams.has("convert")) {
+				url.searchParams.set("convert", "1");
+			}
+			await handleDocRequest(res, url, {
+				rewriteHtml: htmlAssets.rewriteHtml,
+			});
 		} else if (url.pathname === "/api/doc/exists" && req.method === "POST") {
 			await handleDocExistsRequest(res, req);
 		} else if (url.pathname === "/api/obsidian/vaults") {
diff --git a/apps/pi-extension/vendor.sh b/apps/pi-extension/vendor.sh
index 9a218ae8..7252a940 100755
--- a/apps/pi-extension/vendor.sh
+++ b/apps/pi-extension/vendor.sh
@@ -7,7 +7,7 @@ cd "$(dirname "$0")"
 rm -rf generated
 mkdir -p generated generated/ai/providers
 
-for f in feedback-templates prompts review-core diff-paths cli-pagination jj-core vcs-core review-args storage draft project pr-types pr-provider pr-stack pr-github pr-gitlab checklist integrations-common repo reference-common favicon code-file resolve-file config external-annotation agent-jobs worktree worktree-pool html-to-markdown url-to-markdown tour annotate-args at-reference review-workspace-node review-workspace pfm-reminder improvement-hooks code-nav data-dir semantic-diff-types semantic-diff; do
+for f in feedback-templates prompts review-core diff-paths cli-pagination jj-core vcs-core review-args storage draft project pr-types pr-provider pr-stack pr-github pr-gitlab checklist integrations-common repo reference-common favicon code-file resolve-file config external-annotation agent-jobs worktree worktree-pool html-to-markdown html-assets html-assets-node url-to-markdown tour annotate-args at-reference review-workspace-node review-workspace pfm-reminder improvement-hooks code-nav data-dir semantic-diff-types semantic-diff; do
   src="../../packages/shared/$f.ts"
   printf '// @generated — DO NOT EDIT. Source: packages/shared/%s.ts\n' "$f" | cat - "$src" > "generated/$f.ts"
 done
diff --git a/apps/skills/claude/plannotator-annotate/SKILL.md b/apps/skills/claude/plannotator-annotate/SKILL.md
index a91967ec..5dc7e373 100644
--- a/apps/skills/claude/plannotator-annotate/SKILL.md
+++ b/apps/skills/claude/plannotator-annotate/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: plannotator-annotate
-description: Open Plannotator's annotation UI for a markdown file, converted HTML file, URL, or folder and then respond to the returned annotations.
+description: Open Plannotator's annotation UI for a markdown file, HTML file, URL, or folder and then respond to the returned annotations.
 allowed-tools: Bash(plannotator:*)
 disable-model-invocation: true
 ---
diff --git a/apps/skills/core/plannotator-annotate/SKILL.md b/apps/skills/core/plannotator-annotate/SKILL.md
index bab38c43..c08e958e 100644
--- a/apps/skills/core/plannotator-annotate/SKILL.md
+++ b/apps/skills/core/plannotator-annotate/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: plannotator-annotate
-description: Open Plannotator's annotation UI for a markdown file, converted HTML file, URL, or folder and then respond to the returned annotations.
+description: Open Plannotator's annotation UI for a markdown file, HTML file, URL, or folder and then respond to the returned annotations.
 disable-model-invocation: true
 ---
 
diff --git a/apps/skills/extra/plannotator-visual-explainer/SKILL.md b/apps/skills/extra/plannotator-visual-explainer/SKILL.md
index 7a887d05..a56eb6eb 100644
--- a/apps/skills/extra/plannotator-visual-explainer/SKILL.md
+++ b/apps/skills/extra/plannotator-visual-explainer/SKILL.md
@@ -26,12 +26,12 @@ Always deliver via Plannotator's annotation UI. Do NOT use `open` or `xdg-open`.
 
 **Plans/proposals** (user should approve/deny):
 ```bash
-plannotator annotate <file> --render-html --gate
+plannotator annotate <file> --gate
 ```
 
 **Everything else** (informational):
 ```bash
-plannotator annotate <file> --render-html
+plannotator annotate <file>
 ```
 
 ---
diff --git a/apps/skills/extra/plannotator-visual-explainer/references/theme-override.md b/apps/skills/extra/plannotator-visual-explainer/references/theme-override.md
index 2d1f2c2f..72118065 100644
--- a/apps/skills/extra/plannotator-visual-explainer/references/theme-override.md
+++ b/apps/skills/extra/plannotator-visual-explainer/references/theme-override.md
@@ -4,7 +4,7 @@ When visual-explainer's workflow says to pick a palette and font pairing, use th
 
 ## CSS Custom Properties
 
-Replace visual-explainer's `--bg`, `--surface`, `--border`, `--text`, `--accent` variables with Plannotator's semantic tokens. Include these as `:root` defaults so the file works standalone. When embedded in the Plannotator UI via `--render-html`, these get overridden by the active theme.
+Replace visual-explainer's `--bg`, `--surface`, `--border`, `--text`, `--accent` variables with Plannotator's semantic tokens. Include these as `:root` defaults so the file works standalone. When embedded in Plannotator's raw HTML annotation mode, these get overridden by the active theme.
 
 ```css
 :root {
@@ -91,7 +91,7 @@ mermaid.initialize({
 
 ## Dark mode
 
-Plannotator handles dark/light via theme classes, not `prefers-color-scheme`. The standalone defaults above are the light theme. When embedded via `--render-html`, the active theme's tokens override automatically — no media query needed in the generated HTML.
+Plannotator handles dark/light via theme classes, not `prefers-color-scheme`. The standalone defaults above are the light theme. When embedded in raw HTML annotation mode, the active theme's tokens override automatically — no media query needed in the generated HTML.
 
 For standalone viewing, you may optionally add a `prefers-color-scheme: dark` block with the Plannotator dark theme values:
 
diff --git a/bun.lock b/bun.lock
index 329193db..ef167bcd 100644
--- a/bun.lock
+++ b/bun.lock
@@ -64,7 +64,7 @@
     },
     "apps/opencode-plugin": {
       "name": "@plannotator/opencode",
-      "version": "0.20.1",
+      "version": "0.20.3",
       "dependencies": {
         "@opencode-ai/plugin": "^1.1.10",
       },
@@ -86,10 +86,11 @@
     },
     "apps/pi-extension": {
       "name": "@plannotator/pi-extension",
-      "version": "0.20.1",
+      "version": "0.20.3",
       "dependencies": {
         "@joplin/turndown-plugin-gfm": "^1.0.64",
         "@pierre/diffs": "1.2.8",
+        "parse5": "^7.3.0",
         "turndown": "^7.2.4",
       },
       "devDependencies": {
@@ -209,7 +210,7 @@
     },
     "packages/server": {
       "name": "@plannotator/server",
-      "version": "0.20.1",
+      "version": "0.20.3",
       "dependencies": {
         "@pierre/diffs": "1.2.8",
         "@plannotator/ai": "workspace:*",
@@ -227,6 +228,7 @@
       "version": "0.0.1",
       "dependencies": {
         "@joplin/turndown-plugin-gfm": "^1.0.64",
+        "parse5": "^7.3.0",
         "turndown": "^7.2.4",
       },
     },
@@ -1567,7 +1569,7 @@
 
     "enhanced-resolve": ["enhanced-resolve@5.18.4", "", { "dependencies": { "graceful-fs": "^4.2.4", "tapable": "^2.2.0" } }, "sha512-LgQMM4WXU3QI+SYgEc2liRgznaD5ojbmY3sb8LxyguVkIg5FxdpTkvk72te2R38/TGKxH634oLxXRGY6d7AP+Q=="],
 
-    "entities": ["entities@4.5.0", "", {}, "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw=="],
+    "entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="],
 
     "environment": ["environment@1.1.0", "", {}, "sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q=="],
 
@@ -2197,7 +2199,7 @@
 
     "parse-semver": ["parse-semver@1.1.1", "", { "dependencies": { "semver": "^5.1.0" } }, "sha512-Eg1OuNntBMH0ojvEKSrvDSnwLmvVuUOSdylH/pSCPNMIspLlweJyIWXCE+k/5hm3cj/EBUYwmWkjhBALNP4LXQ=="],
 
-    "parse5": ["parse5@5.1.1", "", {}, "sha512-ugq4DFI0Ptb+WWjAdOK16+u/nHfiIrcE+sh8kZMaM0WllQKLI9rOUq6c2b7cwPkXdzfQESqvoqK6ug7U/Yyzug=="],
+    "parse5": ["parse5@7.3.0", "", { "dependencies": { "entities": "^6.0.0" } }, "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw=="],
 
     "parse5-htmlparser2-tree-adapter": ["parse5-htmlparser2-tree-adapter@6.0.1", "", { "dependencies": { "parse5": "^6.0.1" } }, "sha512-qPuWvbLgvDGilKc5BoicRovlT4MtYT6JfJyBOMDsKoiT+GiuP5qyrPCnR9HcPECIJJmZh5jRndyNThnhhb/vlA=="],
 
@@ -2831,8 +2833,6 @@
 
     "bun-types/@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
 
-    "cheerio/parse5": ["parse5@7.3.0", "", { "dependencies": { "entities": "^6.0.0" } }, "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw=="],
-
     "cheerio/parse5-htmlparser2-tree-adapter": ["parse5-htmlparser2-tree-adapter@7.1.0", "", { "dependencies": { "domhandler": "^5.0.3", "parse5": "^7.0.0" } }, "sha512-ruw5xyKs6lrpo9x9rCZqZZnIUntICjQAd0Wsmp396Ul9lN/h+ifgVV1x1gZHi8euej6wTfpqX8j+BFQxF0NS/g=="],
 
     "chevrotain/lodash-es": ["lodash-es@4.17.21", "", {}, "sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw=="],
@@ -2841,6 +2841,8 @@
 
     "cli-highlight/highlight.js": ["highlight.js@10.7.3", "", {}, "sha512-tzcUFauisWKNHaRkN4Wjl/ZA07gENAjFl3J/c480dprkGTg5EQstgaNFqBfUqCq54kZRIEcreTsAgF/m2quD7A=="],
 
+    "cli-highlight/parse5": ["parse5@5.1.1", "", {}, "sha512-ugq4DFI0Ptb+WWjAdOK16+u/nHfiIrcE+sh8kZMaM0WllQKLI9rOUq6c2b7cwPkXdzfQESqvoqK6ug7U/Yyzug=="],
+
     "cliui/string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
 
     "cliui/strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
@@ -2859,6 +2861,8 @@
 
     "d3-sankey/d3-shape": ["d3-shape@1.3.7", "", { "dependencies": { "d3-path": "1" } }, "sha512-EUkvKjqPFUAZyOlhY5gzCxCeI0Aep04LwIRpsZ/mLFelJiUfnK56jo5JMDSE7yyP2kLSb6LtF+S5chMk7uqPqw=="],
 
+    "dom-serializer/entities": ["entities@4.5.0", "", {}, "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw=="],
+
     "encoding-sniffer/iconv-lite": ["iconv-lite@0.6.3", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw=="],
 
     "escodegen/source-map": ["source-map@0.6.1", "", {}, "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g=="],
@@ -2875,10 +2879,6 @@
 
     "glob/minimatch": ["minimatch@10.2.2", "", { "dependencies": { "brace-expansion": "^5.0.2" } }, "sha512-+G4CpNBxa5MprY+04MbgOw1v7So6n5JY166pFi9KfYwT78fxScCeSNQSNzp6dpPSW2rONOps6Ocam1wFhCgoVw=="],
 
-    "hast-util-from-html/parse5": ["parse5@7.3.0", "", { "dependencies": { "entities": "^6.0.0" } }, "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw=="],
-
-    "hast-util-raw/parse5": ["parse5@7.3.0", "", { "dependencies": { "entities": "^6.0.0" } }, "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw=="],
-
     "htmlparser2/entities": ["entities@7.0.1", "", {}, "sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA=="],
 
     "katex/commander": ["commander@8.3.0", "", {}, "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww=="],
@@ -2887,6 +2887,8 @@
 
     "magicast/@babel/types": ["@babel/types@7.29.0", "", { "dependencies": { "@babel/helper-string-parser": "^7.27.1", "@babel/helper-validator-identifier": "^7.28.5" } }, "sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A=="],
 
+    "markdown-it/entities": ["entities@4.5.0", "", {}, "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw=="],
+
     "mdast-util-find-and-replace/escape-string-regexp": ["escape-string-regexp@5.0.0", "", {}, "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw=="],
 
     "mermaid/dompurify": ["dompurify@3.3.1", "", { "optionalDependencies": { "@types/trusted-types": "^2.0.7" } }, "sha512-qkdCKzLNtrgPFP1Vo+98FRzJnBRGe4ffyCea9IwHB1fyxPOeNTHpLKYGd4Uk9xvNoH0ZoOjwZxNptyMwqrId1Q=="],
@@ -2915,8 +2917,6 @@
 
     "parse5-htmlparser2-tree-adapter/parse5": ["parse5@6.0.1", "", {}, "sha512-Ofn/CTFzRGTTxwpNEs9PP93gXShHcTq255nzRYSKe8AkVpZY7e1fpmTfOyoIvjP5HG7Z2ZM7VS9PPhQGW2pOpw=="],
 
-    "parse5-parser-stream/parse5": ["parse5@7.3.0", "", { "dependencies": { "entities": "^6.0.0" } }, "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw=="],
-
     "protobufjs/@types/node": ["@types/node@22.19.3", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-1N9SBnWYOJTrNZCdh/yJE+t910Y128BoyY+zBLWhL3r0TYzlTmFdXrPwHL9DyFZmlEXNQQolTZh3KHV31QDhyA=="],
 
     "proxy-agent/lru-cache": ["lru-cache@7.18.3", "", {}, "sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA=="],
@@ -3063,8 +3063,6 @@
 
     "astro/esbuild/@esbuild/win32-x64": ["@esbuild/win32-x64@0.27.3", "", { "os": "win32", "cpu": "x64" }, "sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA=="],
 
-    "cheerio/parse5/entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="],
-
     "cliui/string-width/emoji-regex": ["emoji-regex@8.0.0", "", {}, "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A=="],
 
     "cliui/strip-ansi/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
@@ -3081,14 +3079,8 @@
 
     "glob/minimatch/brace-expansion": ["brace-expansion@5.0.3", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-fy6KJm2RawA5RcHkLa1z/ScpBeA762UF9KmZQxwIbDtRJrgLzM10depAiEQ+CXYcoiqW1/m96OAAoke2nE9EeA=="],
 
-    "hast-util-from-html/parse5/entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="],
-
-    "hast-util-raw/parse5/entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="],
-
     "normalize-package-data/hosted-git-info/lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="],
 
-    "parse5-parser-stream/parse5/entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="],
-
     "protobufjs/@types/node/undici-types": ["undici-types@6.21.0", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
 
     "rimraf/glob/jackspeak": ["jackspeak@3.4.3", "", { "dependencies": { "@isaacs/cliui": "^8.0.2" }, "optionalDependencies": { "@pkgjs/parseargs": "^0.11.0" } }, "sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw=="],
diff --git a/packages/editor/App.tsx b/packages/editor/App.tsx
index 5175f338..1b5256c6 100644
--- a/packages/editor/App.tsx
+++ b/packages/editor/App.tsx
@@ -142,6 +142,9 @@ const createEmptyMessageState = (message: PickerMessage): MessageAnnotationState
   linkedDocSession: {
     root: {
       markdown: message.text,
+      renderAs: 'markdown',
+      rawHtml: '',
+      shareHtml: '',
       annotations: [],
       selectedAnnotationId: null,
       globalAttachments: [],
@@ -166,6 +169,9 @@ const normalizeMessageState = (
       // Keep it as the source of truth so transient UI state cannot cache an
       // empty markdown value for a message.
       markdown: message.text,
+      renderAs: state.linkedDocSession.root.renderAs ?? 'markdown',
+      rawHtml: state.linkedDocSession.root.rawHtml ?? '',
+      shareHtml: state.linkedDocSession.root.shareHtml ?? '',
     },
     docs: new Map(state.linkedDocSession.docs),
   },
@@ -266,6 +272,7 @@ const App: React.FC = () => {
   // card-chromed markdown column. Branch the document-area containers on this.
   const isHtmlSurface = renderAs === 'html';
   const [rawHtml, setRawHtml] = useState('');
+  const [shareHtml, setShareHtml] = useState('');
   // Session-level force-markdown preference (`--markdown`). When set, folder/linked HTML
   // files are converted instead of rendered raw — threaded into /api/doc as &convert=1.
   const [convertHtml, setConvertHtml] = useState(false);
@@ -288,6 +295,7 @@ const App: React.FC = () => {
   const [projectRoot, setProjectRoot] = useState<string | null>(null);
   const [wideModeType, setWideModeType] = useState<WideModeType | null>(null);
   const wideModeSnapshotRef = useRef<WideModeLayoutSnapshot | null>(null);
+  const initialSidebarPreferenceAppliedRef = useRef(false);
   const lastAppliedTocEnabledRef = useRef(uiPrefs.tocEnabled);
   const goalSetupMode = goalSetupBundle !== null;
 
@@ -330,7 +338,7 @@ const App: React.FC = () => {
   usePrintMode();
 
   // Sidebar (shared TOC + Version Browser)
-  const sidebar = useSidebar(getUIPreferences().tocEnabled);
+  const sidebar = useSidebar(false);
 
   // Resizable panels
   const panelResize = useResizablePanel({
@@ -498,7 +506,7 @@ const App: React.FC = () => {
   const linkedDocHook = useLinkedDoc({
     markdown, annotations, selectedAnnotationId, globalAttachments,
     setMarkdown, setAnnotations, setSelectedAnnotationId, setGlobalAttachments,
-    renderAs, rawHtml, setRenderAs, setRawHtml,
+    renderAs, rawHtml, shareHtml, setRenderAs, setRawHtml, setShareHtml,
     viewerRef, sidebar: linkedDocSidebar, sourceFilePath, sourceConverted,
   });
 
@@ -900,6 +908,24 @@ const App: React.FC = () => {
   // Hide share entry points once they exist so we do not silently drop feedback.
   const canShareCurrentSession = sharingEnabled && codeAnnotations.length === 0;
 
+  const resolveRawHtmlForShare = useCallback(async (): Promise<string | null> => {
+    if (renderAs !== 'html' || !rawHtml) return null;
+    if (shareHtml) return shareHtml;
+    if (!isApiMode) return rawHtml;
+
+    const params = new URLSearchParams();
+    const activePath = linkedDocHook.filepath ?? sourceFilePath;
+    if (activePath) params.set('path', activePath);
+    const query = params.toString();
+    const res = await fetch(`/api/share-html${query ? `?${query}` : ''}`);
+    const data = (await res.json().catch(() => ({}))) as { shareHtml?: unknown; error?: string };
+    if (!res.ok || data.error || typeof data.shareHtml !== 'string') {
+      throw new Error(data.error || 'Failed to prepare HTML for sharing');
+    }
+    setShareHtml(data.shareHtml);
+    return data.shareHtml;
+  }, [isApiMode, linkedDocHook.filepath, rawHtml, renderAs, shareHtml, sourceFilePath]);
+
   // URL-based sharing
   const {
     isSharedSession,
@@ -929,11 +955,48 @@ const App: React.FC = () => {
     },
     shareBaseUrl,
     pasteApiUrl,
-    rawHtml,
+    renderAs === 'html' ? rawHtml : undefined,
+    resolveRawHtmlForShare,
     setRawHtml,
+    setShareHtml,
     setRenderAs,
   );
 
+  useEffect(() => {
+    if (initialSidebarPreferenceAppliedRef.current) return;
+    if (isLoading || isLoadingShared) return;
+    if (wideModeType !== null) return;
+
+    initialSidebarPreferenceAppliedRef.current = true;
+    if (archive.archiveMode || goalSetupMode || annotateSource === 'folder') return;
+    if (renderAs === 'html') {
+      sidebar.close();
+      return;
+    }
+    if (uiPrefs.tocEnabled && hasTocEntries) {
+      sidebar.open('toc');
+    }
+  }, [
+    annotateSource,
+    archive.archiveMode,
+    goalSetupMode,
+    hasTocEntries,
+    isLoading,
+    isLoadingShared,
+    renderAs,
+    sidebar.close,
+    sidebar.open,
+    uiPrefs.tocEnabled,
+    wideModeType,
+  ]);
+
+  const ensureShareLink = useCallback(async (): Promise<string | null> => {
+    const existing = shortShareUrl || shareUrl;
+    if (existing) return existing;
+    if (!canShareCurrentSession) return null;
+    return await generateShortUrl();
+  }, [canShareCurrentSession, generateShortUrl, shareUrl, shortShareUrl]);
+
   // useLayoutEffect + synchronous getBoundingClientRect so the initial
   // bucket is set before the browser paints. Otherwise narrow viewports
   // get a one-frame flash of "Global comment"/"Copy plan" labels before
@@ -1026,7 +1089,7 @@ const App: React.FC = () => {
         if (!res.ok) throw new Error('Not in API mode');
         return res.json();
       })
-      .then((data: { plan: string; origin?: Origin; mode?: 'annotate' | 'annotate-last' | 'annotate-folder' | 'archive' | 'goal-setup'; goalSetup?: GoalSetupBundle; filePath?: string; sourceInfo?: string; sourceConverted?: boolean; gate?: boolean; renderAs?: 'html' | 'markdown'; rawHtml?: string; convertHtml?: boolean; sharingEnabled?: boolean; shareBaseUrl?: string; pasteApiUrl?: string; repoInfo?: { display: string; branch?: string; host?: string }; previousPlan?: string | null; versionInfo?: { version: number; totalVersions: number; project: string }; archivePlans?: ArchivedPlan[]; projectRoot?: string; isWSL?: boolean; serverConfig?: { displayName?: string; gitUser?: string }; recentMessages?: PickerMessage[] }) => {
+      .then((data: { plan: string; origin?: Origin; mode?: 'annotate' | 'annotate-last' | 'annotate-folder' | 'archive' | 'goal-setup'; goalSetup?: GoalSetupBundle; filePath?: string; sourceInfo?: string; sourceConverted?: boolean; gate?: boolean; renderAs?: 'html' | 'markdown'; rawHtml?: string; shareHtml?: string; convertHtml?: boolean; sharingEnabled?: boolean; shareBaseUrl?: string; pasteApiUrl?: string; repoInfo?: { display: string; branch?: string; host?: string }; previousPlan?: string | null; versionInfo?: { version: number; totalVersions: number; project: string }; archivePlans?: ArchivedPlan[]; projectRoot?: string; isWSL?: boolean; serverConfig?: { displayName?: string; gitUser?: string }; recentMessages?: PickerMessage[] }) => {
         // Initialize config store with server-provided values (config file > cookie > default)
         configStore.init(data.serverConfig);
         // Session-level force-markdown preference (--markdown); threaded into folder/linked
@@ -1049,6 +1112,7 @@ const App: React.FC = () => {
         } else if (data.renderAs === 'html' && data.rawHtml) {
           setRenderAs('html');
           setRawHtml(data.rawHtml);
+          setShareHtml(data.shareHtml ?? '');
           setMarkdown('');
         } else if (data.mode === 'annotate-folder') {
           // Folder annotation mode: clear demo content, let user pick a file
@@ -1910,10 +1974,15 @@ const App: React.FC = () => {
   const callbackConfig = React.useMemo(() => getCallbackConfig(), []);
 
   const callCallback = React.useCallback(async (action: CallbackAction) => {
-    if (!callbackConfig || isSubmitting || (!shareUrl && !shortShareUrl)) return;
+    if (!callbackConfig || isSubmitting) return;
     setIsSubmitting(true);
     try {
-      const result = await executeCallback(action, callbackConfig, shortShareUrl || shareUrl);
+      const callbackShareUrl = await ensureShareLink();
+      if (!callbackShareUrl) {
+        toast.error('Failed to create share link');
+        return;
+      }
+      const result = await executeCallback(action, callbackConfig, callbackShareUrl);
       if (result) {
         if (result.type === 'success') {
           toast.success(result.message);
@@ -1925,7 +1994,7 @@ const App: React.FC = () => {
     } finally {
       setIsSubmitting(false);
     }
-  }, [callbackConfig, isSubmitting, shareUrl, shortShareUrl]);
+  }, [callbackConfig, ensureShareLink, isSubmitting]);
 
   const handleCallbackApprove = React.useCallback(() => callCallback(CallbackAction.Approve), [callCallback]);
   const handleCallbackFeedback = React.useCallback(() => callCallback(CallbackAction.Feedback), [callCallback]);
@@ -2010,8 +2079,13 @@ const App: React.FC = () => {
   };
 
   const handleCopyShareLink = async () => {
-    const url = shortShareUrl || shareUrl;
-    if (!url) return;
+    const url = await ensureShareLink();
+    if (!url) {
+      setInitialExportTab('share');
+      setShowExport(true);
+      toast.error('Failed to create share link');
+      return;
+    }
     try {
       await navigator.clipboard.writeText(url);
       toast.success('Share link copied');
@@ -2241,7 +2315,7 @@ const App: React.FC = () => {
           aiHasMessages={aiMessages.length > 0}
           hasAnyAnnotations={hasAnyAnnotations}
           linkedDocIsActive={linkedDocHook.isActive}
-          callbackShareUrlReady={callbackConfig ? Boolean(shareUrl || shortShareUrl) : true}
+          callbackShareUrlReady={callbackConfig ? Boolean(shareUrl || shortShareUrl || (renderAs === 'html' && (shareHtml || rawHtml))) : true}
           canShareCurrentSession={canShareCurrentSession}
           agentName={agentName}
           availableAgents={availableAgents}
@@ -2619,7 +2693,7 @@ const App: React.FC = () => {
               const output = messageMultiSelectMode ? buildFullAnnotationsOutput() : annotationsOutput;
               await navigator.clipboard.writeText(wrapFeedbackForAgent(output));
             }}
-            onShare={canShareCurrentSession && (shareUrl || shortShareUrl) ? () => { setIsPanelOpen(false); setInitialExportTab('share'); setShowExport(true); } : undefined}
+            onShare={canShareCurrentSession ? () => { setIsPanelOpen(false); setInitialExportTab('share'); setShowExport(true); } : undefined}
             otherFileAnnotations={otherFileAnnotations}
             onOtherFileAnnotationsClick={handleFlashAnnotatedFiles}
           />
diff --git a/packages/server/annotate-doc-url.test.ts b/packages/server/annotate-doc-url.test.ts
new file mode 100644
index 00000000..a81966fc
--- /dev/null
+++ b/packages/server/annotate-doc-url.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { applyAnnotateDocSessionParams } from "./annotate-doc-url";
+
+describe("applyAnnotateDocSessionParams", () => {
+  test("adds source base and markdown conversion for local HTML annotate sessions", () => {
+    const result = applyAnnotateDocSessionParams(
+      "http://localhost/api/doc?path=linked.html",
+      "/tmp/docs/page.html",
+      true,
+    );
+
+    const url = new URL(result.url);
+    expect(result.changed).toBe(true);
+    expect(url.searchParams.get("base")).toBe("/tmp/docs");
+    expect(url.searchParams.get("convert")).toBe("1");
+  });
+
+  test("does not override explicit doc request params", () => {
+    const result = applyAnnotateDocSessionParams(
+      "http://localhost/api/doc?path=linked.html&base=/custom&convert=0",
+      "/tmp/docs/page.html",
+      true,
+    );
+
+    const url = new URL(result.url);
+    expect(result.changed).toBe(false);
+    expect(url.searchParams.get("base")).toBe("/custom");
+    expect(url.searchParams.get("convert")).toBe("0");
+  });
+
+  test("skips local base injection for URL annotations", () => {
+    const result = applyAnnotateDocSessionParams(
+      "http://localhost/api/doc?path=linked.html",
+      "https://example.test/page.html",
+      true,
+    );
+
+    const url = new URL(result.url);
+    expect(result.changed).toBe(true);
+    expect(url.searchParams.has("base")).toBe(false);
+    expect(url.searchParams.get("convert")).toBe("1");
+  });
+});
diff --git a/packages/server/annotate-doc-url.ts b/packages/server/annotate-doc-url.ts
new file mode 100644
index 00000000..5d44d112
--- /dev/null
+++ b/packages/server/annotate-doc-url.ts
@@ -0,0 +1,22 @@
+import { dirname } from "path";
+
+export function applyAnnotateDocSessionParams(
+  requestUrl: string,
+  sourceFilePath: string,
+  convertHtml: boolean,
+): { url: string; changed: boolean } {
+  const docUrl = new URL(requestUrl);
+  let changed = false;
+
+  if (!docUrl.searchParams.has("base") && !/^https?:\/\//i.test(sourceFilePath)) {
+    docUrl.searchParams.set("base", dirname(sourceFilePath));
+    changed = true;
+  }
+
+  if (convertHtml && !docUrl.searchParams.has("convert")) {
+    docUrl.searchParams.set("convert", "1");
+    changed = true;
+  }
+
+  return { url: docUrl.toString(), changed };
+}
diff --git a/packages/server/annotate-html-assets.test.ts b/packages/server/annotate-html-assets.test.ts
new file mode 100644
index 00000000..5d49551f
--- /dev/null
+++ b/packages/server/annotate-html-assets.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createHtmlAssetRegistry, inlineHtmlLocalAssets } from "./html-assets";
+
+describe("annotate raw HTML assets", () => {
+  test("rewrites raw HTML support assets and serves them from the source directory", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "plannotator-html-assets-"));
+    const htmlPath = join(dir, "page.html");
+    const cssPath = join(dir, "style.css");
+    const imagePath = join(dir, "logo.png");
+    const html = '<!doctype html><html><head><link rel="stylesheet" href="./style.css"></head><body><img src="./logo.png"></body></html>';
+    writeFileSync(htmlPath, html, "utf-8");
+    writeFileSync(cssPath, "body { color: red; }", "utf-8");
+    writeFileSync(imagePath, "png-bytes", "utf-8");
+
+    const assets = createHtmlAssetRegistry();
+    const rawHtml = assets.rewriteHtml(html, htmlPath);
+
+    expect(rawHtml).toContain("/api/html-assets/");
+
+    const cssUrl = rawHtml.match(/href="([^"]+style\.css)"/)?.[1];
+    const imageUrl = rawHtml.match(/src="([^"]+logo\.png)"/)?.[1];
+    expect(cssUrl).toBeTruthy();
+    expect(imageUrl).toBeTruthy();
+
+    const cssRequestUrl = new URL(cssUrl!, "http://localhost");
+    const cssResponse = await assets.handle(new Request(String(cssRequestUrl)), cssRequestUrl);
+    expect(cssResponse?.status).toBe(200);
+    expect(cssResponse?.headers.get("content-type")).toContain("text/css");
+    expect(cssResponse?.headers.get("access-control-allow-origin")).toBe("*");
+    expect(await cssResponse?.text()).toBe("body { color: red; }");
+
+    const imageRequestUrl = new URL(imageUrl!, "http://localhost");
+    const imageResponse = await assets.handle(new Request(String(imageRequestUrl)), imageRequestUrl);
+    expect(imageResponse?.status).toBe(200);
+    expect(imageResponse?.headers.get("content-type")).toBe("image/png");
+    expect(await imageResponse?.text()).toBe("png-bytes");
+  });
+
+  test("inlines raw HTML support assets for portable share payloads", () => {
+    const dir = mkdtempSync(join(tmpdir(), "plannotator-html-share-"));
+    const htmlPath = join(dir, "page.html");
+    const cssDir = join(dir, "styles");
+    const imageDir = join(dir, "images");
+    mkdirSync(cssDir);
+    mkdirSync(imageDir);
+    writeFileSync(join(imageDir, "bg.png"), Buffer.from([1, 2, 3]));
+    writeFileSync(join(cssDir, "style.css"), 'body { background: url("../images/bg.png"); }', "utf-8");
+    const html = '<!doctype html><html><head><link rel="stylesheet" href="./styles/style.css?v=1"></head><body><img src="./images/bg.png?cache=1"></body></html>';
+    writeFileSync(htmlPath, html, "utf-8");
+
+    const shareHtml = inlineHtmlLocalAssets(html, htmlPath);
+
+    expect(shareHtml).not.toContain("/api/html-assets/");
+    expect(shareHtml).toContain('href="data:text/css;charset=utf-8;base64,');
+    expect(shareHtml).toContain('src="data:image/png;base64,AQID"');
+    expect(shareHtml).not.toContain("base64,AQID?cache=1");
+
+    const cssBase64 = shareHtml.match(/href="data:text\/css;charset=utf-8;base64,([^"]+)"/)?.[1];
+    expect(cssBase64).toBeTruthy();
+    const css = Buffer.from(cssBase64!, "base64").toString("utf-8");
+    expect(css).toContain('url("data:image/png;base64,AQID")');
+  });
+});
diff --git a/packages/server/annotate.ts b/packages/server/annotate.ts
index 5cd36116..ad45c7b2 100644
--- a/packages/server/annotate.ts
+++ b/packages/server/annotate.ts
@@ -1,10 +1,10 @@
 /**
  * Annotate Server
  *
- * Provides a server for annotating arbitrary markdown files.
+ * Provides a server for annotating arbitrary files, URLs, and folders.
  * Follows the same patterns as the review server but serves
- * markdown content via /api/plan so the plan editor UI can
- * render it without modifications.
+ * annotation-session content via /api/plan so the plan editor UI can
+ * render it without separate app bundles.
  *
  * Environment variables:
  *   PLANNOTATOR_REMOTE - Set to "1"/"true" for remote, "0"/"false" for local
@@ -20,10 +20,12 @@ import { warmFileListCache } from "@plannotator/shared/resolve-file";
 import { contentHash, deleteDraft } from "./draft";
 import { createExternalAnnotationHandler } from "./external-annotations";
 import { saveConfig, detectGitUser, getServerConfig } from "./config";
-import { dirname, resolve as resolvePath } from "path";
+import { dirname, isAbsolute, relative, resolve as resolvePath } from "path";
 import { isWSL } from "./browser";
 import { AI_QUERY_ENDPOINT, createAIRuntime } from "./ai-runtime";
 import type { AIEndpoints } from "@plannotator/ai";
+import { createHtmlAssetRegistry } from "./html-assets";
+import { applyAnnotateDocSessionParams } from "./annotate-doc-url";
 
 // Re-export utilities
 export { isRemoteSession, getServerPort } from "./remote";
@@ -33,7 +35,7 @@ export { handleServerReady as handleAnnotateServerReady } from "./shared-handler
 // --- Types ---
 
 export interface AnnotateServerOptions {
-  /** Markdown content of the file to annotate */
+  /** Markdown content of the file to annotate. Empty when rendering raw HTML. */
   markdown: string;
   /** Original file path (for display purposes) */
   filePath: string;
@@ -65,9 +67,9 @@ export interface AnnotateServerOptions {
   sourceConverted?: boolean;
   /** Enable review-gate UX: adds an Approve button alongside Close/Send Annotations */
   gate?: boolean;
-  /** Raw HTML content for direct iframe rendering (--render-html mode) */
+  /** Raw HTML content for direct iframe rendering. */
   rawHtml?: string;
-  /** Render HTML as-is in an iframe instead of converting to markdown */
+  /** Render HTML as-is in an iframe. */
   renderHtml?: boolean;
   /** Session-level force-markdown preference (`--markdown`). Exposed in /api/plan so the
    *  frontend appends `&convert=1` when navigating folder/linked HTML files. */
@@ -146,6 +148,41 @@ export async function startAnnotateServer(
   const draftKey = contentHash(draftSource);
   const externalAnnotations = createExternalAnnotationHandler("plan");
   const aiRuntime = await createAIRuntime();
+  const htmlAssets = createHtmlAssetRegistry();
+
+  async function loadShareHtml(pathParam: string | null): Promise<Response> {
+    if (/^https?:\/\//i.test(filePath)) {
+      return Response.json({ error: "Raw HTML sharing is unavailable for URL annotations" }, { status: 400 });
+    }
+
+    const sourcePath = resolvePath(filePath);
+    const requestedPath = pathParam ? resolvePath(pathParam) : sourcePath;
+    if (!/\.html?$/i.test(requestedPath)) {
+      return Response.json({ error: "Share HTML is only available for HTML documents" }, { status: 400 });
+    }
+    if (!isAllowedHtmlSharePath(requestedPath)) {
+      return Response.json({ error: "Access denied" }, { status: 403 });
+    }
+
+    try {
+      const html = renderHtml && rawHtml && requestedPath === sourcePath
+        ? rawHtml
+        : await Bun.file(requestedPath).text();
+      return Response.json({ shareHtml: htmlAssets.inlineHtml(html, requestedPath) });
+    } catch {
+      return Response.json({ error: "Failed to prepare share HTML" }, { status: 500 });
+    }
+  }
+
+  function isAllowedHtmlSharePath(targetPath: string): boolean {
+    const roots = new Set<string>([process.cwd()]);
+    if (folderPath) roots.add(folderPath);
+    if (!/^https?:\/\//i.test(filePath)) roots.add(dirname(filePath));
+    for (const root of roots) {
+      if (isWithinDirectory(targetPath, root)) return true;
+    }
+    return false;
+  }
 
   // Detect repo info (cached for this session)
   const repoInfo = await getRepoInfo();
@@ -187,6 +224,7 @@ export async function startAnnotateServer(
 
           // API: Get plan content (reuse /api/plan so the plan editor UI works)
           if (url.pathname === "/api/plan" && req.method === "GET") {
+            const displayRawHtml = renderHtml && rawHtml ? htmlAssets.rewriteHtml(rawHtml, filePath) : undefined;
             return Response.json({
               plan: markdown,
               origin,
@@ -195,8 +233,8 @@ export async function startAnnotateServer(
               sourceInfo,
               sourceConverted: sourceConverted ?? false,
               gate,
-              renderAs: renderHtml && rawHtml ? 'html' as const : 'markdown' as const,
-              ...(renderHtml && rawHtml ? { rawHtml } : {}),
+              renderAs: displayRawHtml ? 'html' as const : 'markdown' as const,
+              ...(displayRawHtml ? { rawHtml: displayRawHtml } : {}),
               convertHtml,
               sharingEnabled,
               shareBaseUrl,
@@ -209,6 +247,10 @@ export async function startAnnotateServer(
             });
           }
 
+          if (url.pathname === "/api/share-html" && req.method === "GET") {
+            return loadShareHtml(url.searchParams.get("path"));
+          }
+
           // API: Update user config (write-back to ~/.plannotator/config.json)
           if (url.pathname === "/api/config" && req.method === "POST") {
             try {
@@ -230,16 +272,19 @@ export async function startAnnotateServer(
             return handleImage(req);
           }
 
-          // API: Serve a linked markdown document
-          // Inject source file's directory as base for relative path resolution.
-          // Skip base injection for URL annotations — there's no local directory to resolve against.
+          const htmlAssetResponse = await htmlAssets.handle(req, url);
+          if (htmlAssetResponse) {
+            return htmlAssetResponse;
+          }
+
+          // API: Serve a linked markdown document. The annotate session owns the
+          // source-file base and --markdown preference, so enforce both here.
           if (url.pathname === "/api/doc" && req.method === "GET") {
-            if (!url.searchParams.has("base") && !/^https?:\/\//i.test(filePath)) {
-              const docUrl = new URL(req.url);
-              docUrl.searchParams.set("base", dirname(filePath));
-              return handleDoc(new Request(docUrl.toString()));
-            }
-            return handleDoc(req);
+            const docUrl = applyAnnotateDocSessionParams(req.url, filePath, convertHtml);
+            const docReq = docUrl.changed ? new Request(docUrl.url) : req;
+            return handleDoc(docReq, {
+              rewriteHtml: htmlAssets.rewriteHtml,
+            });
           }
 
           // API: Batch existence check for code-file paths the renderer detected
@@ -402,3 +447,10 @@ export async function startAnnotateServer(
     },
   };
 }
+
+function isWithinDirectory(filePath: string, root: string): boolean {
+  const resolved = resolvePath(filePath);
+  const resolvedRoot = resolvePath(root);
+  const rel = relative(resolvedRoot, resolved);
+  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
diff --git a/packages/server/html-assets.ts b/packages/server/html-assets.ts
new file mode 100644
index 00000000..c638723b
--- /dev/null
+++ b/packages/server/html-assets.ts
@@ -0,0 +1,106 @@
+import { dirname, isAbsolute, relative, resolve as resolvePath } from "path";
+import {
+  HTML_ASSET_ROUTE_PREFIX,
+  encodeHtmlAssetPath,
+  htmlAssetContentType,
+  normalizeHtmlAssetRoutePath,
+  rewriteHtmlAssetReferences,
+} from "@plannotator/shared/html-assets";
+import {
+  inlineHtmlLocalAssets,
+  MAX_HTML_ASSET_BYTES,
+} from "@plannotator/shared/html-assets-node";
+
+export { inlineHtmlLocalAssets };
+
+export function createHtmlAssetRegistry() {
+  const rootsByToken = new Map<string, string>();
+  const tokensByRoot = new Map<string, string>();
+
+  function register(baseDir: string): string {
+    const root = resolvePath(baseDir);
+    const existing = tokensByRoot.get(root);
+    if (existing) return existing;
+    const token = crypto.randomUUID().replace(/-/g, "").slice(0, 16);
+    tokensByRoot.set(root, token);
+    rootsByToken.set(token, root);
+    return token;
+  }
+
+  function rewriteHtml(html: string, htmlFilePath: string): string {
+    if (/^https?:\/\//i.test(htmlFilePath)) return html;
+    try {
+      const token = register(dirname(resolvePath(htmlFilePath)));
+      return rewriteHtmlAssetReferences(
+        html,
+        (assetPath) => `${HTML_ASSET_ROUTE_PREFIX}/${token}/${encodeHtmlAssetPath(assetPath)}`,
+      );
+    } catch {
+      return html;
+    }
+  }
+
+  function inlineHtml(html: string, htmlFilePath: string): string {
+    return inlineHtmlLocalAssets(html, htmlFilePath);
+  }
+
+  async function handle(_req: Request, url: URL): Promise<Response | null> {
+    const prefix = `${HTML_ASSET_ROUTE_PREFIX}/`;
+    if (!url.pathname.startsWith(prefix)) return null;
+
+    const rest = url.pathname.slice(prefix.length);
+    const slash = rest.indexOf("/");
+    if (slash <= 0) {
+      return Response.json({ error: "Missing asset token or path" }, { status: 404 });
+    }
+
+    const token = rest.slice(0, slash);
+    const root = rootsByToken.get(token);
+    if (!root) {
+      return Response.json({ error: "Unknown asset root" }, { status: 404 });
+    }
+
+    const assetPath = normalizeHtmlAssetRoutePath(rest.slice(slash + 1));
+    if (!assetPath) {
+      return Response.json({ error: "Invalid asset path" }, { status: 400 });
+    }
+
+    const contentType = htmlAssetContentType(assetPath);
+    if (!contentType) {
+      return Response.json({ error: "Unsupported asset type" }, { status: 415 });
+    }
+
+    const resolved = resolvePath(root, assetPath);
+    if (!isWithinDirectory(resolved, root)) {
+      return Response.json({ error: "Access denied" }, { status: 403 });
+    }
+
+    try {
+      const file = Bun.file(resolved);
+      if (!(await file.exists())) {
+        return Response.json({ error: "Asset not found" }, { status: 404 });
+      }
+      if (file.size > MAX_HTML_ASSET_BYTES) {
+        return Response.json({ error: "Asset too large" }, { status: 413 });
+      }
+      return new Response(file, {
+        headers: {
+          "Content-Type": contentType,
+          "Cache-Control": "no-store",
+          "Access-Control-Allow-Origin": "*",
+        },
+      });
+    } catch {
+      return Response.json({ error: "Failed to read asset" }, { status: 500 });
+    }
+  }
+
+  return { rewriteHtml, inlineHtml, handle };
+}
+
+function isWithinDirectory(filePath: string, root: string): boolean {
+  const resolved = resolvePath(filePath);
+  const resolvedRoot = resolvePath(root);
+  const rel = relative(resolvedRoot, resolved);
+  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
diff --git a/packages/server/package.json b/packages/server/package.json
index a356df2b..539a05eb 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -21,7 +21,8 @@
     "./share-url": "./share-url.ts",
     "./sessions": "./sessions.ts",
     "./project": "./project.ts",
-    "./pr": "./pr.ts"
+    "./pr": "./pr.ts",
+    "./html-assets": "./html-assets.ts"
   },
   "files": [
     "*.ts"
diff --git a/packages/server/reference-handlers.ts b/packages/server/reference-handlers.ts
index a4e3d482..e256d45a 100644
--- a/packages/server/reference-handlers.ts
+++ b/packages/server/reference-handlers.ts
@@ -24,8 +24,12 @@ import { preloadFile } from "@pierre/diffs/ssr";
 
 // --- Route handlers ---
 
+export interface HandleDocOptions {
+	rewriteHtml?: (html: string, filepath: string) => string;
+}
+
 /** Serve a linked markdown document. Resolves absolute, relative, or bare filename paths. */
-export async function handleDoc(req: Request): Promise<Response> {
+export async function handleDoc(req: Request, options: HandleDocOptions = {}): Promise<Response> {
 	const url = new URL(req.url);
 	const requestedPath = url.searchParams.get("path");
 	if (!requestedPath) {
@@ -59,7 +63,8 @@ export async function handleDoc(req: Request): Promise<Response> {
 				const raw = await file.text();
 				const isHtml = /\.html?$/i.test(requestedPath);
 				if (isHtml && !convert) {
-					return Response.json({ rawHtml: raw, renderAs: "html", filepath: fromBase });
+					const rawHtml = options.rewriteHtml ? options.rewriteHtml(raw, fromBase) : raw;
+					return Response.json({ rawHtml, renderAs: "html", filepath: fromBase });
 				}
 				const markdown = isHtml ? htmlToMarkdown(raw) : raw;
 				return Response.json({ markdown, filepath: fromBase, isConverted: isHtml, renderAs: "markdown" });
@@ -81,7 +86,8 @@ export async function handleDoc(req: Request): Promise<Response> {
 			if (await file.exists()) {
 				const html = await file.text();
 				if (!convert) {
-					return Response.json({ rawHtml: html, renderAs: "html", filepath: resolvedHtml });
+					const rawHtml = options.rewriteHtml ? options.rewriteHtml(html, resolvedHtml) : html;
+					return Response.json({ rawHtml, renderAs: "html", filepath: resolvedHtml });
 				}
 				const markdown = htmlToMarkdown(html);
 				return Response.json({ markdown, filepath: resolvedHtml, isConverted: true, renderAs: "markdown" });
diff --git a/packages/server/share-url.test.ts b/packages/server/share-url.test.ts
new file mode 100644
index 00000000..930f6b19
--- /dev/null
+++ b/packages/server/share-url.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, mock, test } from "bun:test";
+import { decompress } from "@plannotator/shared/compress";
+import { generateRemoteShareUrl, writeRemoteShareLink } from "./share-url";
+
+describe("generateRemoteShareUrl", () => {
+  test("keeps markdown remote shares hash-based", async () => {
+    const url = await generateRemoteShareUrl("# Plan", "https://share.example.test");
+    expect(url.startsWith("https://share.example.test/#")).toBe(true);
+
+    const payload = await decompress(url.split("#")[1]) as { p: string; a: unknown[] };
+    expect(payload).toEqual({ p: "# Plan", a: [] });
+  });
+
+  test("uses encrypted paste links for raw HTML remote shares", async () => {
+    const fetchImpl = mock(async (url: string | URL | Request, init?: RequestInit) => {
+      expect(String(url)).toBe("https://paste.example.test/api/paste");
+      expect(init?.method).toBe("POST");
+      expect(init?.headers).toEqual({ "Content-Type": "application/json" });
+      const body = JSON.parse(String(init?.body)) as { data?: unknown };
+      expect(typeof body.data).toBe("string");
+      return new Response(JSON.stringify({ id: "abc123" }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }) as typeof fetch;
+
+    const url = await generateRemoteShareUrl("", "https://share.example.test", {
+      rawHtml: "<!doctype html><h1>Hello</h1>",
+      pasteApiUrl: "https://paste.example.test",
+      fetchImpl,
+    });
+
+    expect(url).toMatch(/^https:\/\/share\.example\.test\/p\/abc123#key=[A-Za-z0-9_-]+&paste=/);
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+  });
+
+  test("warns instead of silently dropping raw HTML remote share failures", async () => {
+    const fetchImpl = mock(async () =>
+      new Response(JSON.stringify({ error: "Payload too large (max 5 MB encrypted)" }), {
+        status: 413,
+        headers: { "Content-Type": "application/json" },
+      })
+    ) as typeof fetch;
+    const originalWrite = process.stderr.write;
+    let stderr = "";
+    process.stderr.write = ((chunk: string | Uint8Array) => {
+      stderr += String(chunk);
+      return true;
+    }) as typeof process.stderr.write;
+
+    try {
+      await writeRemoteShareLink("", "https://share.example.test", "annotate", "HTML document only", {
+        rawHtml: "<!doctype html><h1>Hello</h1>",
+        pasteApiUrl: "https://paste.example.test",
+        fetchImpl,
+      });
+    } finally {
+      process.stderr.write = originalWrite;
+    }
+
+    expect(stderr).toContain("Warning: could not create remote share link for HTML document only.");
+    expect(stderr).toContain("Payload too large (max 5 MB encrypted)");
+    expect(stderr).toContain("HTML sharing uses the paste service");
+  });
+});
diff --git a/packages/server/share-url.ts b/packages/server/share-url.ts
index 9b7528fc..da67d633 100644
--- a/packages/server/share-url.ts
+++ b/packages/server/share-url.ts
@@ -6,8 +6,16 @@
  */
 
 import { compress } from "@plannotator/shared/compress";
+import { encrypt } from "@plannotator/shared/crypto";
 
 const DEFAULT_SHARE_BASE = "https://share.plannotator.ai";
+const DEFAULT_PASTE_API = "https://plannotator-paste.plannotator.workers.dev";
+
+export interface RemoteShareOptions {
+  rawHtml?: string;
+  pasteApiUrl?: string;
+  fetchImpl?: typeof fetch;
+}
 
 /**
  * Generate a share URL from plan markdown content.
@@ -17,13 +25,69 @@ const DEFAULT_SHARE_BASE = "https://share.plannotator.ai";
  */
 export async function generateRemoteShareUrl(
   plan: string,
-  shareBaseUrl?: string
+  shareBaseUrl?: string,
+  options: RemoteShareOptions = {},
 ): Promise<string> {
   const base = shareBaseUrl || DEFAULT_SHARE_BASE;
+  if (options.rawHtml) {
+    // Callers that start from a local file should pass self-contained HTML
+    // so sibling assets keep working after the payload leaves the machine.
+    return generateRemotePasteShareUrl(
+      { p: plan, a: [], h: options.rawHtml, r: "html" },
+      base,
+      options.pasteApiUrl,
+      options.fetchImpl,
+    );
+  }
   const hash = await compress({ p: plan, a: [] });
   return `${base}/#${hash}`;
 }
 
+async function generateRemotePasteShareUrl(
+  payload: unknown,
+  shareBaseUrl: string,
+  pasteApiUrl = DEFAULT_PASTE_API,
+  fetchImpl: typeof fetch = fetch,
+): Promise<string> {
+  const compressed = await compress(payload);
+  const { ciphertext, key } = await encrypt(compressed);
+
+  const response = await fetchImpl(`${pasteApiUrl}/api/paste`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ data: ciphertext }),
+    signal: AbortSignal.timeout(5_000),
+  });
+
+  if (!response.ok) {
+    throw new Error(await readPasteError(response, `Paste service returned ${response.status}`));
+  }
+
+  const result = (await response.json()) as { id?: unknown };
+  if (typeof result.id !== "string" || !result.id) {
+    throw new Error("Paste service response missing id");
+  }
+
+  const pasteParam =
+    pasteApiUrl !== DEFAULT_PASTE_API
+      ? `&paste=${base64UrlEncode(pasteApiUrl)}`
+      : "";
+  return `${shareBaseUrl}/p/${result.id}#key=${key}${pasteParam}`;
+}
+
+function base64UrlEncode(value: string): string {
+  return btoa(value).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+
+async function readPasteError(response: Response, fallback: string): Promise<string> {
+  try {
+    const body = (await response.json()) as { error?: unknown };
+    return typeof body.error === "string" && body.error.trim() ? body.error : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
 /**
  * Format byte size as human-readable string
  */
@@ -35,19 +99,32 @@ export function formatSize(bytes: number): string {
 
 /**
  * Generate a remote share URL and write it to stderr for the user.
- * Silently does nothing on failure.
+ * Keeps the local server running, but warns when the fallback share link
+ * cannot be created for remote sessions.
  */
 export async function writeRemoteShareLink(
   content: string,
   shareBaseUrl: string | undefined,
   verb: string,
-  noun: string
+  noun: string,
+  options: RemoteShareOptions = {},
 ): Promise<void> {
-  const shareUrl = await generateRemoteShareUrl(content, shareBaseUrl);
-  const size = formatSize(new TextEncoder().encode(shareUrl).length);
-  process.stderr.write(
-    `\n  Open this link on your local machine to ${verb}:\n` +
-    `  ${shareUrl}\n\n` +
-    `  (${size} — ${noun}, annotations added in browser)\n\n`
-  );
+  try {
+    const shareUrl = await generateRemoteShareUrl(content, shareBaseUrl, options);
+    const size = formatSize(new TextEncoder().encode(shareUrl).length);
+    process.stderr.write(
+      `\n  Open this link on your local machine to ${verb}:\n` +
+      `  ${shareUrl}\n\n` +
+      `  (${size} — ${noun}, annotations added in browser)\n\n`
+    );
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    const pasteHint = options.rawHtml
+      ? " HTML sharing uses the paste service; check PLANNOTATOR_PASTE_URL or try a smaller/self-contained HTML file."
+      : "";
+    process.stderr.write(
+      `\n  Warning: could not create remote share link for ${noun}.\n` +
+      `  ${reason}.${pasteHint}\n\n`
+    );
+  }
 }
diff --git a/packages/shared/annotate-args.test.ts b/packages/shared/annotate-args.test.ts
index e1c3f633..863e6dce 100644
--- a/packages/shared/annotate-args.test.ts
+++ b/packages/shared/annotate-args.test.ts
@@ -10,6 +10,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -22,6 +23,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -34,6 +36,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -46,6 +49,7 @@ describe("parseAnnotateArgs", () => {
       json: true,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -58,6 +62,7 @@ describe("parseAnnotateArgs", () => {
       json: true,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -70,6 +75,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -88,6 +94,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -100,6 +107,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -112,6 +120,7 @@ describe("parseAnnotateArgs", () => {
       json: true,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -124,6 +133,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -136,6 +146,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: true,
     });
   });
@@ -148,6 +159,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: true,
     });
   });
@@ -160,6 +172,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -172,6 +185,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -184,6 +198,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -196,6 +211,7 @@ describe("parseAnnotateArgs", () => {
       json: true,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -214,6 +230,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -226,6 +243,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -238,6 +256,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -250,6 +269,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -267,6 +287,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -279,6 +300,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -291,6 +313,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -303,6 +326,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -320,6 +344,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: true,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -332,6 +357,7 @@ describe("parseAnnotateArgs", () => {
       json: true,
       hook: true,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -344,6 +370,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: true,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -356,6 +383,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: true,
       renderHtml: false,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -368,6 +396,7 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: true,
+      renderMarkdown: false,
       noJina: false,
     });
   });
@@ -380,6 +409,33 @@ describe("parseAnnotateArgs", () => {
       json: false,
       hook: false,
       renderHtml: true,
+      renderMarkdown: false,
+      noJina: false,
+    });
+  });
+
+  test("--markdown with HTML file", () => {
+    expect(parseAnnotateArgs("plan.html --markdown")).toEqual({
+      filePath: "plan.html",
+      rawFilePath: "plan.html",
+      gate: false,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      renderMarkdown: true,
+      noJina: false,
+    });
+  });
+
+  test("--markdown and legacy --render-html both parse", () => {
+    expect(parseAnnotateArgs("plan.html --render-html --markdown")).toEqual({
+      filePath: "plan.html",
+      rawFilePath: "plan.html",
+      gate: false,
+      json: false,
+      hook: false,
+      renderHtml: true,
+      renderMarkdown: true,
       noJina: false,
     });
   });
diff --git a/packages/shared/annotate-args.ts b/packages/shared/annotate-args.ts
index 40071f49..45037f6c 100644
--- a/packages/shared/annotate-args.ts
+++ b/packages/shared/annotate-args.ts
@@ -44,6 +44,7 @@ export interface ParsedAnnotateArgs {
   json: boolean;
   hook: boolean;
   renderHtml: boolean;
+  renderMarkdown: boolean;
   noJina: boolean;
 }
 
@@ -54,12 +55,13 @@ const FLAG_MAP = {
   "--json": "json",
   "--hook": "hook",
   "--render-html": "renderHtml",
+  "--markdown": "renderMarkdown",
   "--no-jina": "noJina",
 } as const satisfies Record<string, keyof Omit<ParsedAnnotateArgs, "filePath" | "rawFilePath">>;
 
 export function parseAnnotateArgs(raw: string): ParsedAnnotateArgs {
   const s = (raw ?? "").trim();
-  const flags = { gate: false, json: false, hook: false, renderHtml: false, noJina: false };
+  const flags = { gate: false, json: false, hook: false, renderHtml: false, renderMarkdown: false, noJina: false };
 
   const segments: Segment[] = [];
   for (let i = 0; i < s.length;) {
diff --git a/packages/shared/html-assets-node.ts b/packages/shared/html-assets-node.ts
new file mode 100644
index 00000000..1b0ab734
--- /dev/null
+++ b/packages/shared/html-assets-node.ts
@@ -0,0 +1,63 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve as resolvePath, posix as pathPosix } from "node:path";
+import {
+  htmlAssetContentType,
+  rewriteCssAssetReferences,
+  rewriteHtmlAssetReferences,
+} from "./html-assets";
+
+export const MAX_HTML_ASSET_BYTES = 50 * 1024 * 1024;
+
+export function inlineHtmlLocalAssets(html: string, htmlFilePath: string): string {
+  if (/^https?:\/\//i.test(htmlFilePath)) return html;
+
+  try {
+    const root = dirname(resolvePath(htmlFilePath));
+    const activeCss = new Set<string>();
+
+    const dataUrlFor = (assetPath: string): string | null => {
+      try {
+        const contentType = htmlAssetContentType(assetPath);
+        if (!contentType) return null;
+
+        const resolved = resolvePath(root, assetPath);
+        if (!isWithinDirectory(resolved, root)) return null;
+        if (!existsSync(resolved)) return null;
+
+        const stat = statSync(resolved);
+        if (!stat.isFile() || stat.size > MAX_HTML_ASSET_BYTES) return null;
+
+        let bytes = readFileSync(resolved);
+        if (contentType.startsWith("text/css") && !activeCss.has(assetPath)) {
+          activeCss.add(assetPath);
+          try {
+            const cssBase = pathPosix.dirname(assetPath);
+            const rewrittenCss = rewriteCssAssetReferences(
+              bytes.toString("utf-8"),
+              dataUrlFor,
+              cssBase === "." ? "" : cssBase,
+            );
+            bytes = Buffer.from(rewrittenCss, "utf-8");
+          } finally {
+            activeCss.delete(assetPath);
+          }
+        }
+
+        return `data:${contentType.replace(/;\s*/g, ";")};base64,${Buffer.from(bytes).toString("base64")}`;
+      } catch {
+        return null;
+      }
+    };
+
+    return rewriteHtmlAssetReferences(html, dataUrlFor);
+  } catch {
+    return html;
+  }
+}
+
+function isWithinDirectory(filePath: string, root: string): boolean {
+  const resolved = resolvePath(filePath);
+  const resolvedRoot = resolvePath(root);
+  const rel = relative(resolvedRoot, resolved);
+  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
diff --git a/packages/shared/html-assets.test.ts b/packages/shared/html-assets.test.ts
new file mode 100644
index 00000000..a5d4596b
--- /dev/null
+++ b/packages/shared/html-assets.test.ts
@@ -0,0 +1,113 @@
+import { describe, expect, test } from "bun:test";
+import {
+  encodeHtmlAssetPath,
+  htmlAssetContentType,
+  rewriteCssAssetReferences,
+  normalizeHtmlAssetRoutePath,
+  rewriteHtmlAssetReferences,
+} from "./html-assets";
+
+describe("rewriteHtmlAssetReferences", () => {
+  const rewrite = (html: string) =>
+    rewriteHtmlAssetReferences(html, (assetPath) => `/api/html-assets/t/${encodeHtmlAssetPath(assetPath)}`);
+
+  test("rewrites direct local support assets", () => {
+    const html = `<!doctype html>
+<html>
+  <head>
+    <link rel="stylesheet" href="./style.css?v=1">
+    <link rel="icon" href="icons/app icon.png">
+    <style>.hero { background: url("./hero.png#cover"); }</style>
+    <script src="app.js"></script>
+  </head>
+  <body>
+    <img src="./images/logo.png" srcset="./small.png 1x, ./large.png 2x" style="background-image: url('./inline-bg.webp')">
+    <video src="movie.mp4" poster="poster.jpg"></video>
+    <audio src="intro.mp3"></audio>
+  </body>
+</html>`;
+
+    const out = rewrite(html);
+
+    expect(out).toContain('href="/api/html-assets/t/style.css?v=1"');
+    expect(out).toContain('href="/api/html-assets/t/icons/app%20icon.png"');
+    expect(out).toContain('background: url("/api/html-assets/t/hero.png#cover")');
+    expect(out).toContain('src="/api/html-assets/t/app.js"');
+    expect(out).toContain('src="/api/html-assets/t/images/logo.png"');
+    expect(out).toContain('srcset="/api/html-assets/t/small.png 1x, /api/html-assets/t/large.png 2x"');
+    expect(out).toContain('background-image: url(&quot;/api/html-assets/t/inline-bg.webp&quot;)');
+    expect(out).toContain('src="/api/html-assets/t/movie.mp4"');
+    expect(out).toContain('poster="/api/html-assets/t/poster.jpg"');
+    expect(out).toContain('src="/api/html-assets/t/intro.mp3"');
+  });
+
+  test("leaves external, root-relative, data, anchors, and navigation links alone", () => {
+    const html = `
+<link rel="stylesheet" href="https://cdn.example.com/app.css">
+<link rel="stylesheet" href="/site.css">
+<a href="other.html">Other page</a>
+<a href="#section">Section</a>
+<img src="data:image/png;base64,abc">
+<img src="//cdn.example.com/image.png">
+`;
+
+    const out = rewrite(html);
+
+    expect(out).toContain('href="https://cdn.example.com/app.css"');
+    expect(out).toContain('href="/site.css"');
+    expect(out).toContain('href="other.html"');
+    expect(out).toContain('href="#section"');
+    expect(out).toContain('src="data:image/png;base64,abc"');
+    expect(out).toContain('src="//cdn.example.com/image.png"');
+  });
+
+  test("does not rewrite traversal or unknown extension asset refs", () => {
+    const out = rewrite('<img src="../secret.png"><script src="server"></script>');
+
+    expect(out).toContain('src="../secret.png"');
+    expect(out).toContain('src="server"');
+  });
+});
+
+describe("rewriteCssAssetReferences", () => {
+  test("rewrites local url() references relative to the stylesheet path", () => {
+    const css = `
+body { background: url("../images/bg.png?v=1"); }
+@font-face { src: url("./font.woff2") format("woff2"); }
+@import "./theme.css";
+.remote { background: url("https://example.test/a.png"); }
+`;
+
+    const out = rewriteCssAssetReferences(
+      css,
+      (assetPath) => `/assets/${encodeHtmlAssetPath(assetPath)}`,
+      "styles",
+    );
+
+    expect(out).toContain('url("/assets/images/bg.png?v=1")');
+    expect(out).toContain('url("/assets/styles/font.woff2")');
+    expect(out).toContain('@import url("/assets/styles/theme.css")');
+    expect(out).toContain('url("https://example.test/a.png")');
+  });
+});
+
+describe("html asset route helpers", () => {
+  test("normalizes valid route paths", () => {
+    expect(normalizeHtmlAssetRoutePath("assets/logo%20small.png")).toBe("assets/logo small.png");
+    expect(normalizeHtmlAssetRoutePath("./assets/../logo.svg")).toBe("logo.svg");
+    expect(normalizeHtmlAssetRoutePath("assets/100%2525%20done.png")).toBe("assets/100%25 done.png");
+  });
+
+  test("rejects traversal and invalid encodings", () => {
+    expect(normalizeHtmlAssetRoutePath("../logo.png")).toBeNull();
+    expect(normalizeHtmlAssetRoutePath("..%2Flogo.png")).toBeNull();
+    expect(normalizeHtmlAssetRoutePath("%E0%A4%A")).toBeNull();
+  });
+
+  test("returns expected content types", () => {
+    expect(htmlAssetContentType("style.css")).toBe("text/css; charset=utf-8");
+    expect(htmlAssetContentType("font.woff2")).toBe("font/woff2");
+    expect(htmlAssetContentType("site.webmanifest")).toBe("application/manifest+json; charset=utf-8");
+    expect(htmlAssetContentType("image.unknown")).toBeNull();
+  });
+});
diff --git a/packages/shared/html-assets.ts b/packages/shared/html-assets.ts
new file mode 100644
index 00000000..bd08a40c
--- /dev/null
+++ b/packages/shared/html-assets.ts
@@ -0,0 +1,308 @@
+import { posix as pathPosix } from "path";
+import * as parse5 from "parse5";
+
+export const HTML_ASSET_ROUTE_PREFIX = "/api/html-assets";
+
+const CONTENT_TYPES_BY_EXT: Record<string, string> = {
+  ".apng": "image/apng",
+  ".avif": "image/avif",
+  ".css": "text/css; charset=utf-8",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "application/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".mjs": "application/javascript; charset=utf-8",
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".ogg": "audio/ogg",
+  ".otf": "font/otf",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".ttf": "font/ttf",
+  ".wav": "audio/wav",
+  ".webmanifest": "application/manifest+json; charset=utf-8",
+  ".webm": "video/webm",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".xml": "application/xml; charset=utf-8",
+};
+
+interface HtmlAttr {
+  name: string;
+  value: string;
+}
+
+interface HtmlNode {
+  tagName?: string;
+  attrs?: HtmlAttr[];
+  childNodes?: HtmlNode[];
+  value?: string;
+}
+
+type HtmlAssetUrlMapper = (assetPath: string) => string | null;
+
+export function htmlAssetContentType(assetPath: string): string | null {
+  return CONTENT_TYPES_BY_EXT[pathPosix.extname(assetPath).toLowerCase()] ?? null;
+}
+
+export function encodeHtmlAssetPath(assetPath: string): string {
+  return assetPath.split("/").map(encodeURIComponent).join("/");
+}
+
+export function normalizeHtmlAssetRoutePath(routePath: string): string | null {
+  const decoded = decodeUrlPath(routePath);
+  if (decoded === null) return null;
+  return normalizeDecodedLocalAssetPath(decoded);
+}
+
+export function rewriteHtmlAssetReferences(
+  html: string,
+  assetUrlFor: HtmlAssetUrlMapper,
+): string {
+  const tree = looksLikeFullDocument(html)
+    ? parse5.parse(html)
+    : parse5.parseFragment(html);
+  visit(tree as unknown as HtmlNode, (node) => rewriteNodeAssetReferences(node, assetUrlFor));
+  return parse5.serialize(tree as never);
+}
+
+export function rewriteCssAssetReferences(
+  css: string,
+  assetUrlFor: HtmlAssetUrlMapper,
+  basePath = "",
+): string {
+  let rewritten = css.replace(
+    /url\(\s*(["']?)([^"')]+)\1\s*\)/gi,
+    (match, _quote: string, value: string) => {
+      const next = rewriteLocalAssetUrl(value, assetUrlFor, basePath);
+      return next === null ? match : `url("${next}")`;
+    },
+  );
+
+  rewritten = rewritten.replace(
+    /@import\s+(?:url\(\s*)?(["'])([^"']+)\1\s*\)?/gi,
+    (match, _quote: string, value: string) => {
+      const next = rewriteLocalAssetUrl(value, assetUrlFor, basePath);
+      return next === null ? match : `@import url("${next}")`;
+    },
+  );
+
+  return rewritten;
+}
+
+function rewriteNodeAssetReferences(
+  node: HtmlNode,
+  assetUrlFor: HtmlAssetUrlMapper,
+): void {
+  const tagName = node.tagName?.toLowerCase();
+  if (!tagName) return;
+
+  rewriteStyleAttr(node, assetUrlFor);
+
+  if (tagName === "style") {
+    rewriteStyleContent(node, assetUrlFor);
+    return;
+  }
+
+  if (tagName === "img") {
+    rewriteAttr(node, "src", assetUrlFor);
+    rewriteSrcsetAttr(node, "srcset", assetUrlFor);
+    return;
+  }
+
+  if (tagName === "source") {
+    rewriteAttr(node, "src", assetUrlFor);
+    rewriteSrcsetAttr(node, "srcset", assetUrlFor);
+    return;
+  }
+
+  if (tagName === "video") {
+    rewriteAttr(node, "src", assetUrlFor);
+    rewriteAttr(node, "poster", assetUrlFor);
+    return;
+  }
+
+  if (tagName === "audio" || tagName === "script") {
+    rewriteAttr(node, "src", assetUrlFor);
+    return;
+  }
+
+  if (tagName === "link" && isSupportLink(node)) {
+    rewriteAttr(node, "href", assetUrlFor);
+  }
+}
+
+function visit(node: HtmlNode, fn: (node: HtmlNode) => void): void {
+  fn(node);
+  for (const child of node.childNodes ?? []) visit(child, fn);
+}
+
+function rewriteAttr(
+  node: HtmlNode,
+  name: string,
+  assetUrlFor: HtmlAssetUrlMapper,
+): void {
+  const attr = findAttr(node, name);
+  if (!attr) return;
+  const rewritten = rewriteLocalAssetUrl(attr.value, assetUrlFor);
+  if (rewritten !== null) attr.value = rewritten;
+}
+
+function rewriteSrcsetAttr(
+  node: HtmlNode,
+  name: string,
+  assetUrlFor: HtmlAssetUrlMapper,
+): void {
+  const attr = findAttr(node, name);
+  if (!attr) return;
+  const rewritten = rewriteSrcset(attr.value, assetUrlFor);
+  if (rewritten !== attr.value) attr.value = rewritten;
+}
+
+function findAttr(node: HtmlNode, name: string): HtmlAttr | null {
+  const target = name.toLowerCase();
+  return node.attrs?.find((attr) => attr.name.toLowerCase() === target) ?? null;
+}
+
+function attrValue(node: HtmlNode, name: string): string | null {
+  return findAttr(node, name)?.value.trim() ?? null;
+}
+
+function rewriteStyleAttr(node: HtmlNode, assetUrlFor: HtmlAssetUrlMapper): void {
+  const attr = findAttr(node, "style");
+  if (!attr) return;
+  attr.value = rewriteCssAssetReferences(attr.value, assetUrlFor);
+}
+
+function rewriteStyleContent(node: HtmlNode, assetUrlFor: HtmlAssetUrlMapper): void {
+  for (const child of node.childNodes ?? []) {
+    if (typeof child.value === "string") {
+      child.value = rewriteCssAssetReferences(child.value, assetUrlFor);
+    }
+  }
+}
+
+function isSupportLink(node: HtmlNode): boolean {
+  const rel = attrValue(node, "rel");
+  if (!rel) return false;
+  const tokens = new Set(rel.toLowerCase().split(/\s+/).filter(Boolean));
+  return (
+    tokens.has("stylesheet") ||
+    tokens.has("preload") ||
+    tokens.has("modulepreload") ||
+    tokens.has("icon") ||
+    tokens.has("apple-touch-icon") ||
+    tokens.has("mask-icon") ||
+    tokens.has("manifest")
+  );
+}
+
+function rewriteLocalAssetUrl(
+  value: string,
+  assetUrlFor: HtmlAssetUrlMapper,
+  basePath = "",
+): string | null {
+  const trimmed = value.trim();
+  if (shouldSkipUrl(trimmed)) return null;
+
+  const { path, suffix } = splitPathSuffix(trimmed);
+  const normalized = normalizeLocalAssetPath(
+    basePath ? pathPosix.join(basePath, path) : path,
+  );
+  if (normalized === null) return null;
+  if (htmlAssetContentType(normalized) === null) return null;
+
+  const next = assetUrlFor(normalized);
+  if (next === null) return null;
+  return /^data:/i.test(next) ? next : `${next}${suffix}`;
+}
+
+function rewriteSrcset(
+  srcset: string,
+  assetUrlFor: HtmlAssetUrlMapper,
+): string {
+  const rewritten: string[] = [];
+  let changed = false;
+  let i = 0;
+
+  while (i < srcset.length) {
+    while (i < srcset.length && /[\s,]/u.test(srcset[i])) i++;
+    if (i >= srcset.length) break;
+
+    const urlStart = i;
+    while (i < srcset.length && !/[\s,]/u.test(srcset[i])) i++;
+
+    if (srcset.slice(urlStart, i).toLowerCase().startsWith("data:")) {
+      while (i < srcset.length && !/\s/u.test(srcset[i])) i++;
+    }
+
+    const originalUrl = srcset.slice(urlStart, i);
+    const descriptorStart = i;
+    while (i < srcset.length && srcset[i] !== ",") i++;
+    const descriptor = srcset.slice(descriptorStart, i).trim();
+
+    const nextUrl = rewriteLocalAssetUrl(originalUrl, assetUrlFor) ?? originalUrl;
+    if (nextUrl !== originalUrl) changed = true;
+    rewritten.push(descriptor ? `${nextUrl} ${descriptor}` : nextUrl);
+
+    if (srcset[i] === ",") i++;
+  }
+
+  return changed ? rewritten.join(", ") : srcset;
+}
+
+function shouldSkipUrl(value: string): boolean {
+  if (!value || value.startsWith("#") || value.startsWith("/") || value.startsWith("//")) {
+    return true;
+  }
+  return /^[a-z][a-z0-9+.-]*:/i.test(value);
+}
+
+function splitPathSuffix(value: string): { path: string; suffix: string } {
+  const queryIndex = value.indexOf("?");
+  const hashIndex = value.indexOf("#");
+  let splitAt = -1;
+  if (queryIndex >= 0) splitAt = queryIndex;
+  if (hashIndex >= 0 && (splitAt < 0 || hashIndex < splitAt)) splitAt = hashIndex;
+  if (splitAt < 0) return { path: value, suffix: "" };
+  return { path: value.slice(0, splitAt), suffix: value.slice(splitAt) };
+}
+
+function decodeUrlPath(value: string): string | null {
+  try {
+    return value
+      .split("/")
+      .map((segment) => decodeURIComponent(segment))
+      .join("/");
+  } catch {
+    return null;
+  }
+}
+
+function normalizeLocalAssetPath(value: string): string | null {
+  const decoded = decodeUrlPath(value.trim());
+  if (decoded === null) return null;
+  return normalizeDecodedLocalAssetPath(decoded);
+}
+
+function normalizeDecodedLocalAssetPath(value: string): string | null {
+  const normalized = pathPosix.normalize(value.trim().replace(/\\/g, "/"));
+  if (
+    normalized === "." ||
+    normalized === ".." ||
+    normalized.startsWith("../") ||
+    normalized.startsWith("/") ||
+    normalized.includes("\0") ||
+    /[\u0000-\u001f]/u.test(normalized)
+  ) {
+    return null;
+  }
+  return normalized;
+}
+
+function looksLikeFullDocument(html: string): boolean {
+  return /<!doctype\s+html|<html[\s>]|<head[\s>]|<body[\s>]/i.test(html);
+}
diff --git a/packages/shared/html-to-markdown.ts b/packages/shared/html-to-markdown.ts
index c13189d8..028bfa01 100644
--- a/packages/shared/html-to-markdown.ts
+++ b/packages/shared/html-to-markdown.ts
@@ -1,8 +1,8 @@
 /**
  * HTML-to-Markdown conversion via Turndown.
  *
- * Shared between the CLI (single HTML file / URL) and the server
- * (on-demand conversion for HTML files in folder mode).
+ * Shared between URL fetching, `annotate --markdown`, and the server's
+ * on-demand conversion for HTML files in folder mode.
  */
 
 import TurndownService from "turndown";
diff --git a/packages/shared/package.json b/packages/shared/package.json
index efd8aeb4..31b320cf 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -40,6 +40,8 @@
     "./worktree-pool": "./worktree-pool.ts",
     "./html-to-markdown": "./html-to-markdown.ts",
     "./url-to-markdown": "./url-to-markdown.ts",
+    "./html-assets": "./html-assets.ts",
+    "./html-assets-node": "./html-assets-node.ts",
     "./tour": "./tour.ts",
     "./annotate-args": "./annotate-args.ts",
     "./at-reference": "./at-reference.ts",
@@ -50,6 +52,7 @@
   },
   "dependencies": {
     "@joplin/turndown-plugin-gfm": "^1.0.64",
+    "parse5": "^7.3.0",
     "turndown": "^7.2.4"
   }
 }
diff --git a/packages/shared/url-to-markdown.ts b/packages/shared/url-to-markdown.ts
index b6c96f55..19f68e92 100644
--- a/packages/shared/url-to-markdown.ts
+++ b/packages/shared/url-to-markdown.ts
@@ -23,7 +23,7 @@ export const isConvertedSource = (source: UrlToMarkdownResult["source"]): boolea
   source === "jina" || source === "fetch+turndown";
 
 const FETCH_TIMEOUT_MS = 30_000;
-const MAX_BODY_BYTES = 10 * 1024 * 1024; // 10 MB — matches local HTML file guard
+const MAX_BODY_BYTES = 10 * 1024 * 1024;
 
 /**
  * Skip Jina for local/private URLs — fetch them directly instead.
diff --git a/packages/ui/components/ExportModal.tsx b/packages/ui/components/ExportModal.tsx
index 251001f0..4d86e6fe 100644
--- a/packages/ui/components/ExportModal.tsx
+++ b/packages/ui/components/ExportModal.tsx
@@ -25,7 +25,7 @@ interface ExportModalProps {
   /** Error from the last short URL generation attempt (empty string = no error) */
   shortUrlError?: string;
   /** Generate a short URL on demand (user clicks "Create short link") */
-  onGenerateShortUrl?: () => void;
+  onGenerateShortUrl?: () => void | Promise<unknown>;
   annotationsOutput: string;
   annotationCount: number;
   taterSprite?: React.ReactNode;
diff --git a/packages/ui/hooks/useLinkedDoc.ts b/packages/ui/hooks/useLinkedDoc.ts
index b6c62940..acee5d48 100644
--- a/packages/ui/hooks/useLinkedDoc.ts
+++ b/packages/ui/hooks/useLinkedDoc.ts
@@ -24,8 +24,10 @@ export interface UseLinkedDocOptions {
    *  swaps these to render raw; back() restores the base values from this snapshot. */
   renderAs: 'markdown' | 'html';
   rawHtml: string;
+  shareHtml: string;
   setRenderAs: (r: 'markdown' | 'html') => void;
   setRawHtml: (html: string) => void;
+  setShareHtml: (html: string) => void;
   viewerRef: React.RefObject<ViewerHandle | null>;
   sidebar: { open: (tab?: SidebarTab) => void };
   /** Absolute path of the primary document — enables getDocAnnotations() to include
@@ -43,6 +45,7 @@ interface SavedPlanState {
   globalAttachments: ImageAttachment[];
   renderAs: 'markdown' | 'html';
   rawHtml: string;
+  shareHtml: string;
 }
 
 export interface CachedDocState {
@@ -96,8 +99,10 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
     setGlobalAttachments,
     renderAs,
     rawHtml,
+    shareHtml,
     setRenderAs,
     setRawHtml,
+    setShareHtml,
     viewerRef,
     sidebar,
     sourceFilePath,
@@ -134,6 +139,7 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
           isConverted?: boolean;
           renderAs?: 'markdown' | 'html';
           rawHtml?: string;
+          shareHtml?: string;
           error?: string;
           matches?: string[];
         };
@@ -167,6 +173,7 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
             globalAttachments: [...globalAttachments],
             renderAs,
             rawHtml,
+            shareHtml,
           };
           let total = annotations.length + globalAttachments.length;
           for (const [fp, cached] of docCache.current.entries()) {
@@ -202,6 +209,7 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
         const docRenderAs = data.renderAs === 'html' ? 'html' : 'markdown';
         setRenderAs(docRenderAs);
         setRawHtml(docRenderAs === 'html' ? (data.rawHtml ?? '') : '');
+        setShareHtml(docRenderAs === 'html' ? (data.shareHtml ?? '') : '');
         setMarkdown(docRenderAs === 'html' ? '' : (data.markdown ?? ''));
         setAnnotations(cached?.annotations ?? []);
         setGlobalAttachments(cached?.globalAttachments ?? []);
@@ -233,6 +241,7 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
       globalAttachments,
       renderAs,
       rawHtml,
+      shareHtml,
       linkedDoc,
       setMarkdown,
       setAnnotations,
@@ -240,6 +249,7 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
       setGlobalAttachments,
       setRenderAs,
       setRawHtml,
+      setShareHtml,
       viewerRef,
       sidebar,
     ]
@@ -271,6 +281,7 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
     const saved = savedPlanState.current;
     setRenderAs(saved.renderAs);
     setRawHtml(saved.rawHtml);
+    setShareHtml(saved.shareHtml);
     setMarkdown(saved.markdown);
     setAnnotations(saved.annotations);
     setGlobalAttachments(saved.globalAttachments);
@@ -296,6 +307,7 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
     setGlobalAttachments,
     setRenderAs,
     setRawHtml,
+    setShareHtml,
     viewerRef,
   ]);
 
@@ -317,6 +329,7 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
           markdown: savedPlanState.current.markdown,
           renderAs: savedPlanState.current.renderAs,
           rawHtml: savedPlanState.current.rawHtml,
+          shareHtml: savedPlanState.current.shareHtml,
           annotations: [...savedPlanState.current.annotations],
           selectedAnnotationId: savedPlanState.current.selectedAnnotationId,
           globalAttachments: [...savedPlanState.current.globalAttachments],
@@ -325,13 +338,14 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
           markdown,
           renderAs,
           rawHtml,
+          shareHtml,
           annotations: [...annotations],
           selectedAnnotationId,
           globalAttachments: [...globalAttachments],
         };
 
     return { root, docs };
-  }, [linkedDoc, annotations, globalAttachments, markdown, renderAs, rawHtml, selectedAnnotationId]);
+  }, [linkedDoc, annotations, globalAttachments, markdown, renderAs, rawHtml, shareHtml, selectedAnnotationId]);
 
   const restoreSession = useCallback((state: LinkedDocSessionState) => {
     viewerRef.current?.clearAllHighlights();
@@ -345,6 +359,9 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
     setDocAnnotationCount(total);
 
     setMarkdown(state.root.markdown);
+    setRenderAs(state.root.renderAs);
+    setRawHtml(state.root.rawHtml);
+    setShareHtml(state.root.shareHtml);
     setAnnotations([...state.root.annotations]);
     setGlobalAttachments([...state.root.globalAttachments]);
     setSelectedAnnotationId(state.root.selectedAnnotationId);
@@ -362,6 +379,9 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
     setAnnotations,
     setSelectedAnnotationId,
     setGlobalAttachments,
+    setRenderAs,
+    setRawHtml,
+    setShareHtml,
     viewerRef,
   ]);
 
diff --git a/packages/ui/hooks/useSharing.ts b/packages/ui/hooks/useSharing.ts
index 7d5bb984..67e7e5c7 100644
--- a/packages/ui/hooks/useSharing.ts
+++ b/packages/ui/hooks/useSharing.ts
@@ -64,7 +64,7 @@ interface UseSharingResult {
   refreshShareUrl: () => Promise<void>;
 
   /** Generate a short URL via the paste service (user must explicitly trigger this) */
-  generateShortUrl: () => Promise<void>;
+  generateShortUrl: () => Promise<string | null>;
 
   /** Import annotations from a teammate's share URL */
   importFromShareUrl: (url: string) => Promise<ImportResult>;
@@ -100,7 +100,9 @@ export function useSharing(
   shareBaseUrl?: string,
   pasteApiUrl?: string,
   rawHtml?: string,
+  resolveRawHtmlForShare?: () => Promise<string | null>,
   setRawHtml?: (h: string) => void,
+  setShareHtml?: (h: string) => void,
   setRenderAs?: (m: 'markdown' | 'html') => void,
 ): UseSharingResult {
   const [isSharedSession, setIsSharedSession] = useState(false);
@@ -141,22 +143,22 @@ export function useSharing(
         if (payload) {
           if (payload.h && payload.r === 'html') {
             setRawHtml?.(payload.h);
+            setShareHtml?.(payload.h);
             setRenderAs?.('html');
             setMarkdown('');
           } else {
             setMarkdown(payload.p);
             setRenderAs?.('markdown');
             setRawHtml?.('');
+            setShareHtml?.('');
           }
 
           const restoredAnnotations = fromShareable(payload.a, payload.d, payload.s);
           setAnnotations(restoredAnnotations);
 
-          if (payload.g?.length) {
-            const parsed = parseShareableImages(payload.g) ?? [];
-            setGlobalAttachments(parsed);
-            setSharedGlobalAttachments(parsed);
-          }
+          const parsedGlobalAttachments = parseShareableImages(payload.g) ?? [];
+          setGlobalAttachments(parsedGlobalAttachments);
+          setSharedGlobalAttachments(parsedGlobalAttachments.length ? parsedGlobalAttachments : null);
 
           setPendingSharedAnnotations(restoredAnnotations);
           setIsSharedSession(true);
@@ -188,24 +190,23 @@ export function useSharing(
       if (payload) {
         if (payload.h && payload.r === 'html') {
           setRawHtml?.(payload.h);
+          setShareHtml?.(payload.h);
           setRenderAs?.('html');
           setMarkdown('');
         } else {
           setMarkdown(payload.p);
           setRenderAs?.('markdown');
           setRawHtml?.('');
+          setShareHtml?.('');
         }
 
         // Convert shareable annotations to full annotations
         const restoredAnnotations = fromShareable(payload.a, payload.d, payload.s);
         setAnnotations(restoredAnnotations);
 
-        // Restore global attachments if present
-        if (payload.g?.length) {
-          const parsed = parseShareableImages(payload.g) ?? [];
-          setGlobalAttachments(parsed);
-          setSharedGlobalAttachments(parsed);
-        }
+        const parsedGlobalAttachments = parseShareableImages(payload.g) ?? [];
+        setGlobalAttachments(parsedGlobalAttachments);
+        setSharedGlobalAttachments(parsedGlobalAttachments.length ? parsedGlobalAttachments : null);
 
         // Store for later application to DOM
         setPendingSharedAnnotations(restoredAnnotations);
@@ -236,7 +237,7 @@ export function useSharing(
       setShareLoadError('Failed to load shared plan — an unexpected error occurred.');
       return false;
     }
-  }, [setMarkdown, setAnnotations, setGlobalAttachments, onSharedLoad, pasteApiUrl, setRawHtml, setRenderAs]);
+  }, [setMarkdown, setAnnotations, setGlobalAttachments, onSharedLoad, pasteApiUrl, setRawHtml, setShareHtml, setRenderAs]);
 
   // Load from hash on mount
   useEffect(() => {
@@ -281,7 +282,7 @@ export function useSharing(
     if (isSharedRef.current) { isSharedRef.current = false; return; }
     setShortShareUrl('');
     setShortUrlError('');
-  }, [markdown, annotations, rawHtml, isSharedSession]);
+  }, [markdown, annotations, globalAttachments, rawHtml, isSharedSession]);
 
   /**
    * Generate a short URL via the paste service.
@@ -289,34 +290,40 @@ export function useSharing(
    * Clears the short URL if the service is unavailable — the full
    * hash-based URL remains usable as a fallback.
    */
-  const generateShortUrl = useCallback(async () => {
-    if (!markdown && !rawHtml) return;
+  const generateShortUrl = useCallback(async (): Promise<string | null> => {
+    if (!markdown && !rawHtml) return null;
 
     setIsGeneratingShortUrl(true);
     setShortUrlError('');
 
     try {
+      const htmlForShare = rawHtml
+        ? (await resolveRawHtmlForShare?.()) ?? rawHtml
+        : undefined;
       const result = await createShortShareUrl(
         markdown,
         annotations,
         globalAttachments,
         { pasteApiUrl, shareBaseUrl },
-        rawHtml,
+        htmlForShare,
       );
 
       if (result) {
         setShortShareUrl(result.shortUrl);
+        return result.shortUrl;
       } else {
         setShortShareUrl('');
         setShortUrlError('Short URL service unavailable');
+        return null;
       }
-    } catch {
+    } catch (e) {
       setShortShareUrl('');
-      setShortUrlError('Failed to generate short URL');
+      setShortUrlError(e instanceof Error ? e.message : 'Failed to generate short URL');
+      return null;
     } finally {
       setIsGeneratingShortUrl(false);
     }
-  }, [markdown, annotations, globalAttachments, shareBaseUrl, pasteApiUrl, rawHtml]);
+  }, [markdown, annotations, globalAttachments, shareBaseUrl, pasteApiUrl, rawHtml, resolveRawHtmlForShare]);
 
   // Import annotations from a teammate's share URL (supports both hash-based and short /p/<id> URLs)
   const importFromShareUrl = useCallback(async (url: string): Promise<ImportResult> => {
diff --git a/packages/ui/utils/sharing.ts b/packages/ui/utils/sharing.ts
index 3be5ab26..8b473452 100644
--- a/packages/ui/utils/sharing.ts
+++ b/packages/ui/utils/sharing.ts
@@ -27,7 +27,7 @@ export interface SharePayload {
   g?: ShareableImage[];  // global attachments (path strings or [path, name] tuples)
   d?: (string | null)[];  // diffContext per annotation, parallel to `a`
   s?: (string | undefined)[];  // source per annotation (external tool identifier), parallel to `a`
-  h?: string;  // raw HTML content (render-html mode)
+  h?: string;  // raw HTML content (direct HTML rendering mode)
   r?: 'html';  // render mode flag (omitted = markdown)
 }
 
@@ -220,6 +220,13 @@ export function formatUrlSize(url: string): string {
 const DEFAULT_PASTE_API = 'https://plannotator-paste.plannotator.workers.dev';
 const DEFAULT_SHARE_BASE = 'https://share.plannotator.ai';
 
+export class ShortShareUrlError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ShortShareUrlError';
+  }
+}
+
 /**
  * Create a short share URL by posting compressed plan data to the paste service.
  *
@@ -269,6 +276,9 @@ export async function createShortShareUrl(
     });
 
     if (!response.ok) {
+      if (response.status === 413) {
+        throw new ShortShareUrlError(await readPasteError(response, 'Share payload is too large'));
+      }
       console.warn(`[sharing] Paste service returned ${response.status}`);
       return null;
     }
@@ -283,6 +293,9 @@ export async function createShortShareUrl(
 
     return { shortUrl, id: result.id };
   } catch (e) {
+    if (e instanceof ShortShareUrlError) {
+      throw e;
+    }
     // Service unavailable — expected for self-hosted setups without a paste backend.
     // The caller is responsible for falling back to hash-based sharing silently.
     console.debug('[sharing] Short URL service unavailable, using hash-based sharing:', e);
@@ -290,6 +303,15 @@ export async function createShortShareUrl(
   }
 }
 
+async function readPasteError(response: Response, fallback: string): Promise<string> {
+  try {
+    const body = (await response.json()) as { error?: unknown };
+    return typeof body.error === 'string' && body.error.trim() ? body.error : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
 /**
  * Load plan data from a paste service using the paste ID embedded in a short URL.
  *