@blocofy/cli 0.17.1 → 0.18.0

package/README.md

@@ -125,9 +125,9 @@ Show which site a command in `[dir]` would hit (verified), without writing anyth
 ```
 blocofy theme dev [dir] [--port <n>] [--no-sync] [--name <name>] [--instance <handle>]
 ```
-Start a local dev server that renders your local theme files with the site's live content.
-Press `l` to open it, `q` to quit. Edit a file and save → the view reloads. Saves sync to a
-**draft** theme only (never the live site). `dir` defaults to cwd. The platform's remote preview
+Start a local dev server that shows a **draft** theme: your local theme files with that draft's
+saved content (local draft browsing). Press `l` to open it, `q` to quit. Edit a file and save → the
+view reloads. Saves sync to a **draft** theme only (never the live site). `dir` defaults to cwd. The platform's remote preview
 and editor views for this command are retired; to share a draft page, create a preview link for
 it (v1 API `POST /themes/{id}/preview-links` or MCP `create_preview_link`; one page per link).
 The target site is verified once at start; a long session keeps that target (restart it after
@@ -136,10 +136,61 @@ The dev server answers this machine only: it listens on `http://127.0.0.1:<port>
 whose `Host` (or `Origin`, when sent) is not that address or `localhost:<port>`, and answers only
 `GET`/`HEAD` (anything else gets `405`). The reload channel is same-origin only.
 - `--port <n>` — local port (default 3030).
-- `--no-sync` — local preview only (skip draft sync).
+- `--no-sync` — do not sync; needs `--instance <draft-handle>` to have something to show. Without it
+  the local view only shows an error page (there is no implicit live preview).
 - `--name <name>` — name the draft when it is first created (ignored if it already exists).
-- `--instance <handle>` — sync into this draft. Needed when the platform cannot tell which draft is the
-  CLI draft (see "Which draft a draft command writes to" below); the live theme's handle is refused.
+- `--instance <handle>` — sync into and show this draft. Needed when the platform cannot tell which
+  draft is the CLI draft (see "Which draft a draft command writes to" below); the live theme's handle
+  is refused.
+
+**Local draft browsing.** The local view renders only a draft theme, never the live one:
+- Which draft: `--instance` (or the theme work saved by `init` / `theme work start`), otherwise the
+  draft the startup sync wrote to. With no draft the CLI does not ask the platform to render at all and
+  the page says "Tema hedefi hazırlanamadı" with the reason (sync failure, no handle returned,
+  `--no-sync` without `--instance`). Requests are never sent with a live theme.
+- What you see: your **local theme files** plus the draft's **saved** content (pages, entries,
+  settings); drafts and scheduled entries are visible, trashed pages and entries are not. The platform
+  adds the local preview band; the CLI adds only the reload script.
+- Navigation stays local: links, `area`s, form actions, `formaction`, `<meta http-equiv=refresh>` and
+  `<link rel=alternate>` that point at one of the site's own addresses (as the platform reports them,
+  also protocol-relative `//host/…`) are rewritten to `http://127.0.0.1:<port>`, keeping path, query and
+  hash. Relative links, other sites and other tenants are left alone. A `javascript:`, `data:` or
+  `vbscript:` URL, a URL with a user name/password, a malformed URL or one with a character reference
+  the CLI cannot decode is removed from those attributes (marked `data-blocofy-blocked="<attribute>"`).
+  Images, scripts, stylesheets, iframes and `<link rel=canonical>` are not touched (assets load from the
+  site's system host; canonical keeps the site's public address).
+- The query string reaches the theme (pagination, filters); the `#hash` stays in the browser.
+- A missing page is answered with HTTP 404 and the draft's own 404 page, plus a small note with the
+  reason. Redirects (for example to a language's canonical address) are not followed locally: the note
+  shows where the live site would redirect.
+- Platform refusals (`instance_is_live`, `instance_not_found`, `bad_search`, …) are shown as a page with
+  their code and HTTP status. A platform that does not speak this contract (version 2) gets the page
+  "Platform sürümü yerel taslak gezinmeyi desteklemiyor"; its HTML is never shown as your draft.
+- **Forms are not sent from the local view.** Every HTML answer carries the header
+  `Content-Security-Policy: form-action 'self'; connect-src 'self'; base-uri 'none'` (plus
+  `Referrer-Policy: no-referrer`, `X-Content-Type-Options: nosniff`, `Cache-Control: no-store`). Any form
+  submission can only reach the local server, which answers `405` with "Yerel önizlemede formlar
+  gönderilmez"; a `GET` search form becomes a local page request. `fetch`, XHR, `sendBeacon`, WebSocket
+  and `<a ping>` to the live site or third parties are blocked. A theme's own `<meta>` CSP applies on top
+  (the stricter rule wins).
+
+Known limits of local draft browsing:
+- Navigation done by JavaScript (`location.href = …`, `window.open`, the History API, inline `onclick`
+  handlers, a JS redirect) is not rewritten and can open the live site or another address.
+- Scripts, images, iframes and fonts are not restricted (so menus, sliders and embeds work): a theme or
+  third-party script can still load images or frames from other sites (a `GET` request, e.g. a
+  tracking pixel), and JavaScript can open another site in the top window or a new one. The CLI does
+  not claim the local view has no outside effects; it blocks form submissions and script network calls.
+- Features that call the live site from the browser (load-more by `fetch`, search-as-you-type, etc.)
+  do not work locally (`connect-src 'self'`).
+- `http://<site host>` links are matched only when they equal one of the site's addresses exactly
+  (normally `https://`), so an `http://` link to the site is left as is.
+- Absolute form actions are rewritten to `127.0.0.1`; open the view on `http://127.0.0.1:<port>` (the
+  printed address), on `localhost:<port>` such a form is refused by the browser.
+- The link rewrite reads HTML tags, comments and raw-text elements (`script`, `style`, `textarea`,
+  `title`, `noscript`, …) like a browser, but not the rarer escape rules inside `<script>` or SVG/MathML
+  `CDATA`; such text may be left unmapped. A `javascript:` link that a theme uses as a menu toggle loses
+  its `href` (its click handler still runs, but it is no longer keyboard-focusable).
 
 ```
 blocofy theme pull [dir] [--draft] [--instance <handle>]
@@ -626,6 +677,21 @@ Each retry prints a notice on stderr.
 
 ## Changelog
 
+- **0.18.0** (2026-11-01) — `theme dev` local draft browsing (needs a platform that speaks browse contract 2).
+  - The local view renders only a draft: `--instance`, the saved theme work or the draft the sync
+    wrote to. Without one it no longer falls back to the live theme: no render request is sent and the
+    page says why ("Tema hedefi hazırlanamadı"). `--no-sync` now needs `--instance`.
+  - Pages are requested with `mode: "browse"`, the raw query string and the local address; the answer
+    is accepted only when it is contract 2 for the same draft. An older platform's answer is shown as
+    "Platform sürümü yerel taslak gezinmeyi desteklemiyor", never as the draft. Platform refusals show
+    their code and keep their HTTP status; a 404 stays a 404.
+  - Links, form actions, `formaction`, meta refresh and `rel=alternate` links to the site's own
+    addresses (also `//host/…`) are rewritten to the local address; `javascript:`/`data:`/userinfo and
+    malformed URLs on those attributes are removed. Assets and canonical are left alone.
+  - Every HTML answer carries `Content-Security-Policy: form-action 'self'; connect-src 'self';
+    base-uri 'none'`, `Referrer-Policy: no-referrer`, `X-Content-Type-Options: nosniff` and
+    `Cache-Control: no-store`; a form submission gets a `405` page saying forms are not sent locally.
+    JavaScript-driven navigation and image/frame requests are not contained (see "Known limits").
 - **0.17.1** (2026-11-01) — Security fix: `theme dev` answers this machine only.
   - The local server listens on IPv4 loopback (`127.0.0.1`) instead of every network interface, and
     prints that address. There is no option to open it to the network.
@@ -920,9 +986,10 @@ Each retry prints a notice on stderr.
 ## How it works
 
 `theme dev` starts a local HTTP server. For each page request it reads your local theme
-files and sends them to the platform's dev-render endpoint (`/api/dev/render`). The platform
-renders them with the site's **live data** and returns HTML — so the CLI ships no rendering
-engine and you see exactly the production output.
+files and sends them, with the draft theme's handle, to the platform's dev-render endpoint
+(`/api/dev/render`, `mode: "browse"`). The platform renders them with that draft's **saved
+content** and returns HTML — so the CLI ships no rendering engine. The CLI maps the site's own
+links to the local address and adds the reload script.
 
 It also continuously syncs your local files to a **draft theme**, so the same work can be opened
 in the admin theme editor without affecting your published theme. Save a file and the local view

package/bin/blocofy.mjs

@@ -5,8 +5,8 @@
  *
  * `blocofy login` stores your platform URL + dev token, then `blocofy theme dev`
  * starts a local server that proxies each request to the platform's
- * `/api/dev/render` endpoint (local theme files + live data) with file-watch
- * livereload. No monorepo required.
+ * `/api/dev/render` endpoint (local theme files + the draft's saved content,
+ * local draft browsing) with file-watch livereload. No monorepo required.
  */
 import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -219,18 +219,20 @@ Usage
       Show which site a command in [dir] would hit (verified), without writing anything.
 
   blocofy theme dev [dir] [--port <n>] [--no-sync] [--name <name>] [--instance <handle>]
-      Start a local dev server that renders your local theme files with the site's
-      live content. Press l to open it, q to quit. Edit a file and save → the view
-      reloads. Saves sync to a DRAFT theme only (never the live site). (dir defaults to cwd)
+      Start a local dev server that shows a DRAFT theme with your local theme files and
+      the draft's saved content; menus, pages, entries and languages stay on the local
+      address (never the live theme). Press l to open it, q to quit. Edit a file and save →
+      the view reloads. Saves sync to a DRAFT theme only (never the live site). Forms are not
+      sent from the local view. (dir defaults to cwd)
       The platform's remote preview and editor views for this command are retired; to
       share a draft page, create a preview link for it (v1 API / MCP create_preview_link).
       The target site is verified ONCE at start; a long session keeps that target (restart
       it after changing credentials, context or the project binding).
         --port <n>   local port (default 3030)
-        --no-sync    local preview only (skip draft sync)
+        --no-sync    skip draft sync; needs --instance <draft-handle> (no draft = no preview)
         --name <name>  name the draft when it is first created (ignored if it already exists)
-        --instance <handle>  sync into this draft (when the platform cannot tell which draft is
-                             the CLI draft it refuses and asks for this; never the live theme)
+        --instance <handle>  sync into and show this draft (when the platform cannot tell which
+                             draft is the CLI draft it refuses and asks for this; never the live theme)
 
   blocofy theme pull [dir] [--draft] [--instance <handle>]
       Download the live theme to disk. (dir defaults to cwd)
@@ -2577,7 +2579,7 @@ async function themeDev(rest) {
   // sync never writes the live theme, so the live theme's handle is refused here.
   const devInstance = typeof flags.instance === "string" ? flags.instance : savedInstance;
   if (devInstance && instanceMaybeLive(devInstance, target.identity?.liveThemeId ?? null)) {
-    console.error(`✗ ${devInstance} is (or could not be told apart from) the LIVE theme. 'theme dev' syncs to a draft only; pick a draft handle (\`blocofy status\`) or use --no-sync.`);
+    console.error(`✗ ${devInstance} is (or could not be told apart from) the LIVE theme. 'theme dev' shows and syncs a draft only; pick a draft handle (\`blocofy status\`).`);
     process.exit(2);
   }
 
@@ -2645,6 +2647,14 @@ async function themeDev(rest) {
     console.log(`  Watching ${themeDir} — ${fileCount} theme files\n`);
   }
 
+  // Local draft browsing: no draft handle → the local view renders nothing (never the live theme).
+  if (noSync && !devInstance) {
+    console.warn(
+      "  ⚠ --no-sync without --instance: there is no draft to show, so the local view only explains that.\n" +
+        "    Pass the draft to preview: blocofy theme dev --no-sync --instance <draft-handle> (handles: blocofy status)\n",
+    );
+  }
+
   if (flags.dry) {
     console.log("(--dry: server not started)");
     return;

package/lib/browse-html.mjs

@@ -0,0 +1,323 @@
+/**
+ * Local draft browsing (theme dev, contract 2): navigation-link mapping on the HTML the platform returns.
+ *
+ * A narrow HTML start-tag tokenizer (no dependency) finds the navigation surfaces — `a[href]`, `area[href]`,
+ * `form[action]`, `button[formaction]`, `input[formaction]`, `meta[http-equiv=refresh]` content URL and
+ * `link[rel~=alternate][href]` — and classifies each URL:
+ *   - its origin is one of the site's `internalOrigins` (also a protocol-relative `//host/…`) → rewritten to the
+ *     local origin, path + query + hash kept;
+ *   - `javascript:` / `data:` / `vbscript:`, userinfo (`https://u@host`), a malformed URL or a character reference
+ *     this tokenizer does not know → the attribute is removed and `data-blocofy-blocked="<attribute>"` is left;
+ *   - anything else (relative, external, `mailto:`…) → unchanged.
+ * Assets (img/src, srcset, script src, stylesheets, iframes) and `link[rel=canonical]` (public identity, PM decision 5)
+ * are never touched. This mapping is navigation convenience only: side-effect containment is the CSP response header
+ * set by the dev server, not this rewrite.
+ */
+
+const RAW_TEXT = new Set(["script", "style", "xmp", "iframe", "noembed", "noframes", "noscript", "textarea", "title"]);
+const BLOCKED_SCHEMES = new Set(["javascript:", "data:", "vbscript:"]);
+const isWs = (c) => c === " " || c === "\t" || c === "\n" || c === "\f" || c === "\r";
+const isAlpha = (c) => (c >= "a" && c <= "z") || (c >= "A" && c <= "Z");
+
+/**
+ * Parse the start (or end) tag whose name begins at `p`. Returns { name, attrs, end } or null at EOF (an unfinished tag
+ * is not emitted by a browser either). Each attribute: { name, raw, start, end } — `raw` is the undecoded value,
+ * `start..end` the whole attribute (name through value) in `html`.
+ */
+function parseTag(html, p) {
+  const n = html.length;
+  let j = p;
+  while (j < n && !isWs(html[j]) && html[j] !== "/" && html[j] !== ">") j++;
+  const name = html.slice(p, j).toLowerCase();
+  const attrs = [];
+  for (;;) {
+    while (j < n && (isWs(html[j]) || html[j] === "/")) j++;
+    if (j >= n) return null;
+    if (html[j] === ">") return { name, attrs, end: j + 1 };
+    const start = j;
+    j++; // the first character of a name may be "=" (spec: part of the name)
+    while (j < n && !isWs(html[j]) && html[j] !== "/" && html[j] !== ">" && html[j] !== "=") j++;
+    const attrName = html.slice(start, j).toLowerCase();
+    let k = j;
+    while (k < n && isWs(html[k])) k++;
+    if (html[k] !== "=") {
+      attrs.push({ name: attrName, raw: "", start, end: j });
+      continue;
+    }
+    k++;
+    while (k < n && isWs(html[k])) k++;
+    if (k >= n) return null;
+    const q = html[k];
+    if (q === '"' || q === "'") {
+      const close = html.indexOf(q, k + 1);
+      if (close < 0) return null;
+      attrs.push({ name: attrName, raw: html.slice(k + 1, close), start, end: close + 1 });
+      j = close + 1;
+    } else if (q === ">") {
+      attrs.push({ name: attrName, raw: "", start, end: k });
+      j = k;
+    } else {
+      let e = k;
+      while (e < n && !isWs(html[e]) && html[e] !== ">") e++;
+      attrs.push({ name: attrName, raw: html.slice(k, e), start, end: e });
+      j = e;
+    }
+  }
+}
+
+/** Index of the `</name` end tag (followed by whitespace, "/" or ">") from `from`, case-insensitive; else EOF. */
+function rawTextEnd(html, from, name) {
+  let i = from;
+  for (;;) {
+    const lt = html.indexOf("</", i);
+    if (lt < 0) return html.length;
+    const after = html[lt + 2 + name.length];
+    if (
+      html.slice(lt + 2, lt + 2 + name.length).toLowerCase() === name &&
+      (after === undefined || isWs(after) || after === "/" || after === ">")
+    ) {
+      return lt;
+    }
+    i = lt + 2;
+  }
+}
+
+/**
+ * Every start tag in `html`, in document order: { name, attrs, start, end }. Comments, doctype/bogus comments, end
+ * tags and the content of raw-text/RCDATA elements (script, style, textarea, title, noscript, iframe, xmp, noembed,
+ * noframes) are skipped; `<template>` content is markup and is scanned.
+ */
+export function startTags(html) {
+  const tags = [];
+  const n = html.length;
+  let i = 0;
+  while (i < n) {
+    const lt = html.indexOf("<", i);
+    if (lt < 0) break;
+    const next = html[lt + 1];
+    if (html.startsWith("<!--", lt)) {
+      const body = lt + 4;
+      if (html[body] === ">") {
+        i = body + 1;
+        continue;
+      }
+      if (html.startsWith("->", body)) {
+        i = body + 2;
+        continue;
+      }
+      const a = html.indexOf("-->", body);
+      const b = html.indexOf("--!>", body);
+      const ends = [a < 0 ? Infinity : a + 3, b < 0 ? Infinity : b + 4];
+      const end = Math.min(...ends);
+      if (end === Infinity) break;
+      i = end;
+      continue;
+    }
+    if (next === "!" || next === "?") {
+      const gt = html.indexOf(">", lt + 2);
+      if (gt < 0) break;
+      i = gt + 1;
+      continue;
+    }
+    if (next === "/") {
+      if (isAlpha(html[lt + 2] ?? "")) {
+        const endTag = parseTag(html, lt + 2);
+        if (!endTag) break;
+        i = endTag.end;
+        continue;
+      }
+      const gt = html.indexOf(">", lt + 2);
+      if (gt < 0) break;
+      i = gt + 1;
+      continue;
+    }
+    if (isAlpha(next ?? "")) {
+      const tag = parseTag(html, lt + 1);
+      if (!tag) break;
+      tags.push({ ...tag, start: lt });
+      i = tag.end;
+      if (tag.name === "plaintext") break;
+      if (RAW_TEXT.has(tag.name)) i = rawTextEnd(html, i, tag.name);
+      continue;
+    }
+    i = lt + 1;
+  }
+  return tags;
+}
+
+// Character references that can change how a URL is classified (ASCII punctuation, tab/newline) + the common ones.
+// A named reference not listed here makes the value "malformed" (fail-closed), never silently literal.
+const NAMED = {
+  amp: "&", AMP: "&", lt: "<", LT: "<", gt: ">", GT: ">", quot: '"', QUOT: '"', apos: "'",
+  colon: ":", sol: "/", bsol: "\\", period: ".", quest: "?", num: "#", commat: "@", percnt: "%",
+  equals: "=", excl: "!", dollar: "$", lpar: "(", rpar: ")", ast: "*", midast: "*", plus: "+",
+  comma: ",", semi: ";", lsqb: "[", lbrack: "[", rsqb: "]", rbrack: "]", lowbar: "_", UnderBar: "_",
+  grave: "`", DiacriticalGrave: "`", lcub: "{", lbrace: "{", rcub: "}", rbrace: "}", verbar: "|",
+  vert: "|", VerticalLine: "|", Hat: "^", Tab: "\t", NewLine: "\n", nbsp: " ",
+};
+// Legacy names a browser also decodes without ";" (in an attribute only when not followed by [A-Za-z0-9=]).
+const LEGACY = new Set(["amp", "AMP", "lt", "LT", "gt", "GT", "quot", "QUOT", "nbsp"]);
+
+/** Decode an attribute value's character references. { text, unknown } — `unknown` = a reference we cannot decode. */
+export function decodeAttr(raw) {
+  let unknown = false;
+  const text = raw.replace(/&(#[xX][0-9a-fA-F]+;?|#[0-9]+;?|[A-Za-z][A-Za-z0-9]*;?)/g, (whole, ref, offset) => {
+    if (ref[0] === "#") {
+      const hex = ref[1] === "x" || ref[1] === "X";
+      const digits = ref.slice(hex ? 2 : 1).replace(/;$/, "");
+      const cp = parseInt(digits, hex ? 16 : 10);
+      if (!cp || cp > 0x10ffff || (cp >= 0xd800 && cp <= 0xdfff)) return "�";
+      return String.fromCodePoint(cp);
+    }
+    if (ref.endsWith(";")) {
+      const name = ref.slice(0, -1);
+      if (Object.hasOwn(NAMED, name)) return NAMED[name];
+      unknown = true;
+      return whole;
+    }
+    const nextChar = raw[offset + whole.length] ?? "";
+    if (LEGACY.has(ref) && !/[A-Za-z0-9=]/.test(nextChar)) return NAMED[ref];
+    return whole; // `?a=1&b=2`: not a reference
+  });
+  return { text, unknown };
+}
+
+const escapeAttr = (value) => value.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+
+/**
+ * Classify one navigation URL. → { action: "keep" } | { action: "rewrite", value } | { action: "block", reason }.
+ * `pageUrl` is the local page URL (http); a protocol-relative value is also resolved over https so `//host/x` of an
+ * internal https origin is recognised.
+ */
+export function classifyNavigationUrl(raw, { pageUrl, internal, localOrigin }) {
+  const { text, unknown } = decodeAttr(raw);
+  if (unknown) return { action: "block", reason: "malformed" };
+  let viaHttp;
+  let viaHttps;
+  try {
+    viaHttp = new URL(text, pageUrl);
+    const httpsBase = new URL(pageUrl);
+    httpsBase.protocol = "https:";
+    viaHttps = new URL(text, httpsBase);
+  } catch {
+    return { action: "block", reason: "malformed" };
+  }
+  if (BLOCKED_SCHEMES.has(viaHttp.protocol)) return { action: "block", reason: viaHttp.protocol.slice(0, -1) };
+  if (viaHttp.username || viaHttp.password) return { action: "block", reason: "userinfo" };
+  const hit = internal.has(viaHttp.origin) ? viaHttp : internal.has(viaHttps.origin) ? viaHttps : null;
+  if (hit) return { action: "rewrite", value: `${localOrigin}${hit.pathname}${hit.search}${hit.hash}` };
+  return { action: "keep" };
+}
+
+/** `<delay>[;,] url=<url>` → { delay, url } (HTML "shared declarative refresh steps"); url null when absent/invalid. */
+export function parseRefresh(content) {
+  let i = 0;
+  const s = content;
+  while (i < s.length && isWs(s[i])) i++;
+  const delayStart = i;
+  while (i < s.length && /[0-9.]/.test(s[i])) i++;
+  if (i === delayStart) return null;
+  const delay = s.slice(delayStart, i);
+  if (i >= s.length) return { delay, url: null };
+  if (!isWs(s[i]) && s[i] !== ";" && s[i] !== ",") return null;
+  while (i < s.length && isWs(s[i])) i++;
+  if (s[i] === ";" || s[i] === ",") i++;
+  while (i < s.length && isWs(s[i])) i++;
+  if (i >= s.length) return { delay, url: null };
+  if (s.slice(i, i + 3).toLowerCase() === "url") {
+    let j = i + 3;
+    while (j < s.length && isWs(s[j])) j++;
+    if (s[j] === "=") {
+      j++;
+      while (j < s.length && isWs(s[j])) j++;
+      i = j;
+    }
+  }
+  let url = s.slice(i);
+  if (url[0] === '"' || url[0] === "'") {
+    const close = url.indexOf(url[0], 1);
+    url = close < 0 ? url.slice(1) : url.slice(1, close);
+  }
+  return { delay, url };
+}
+
+const relTokens = (attr) => (attr ? decodeAttr(attr.raw).text.toLowerCase().split(/[\t\n\f\r ]+/).filter(Boolean) : []);
+
+/** Which attribute of this tag is a navigation URL (null when the tag is not a navigation surface). */
+function navigationAttribute(name, first) {
+  switch (name) {
+    case "a":
+      return first.has("href") ? "href" : first.has("xlink:href") ? "xlink:href" : null;
+    case "area":
+      return "href";
+    case "form":
+      return "action";
+    case "button":
+    case "input":
+      return "formaction";
+    case "link": {
+      const rel = relTokens(first.get("rel"));
+      // canonical = public identity (PM decision 5): kept at the site's authority. `alternate stylesheet` is an asset.
+      if (!rel.includes("alternate") || rel.includes("canonical") || rel.includes("stylesheet")) return null;
+      return "href";
+    }
+    case "meta":
+      return decodeAttr(first.get("http-equiv")?.raw ?? "").text.trim().toLowerCase() === "refresh" ? "content" : null;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Rewrite the navigation surfaces of `html` (see the module comment). Returns { html, rewritten, blocked }.
+ * `internalOrigins` must already be validated origins; `localOrigin` is `http://127.0.0.1:<port>`.
+ */
+export function rewriteNavigation(html, { pageUrl, internalOrigins, localOrigin }) {
+  const internal = new Set(internalOrigins);
+  const ctx = { pageUrl, internal, localOrigin };
+  const edits = [];
+  let rewritten = 0;
+  let blocked = 0;
+  for (const tag of startTags(html)) {
+    // A browser keeps the FIRST of duplicate attributes; later ones are inert — and removed when the first is edited,
+    // so an edit never promotes an ignored duplicate.
+    const first = new Map();
+    for (const attr of tag.attrs) if (!first.has(attr.name)) first.set(attr.name, attr);
+    const attrName = navigationAttribute(tag.name, first);
+    const attr = attrName && first.get(attrName);
+    if (!attr || attr.raw === "") continue;
+
+    let result;
+    let refresh = null;
+    if (tag.name === "meta") {
+      const content = decodeAttr(attr.raw);
+      refresh = parseRefresh(content.text);
+      if (!refresh || refresh.url === null) continue;
+      // The URL was already decoded with the content attribute; re-escape `&` so it is not decoded twice.
+      result = content.unknown
+        ? { action: "block", reason: "malformed" }
+        : classifyNavigationUrl(refresh.url.replace(/&/g, "&amp;"), ctx);
+    } else {
+      result = classifyNavigationUrl(attr.raw, ctx);
+    }
+    if (result.action === "keep") continue;
+
+    const dropDuplicates = () => {
+      for (const other of tag.attrs) if (other !== attr && other.name === attr.name) edits.push({ start: other.start, end: other.end, text: "" });
+    };
+    if (result.action === "block") {
+      blocked++;
+      edits.push({ start: attr.start, end: attr.end, text: `data-blocofy-blocked="${escapeAttr(attrName)}"` });
+    } else {
+      rewritten++;
+      const value = refresh ? `${refresh.delay};url=${result.value}` : result.value;
+      edits.push({ start: attr.start, end: attr.end, text: `${attrName}="${escapeAttr(value)}"` });
+    }
+    dropDuplicates();
+  }
+  if (edits.length === 0) return { html, rewritten, blocked };
+  edits.sort((x, y) => y.start - x.start);
+  let out = html;
+  for (const edit of edits) out = out.slice(0, edit.start) + edit.text + out.slice(edit.end);
+  return { html: out, rewritten, blocked };
+}

package/lib/dev-server.mjs

@@ -9,6 +9,7 @@ import {
   injectLivereload,
   readLocalTemplates,
 } from "./local-theme.mjs";
+import { rewriteNavigation } from "./browse-html.mjs";
 import { DRAFT_TARGET_AMBIGUOUS, draftSyncErrorLine, pushTheme } from "./theme-sync.mjs";
 
 /**
@@ -49,13 +50,77 @@ function refusal(req, port) {
 }
 
 /**
- * Standalone dev server. For each page request it reads the local theme files and
- * posts them to the platform's `/api/dev/render` endpoint, then injects a livereload
- * script into the returned HTML. `fs.watch` reloads the browser over SSE on change.
+ * Local draft browsing (contract 2) response headers on every HTML answer of this server. The CSP is an HTTP header,
+ * not a `<meta>`, so a theme cannot remove it (a theme's own meta CSP still applies too — the stricter wins):
+ *   - `form-action 'self'`: every form submission (action, formaction, formtarget/new window) can only go to this
+ *     server, which answers 405 for anything but GET/HEAD; a GET form becomes a local read-only page request;
+ *   - `connect-src 'self'`: fetch / XHR / sendBeacon / WebSocket / EventSource / `<a ping>` to the live site or a third
+ *     party are blocked (the livereload EventSource is same-origin and keeps working);
+ *   - `base-uri 'none'`: a theme `<base href>` cannot re-target relative links to the live site.
+ * script/style/img/frame/font sources are deliberately NOT restricted: theme menus, sliders and embeds keep working.
+ */
+export const BROWSE_CSP = "form-action 'self'; connect-src 'self'; base-uri 'none'";
+const HTML_HEADERS = {
+  "content-type": "text/html; charset=utf-8",
+  "cache-control": "no-store",
+  "content-security-policy": BROWSE_CSP,
+  "referrer-policy": "no-referrer",
+  "x-content-type-options": "nosniff",
+};
+
+/** The browse contract version this CLI speaks (platform `POST /api/dev/render` with `mode: "browse"`). */
+export const BROWSE_CONTRACT = 2;
+
+const isLocalDevHost = (hostname) =>
+  hostname === "localhost" || hostname.endsWith(".localhost") || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname);
+
+/** An internal origin: canonical `https://host[:port]`, or `http://` only for a local development host (fixture stack). */
+function validOrigin(value) {
+  if (typeof value !== "string") return false;
+  try {
+    const u = new URL(value);
+    if (u.origin !== value) return false;
+    return u.protocol === "https:" || (u.protocol === "http:" && isLocalDevHost(u.hostname));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Strict contract-2 check of a `/api/dev/render` browse answer. → { ok: true, status, html, internalOrigins, diagnosis }
+ * or { ok: false, why }. An old platform's `{ html }` (or any other shape) is never served as a browsable draft.
+ */
+export function validateBrowseResponse(httpStatus, body, sentInstance) {
+  if (httpStatus !== 200 && httpStatus !== 404) return { ok: false, why: `HTTP ${httpStatus}` };
+  if (!body || typeof body !== "object" || Array.isArray(body)) return { ok: false, why: "JSON nesnesi değil" };
+  if (body.contract !== BROWSE_CONTRACT) return { ok: false, why: `contract ${JSON.stringify(body.contract ?? null)}` };
+  if (body.status !== httpStatus) return { ok: false, why: "status HTTP durumuyla eşleşmiyor" };
+  if (!body.target || typeof body.target !== "object" || body.target.instance !== sentInstance) {
+    return { ok: false, why: "target.instance gönderilen taslakla eşleşmiyor" };
+  }
+  if (typeof body.html !== "string") return { ok: false, why: "html dizgi değil" };
+  if (!Array.isArray(body.internalOrigins) || !body.internalOrigins.every(validOrigin)) {
+    return { ok: false, why: "internalOrigins geçersiz" };
+  }
+  const d = body.diagnosis;
+  const diagnosis =
+    d && typeof d === "object" && typeof d.code === "string"
+      ? { code: d.code.slice(0, 64), location: typeof d.location === "string" ? d.location.slice(0, 2048) : null }
+      : null;
+  return { ok: true, status: httpStatus, html: body.html, internalOrigins: body.internalOrigins, diagnosis };
+}
+
+/**
+ * Standalone dev server — local draft browsing. For each page request it reads the local theme files and posts them
+ * with the draft theme handle to the platform's `/api/dev/render` (`mode: "browse"`), validates the contract-2 answer,
+ * maps the site's own links to this local origin, and injects a livereload script. `fs.watch` reloads the browser over
+ * SSE on change.
  *
- * Assets are usually inlined into the HTML via `{% render 'asset/x.css' %}` (no
- * separate request); direct `/asset/*` references are served from disk. Images/JS
- * are remote (Directus/CDN), so no local serving is needed for them.
+ * No draft handle → no render request at all (a local terminal error page; never the live theme). The handle is
+ * `instance` (theme dev --instance, or the saved theme work) or the one the startup draft sync returns.
+ *
+ * Assets are usually inlined into the HTML via `{% render 'asset/x.css' %}` (no separate request); direct `/asset/*`
+ * references are served from disk. Images come from the site's system host (`/cdn`), not through this server.
  */
 export function startDevServer({ dir, url, token, port, syncDraft = false, instance = null, onError, onReload, onRetry, onWarn, onSyncRefused }) {
   const base = url.replace(/\/+$/, "");
@@ -63,28 +128,31 @@ export function startDevServer({ dir, url, token, port, syncDraft = false, insta
   const bearer = async () => (typeof token === "function" ? await token() : token);
   const clients = new Set();
 
-  // Taslak instance handle'ı: `pushTheme({draft:true})` yanıtından gelir (ek istek YOK). Render
-  // istekleri bunu taşıyınca platform CANLI sayfa belgeleri yerine TASLAĞIN sayfa belgelerini
-  // çözer — `theme dev`'in yerel görünümü nihayet üzerinde çalışılan şeyi gösterir.
-  let draftInstance = null;
-  // Kanonik yazma yolu ham control-plane JSON'u döndürür ve `instanceId` içermeyebilir. O durumda
-  // sessizce canlıya dönmek, bu onarımın kapattığı arıza sınıfının aynısı olurdu — bir kez uyar.
+  // The draft the local view shows. `--instance` (or the saved theme work) is fixed for the session; otherwise the
+  // handle comes from the draft sync answer (`pushTheme({draft:true})`, no extra request).
+  let draftInstance = instance ? String(instance) : null;
+  // Why there is no handle (shown on the local error page; no render is requested without one).
+  let noHandleReason = syncDraft
+    ? "Taslak senkronu henüz bitmedi."
+    : "--no-sync ile --instance <taslak-handle> verilmedi; yerel önizleme canlı temayı göstermez.";
   let warnedNoHandle = false;
   const noteHandle = (pushed) => {
+    if (instance) return;
     if (pushed?.instanceId) {
-      draftInstance = pushed.instanceId;
+      draftInstance = String(pushed.instanceId);
       return;
     }
+    noHandleReason = "Platform taslak senkronundan sonra bir taslak tema handle'ı döndürmedi.";
     if (!warnedNoHandle) {
       warnedNoHandle = true;
       onWarn?.(
-        "the server did not return a draft theme handle — local preview will render LIVE page content, not your draft.",
+        "the server did not return a draft theme handle — the local view cannot show your draft (it never falls back to live); pass --instance <draft-handle>.",
       );
     }
   };
 
   // Açılıştaki push'u BİR promise olarak tut: ilk render isteği bunu bekler, yoksa ilk sayfa
-  // yüklemesi canlı içerikle gelir ve geliştirici "taslağım görünmüyor" sanır.
+  // yüklemesi senkron bitmeden gelir ve geliştirici "taslağım görünmüyor" sanır.
   // #989: `instance` (theme dev --instance) syncs into that draft; otherwise the platform picks the CLI draft and
   // refuses (409 draft_target_ambiguous) when it cannot prove which one that is. A refusal is final for the session:
   // `onSyncRefused` is told once (the caller exits) — the sync is never retried in a loop.
@@ -105,57 +173,94 @@ export function startDevServer({ dir, url, token, port, syncDraft = false, insta
         .then(noteHandle)
         .catch((err) => {
           // #989 re-review P3: a startup sync failure is said, in one line — never swallowed.
-          if (!refusedBy(err)) onWarn?.(draftSyncErrorLine(err));
+          if (!refusedBy(err)) {
+            const line = draftSyncErrorLine(err);
+            noHandleReason = line;
+            onWarn?.(line);
+          }
         })
     : Promise.resolve();
 
-  async function renderPath(pathname) {
+  /** One page through the browse contract. → { status, html } (html is complete; livereload not yet injected). */
+  async function renderPage(pathname, search, localOrigin) {
     // Açılış push'u bitene kadar bekle — yalnız ilk istekte gerçekten bekler, sonra çözülmüş promise.
-    if (!draftInstance) await draftReady;
+    await draftReady;
+    if (!draftInstance) {
+      return {
+        status: 503,
+        html: localPage({
+          title: "Tema hedefi hazırlanamadı",
+          lines: [
+            "Yerel önizleme yalnız bir taslak temayı gösterir. Hangi taslağın gösterileceği belirlenemediği için platformdan sayfa istenmedi; canlı siteye de geçilmedi.",
+          ],
+          detail: noHandleReason,
+          hint: "Terminaldeki mesaja bakın. Bir taslak seçmek için: blocofy theme dev --instance <taslak-handle> (handle'lar: blocofy status).",
+        }),
+      };
+    }
+    const sent = draftInstance;
     const templates = readLocalTemplates(dir);
     const res = await fetch(`${base}/api/dev/render`, {
       method: "POST",
       headers: { "content-type": "application/json", authorization: `Bearer ${await bearer()}` },
-      // `preview` BİLİNÇLE gönderilmez: sunucuda preview yalnız tazelik değil — önizleme bandı,
-      // editör bridge'i ve blok işaretleyicileri de ona bağlı. `theme dev`'in vaadi prod paritesi.
       body: JSON.stringify({
+        mode: "browse",
         path: pathname,
         templates,
-        ...(draftInstance ? { instance: draftInstance } : {}),
+        instance: sent,
+        ...(search ? { search } : {}),
+        localOrigin,
       }),
     });
     const text = await res.text();
-    if (!res.ok) {
-      let message = text;
-      try {
-        message = JSON.parse(text).error ?? text;
-      } catch {
-        /* raw text */
-      }
-      return { status: res.status, html: errorHtml(res.status, message) };
-    }
+    let body = null;
     try {
-      return { status: 200, html: JSON.parse(text).html ?? "" };
+      body = JSON.parse(text);
     } catch {
-      return { status: 200, html: text };
+      /* not JSON */
+    }
+    if (res.status !== 200 && res.status !== 404) return { status: res.status, html: refusalPage(res.status, body, text) };
+    const checked = validateBrowseResponse(res.status, body, sent);
+    if (!checked.ok) {
+      // A 404 with a typed error body (e.g. instance_not_found) is a refusal, not a contract-2 page.
+      if (res.status === 404 && body?.error) return { status: 404, html: refusalPage(404, body, text) };
+      return {
+        status: 502,
+        html: localPage({
+          title: "Platform sürümü yerel taslak gezinmeyi desteklemiyor",
+          lines: [
+            `Platformun yanıtı yerel taslak gezinme sözleşmesine (contract ${BROWSE_CONTRACT}) uymuyor; bu yanıt taslağınız diye gösterilmedi.`,
+            "Platform güncellenene kadar bu CLI sürümüyle yerel önizleme kullanılamaz.",
+          ],
+          detail: `Uyumsuzluk: ${checked.why}`,
+        }),
+      };
     }
+    const pageUrl = `${localOrigin}${pathname}${search}`;
+    let html = rewriteNavigation(checked.html, { pageUrl, internalOrigins: checked.internalOrigins, localOrigin }).html;
+    if (checked.status === 404) html = injectBeforeBodyEnd(html, notFoundNote(checked.diagnosis));
+    return { status: checked.status, html };
   }
 
   const server = createServer(async (req, res) => {
     // Before every branch: no SSE subscription, disk read or authenticated render for a refused request.
     const refused = refusal(req, server.address()?.port);
     if (refused) {
-      res.writeHead(refused.status, {
-        "content-type": "text/plain; charset=utf-8",
-        "cache-control": "no-store",
-        ...(refused.status === 405 ? { allow: ALLOWED_METHODS } : {}),
-      });
+      if (refused.status === 405) {
+        // Forms (POST/PUT/…) end here: CSP `form-action 'self'` keeps every submission on this server.
+        res.writeHead(405, { ...HTML_HEADERS, allow: ALLOWED_METHODS });
+        res.end(formsNotSentPage());
+        return;
+      }
+      res.writeHead(refused.status, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" });
       res.end(`${refused.reason}\n`);
       return;
     }
     const head = req.method === "HEAD";
     try {
-      const pathname = decodeURIComponent(new URL(req.url, "http://localhost").pathname);
+      // Origin-form request target (checked above): parse it as a path of this origin, never as an authority.
+      const target = new URL(`http://localhost${req.url}`);
+      const pathname = decodeURIComponent(target.pathname);
 
       // Livereload SSE channel — same-origin only (no CORS header): cross-origin views no longer subscribe.
       if (pathname === LIVERELOAD_PATH) {
@@ -181,17 +286,19 @@ export function startDevServer({ dir, url, token, port, syncDraft = false, insta
 
       // HEAD never spends an authenticated render: headers only.
       if (head) {
-        res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+        res.writeHead(200, HTML_HEADERS);
         res.end();
         return;
       }
 
-      // Page → render on the platform.
-      const { status, html } = await renderPath(pathname);
-      res.writeHead(status, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+      // Page → render the draft on the platform. The raw (still percent-encoded) path and query go as they are: the
+      // platform decodes once. The hash never reaches a server.
+      const localOrigin = `http://${DEV_SERVER_HOST}:${server.address().port}`;
+      const { status, html } = await renderPage(target.pathname, target.search, localOrigin);
+      res.writeHead(status, HTML_HEADERS);
       res.end(injectLivereload(html));
     } catch (err) {
-      res.writeHead(502, { "content-type": "text/html; charset=utf-8" });
+      res.writeHead(502, HTML_HEADERS);
       res.end(injectLivereload(errorHtml(502, err?.message ?? String(err))));
     }
   });
@@ -331,7 +438,64 @@ function safeAssetFile(dir, pathname) {
 }
 
 function escapeHtml(value) {
-  return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+function injectBeforeBodyEnd(html, snippet) {
+  const at = html.lastIndexOf("</body>");
+  return at < 0 ? html + snippet : html.slice(0, at) + snippet + html.slice(at);
+}
+
+/** A local page of this CLI (not the theme): title, paragraphs, an optional detail block and hint. */
+function localPage({ title, lines = [], detail = null, hint = null }) {
+  return (
+    `<!doctype html><html lang="tr"><head><meta charset="utf-8"><meta name="robots" content="noindex">` +
+    `<title>blocofy theme dev — ${escapeHtml(title)}</title></head>` +
+    `<body style="font-family:system-ui,sans-serif;padding:2rem;max-width:48rem;margin:0 auto;color:#18181b">` +
+    `<h1 style="color:#b91c1c;font-size:1.5rem">${escapeHtml(title)}</h1>` +
+    lines.map((line) => `<p>${escapeHtml(line)}</p>`).join("") +
+    (detail ? `<pre style="white-space:pre-wrap;background:#f4f4f5;padding:1rem;border-radius:.5rem;color:#333">${escapeHtml(detail)}</pre>` : "") +
+    (hint ? `<p style="color:#52525b">${escapeHtml(hint)}</p>` : "") +
+    `</body></html>`
+  );
+}
+
+/** The platform refused the browse request: its error code (new `{error:{code,message}}` or legacy shape), status kept. */
+function refusalPage(status, body, text) {
+  const error = body?.error;
+  const code = typeof error?.code === "string" ? error.code : typeof body?.code === "string" ? body.code : null;
+  const message =
+    typeof error?.message === "string" ? error.message : typeof error === "string" ? error : body ? "" : text.slice(0, 500);
+  return localPage({
+    title: "Platform bu sayfayı göstermeyi reddetti",
+    lines: [`HTTP ${status}${code ? ` · ${code}` : ""}`, ...(message ? [message] : [])],
+    hint:
+      code === "instance_is_live" || code === "instance_not_found" || code === "instance_required"
+        ? "Yerel önizleme yalnız bu sitenin bir taslak temasını gösterir; canlı temaya geçilmez. Bir taslak seçin: blocofy theme dev --instance <taslak-handle> (handle'lar: blocofy status)."
+        : "Bu sayfa kaydettiğinizde kendiliğinden yenilenir.",
+  });
+}
+
+/** A small CLI note on a 404 (the theme's own 404 HTML is otherwise left as is). */
+function notFoundNote(diagnosis) {
+  const parts = ["blocofy theme dev: 404"];
+  if (diagnosis?.code) parts.push(diagnosis.code);
+  if (diagnosis?.location) parts.push(`canlı sitede yönlendirilirdi: ${diagnosis.location} (yerel önizlemede yönlendirme uygulanmaz)`);
+  return (
+    `<blocofy-dev-note role="note" style="all:initial;position:fixed;bottom:8px;left:8px;z-index:2147483647;` +
+    `font:12px/1.4 system-ui,sans-serif;background:#18181b;color:#fafafa;padding:6px 10px;border-radius:6px;max-width:90vw">` +
+    `${escapeHtml(parts.join(" · "))}</blocofy-dev-note>`
+  );
+}
+
+/** The 405 answer for a form submission (any non-GET/HEAD request). */
+function formsNotSentPage() {
+  return localPage({
+    title: "Yerel önizlemede formlar gönderilmez",
+    lines: [
+      "Bu yerel sunucu yalnız sayfa gösterir (GET/HEAD). Bu form gönderimi canlı siteye ya da başka bir adrese iletilmedi.",
+    ],
+  });
 }
 
 function errorHtml(status, message) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocofy/cli",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Develop your Blocofy theme locally against live data with instant preview — login, theme dev, pull, push.",
   "type": "module",
   "license": "MIT",