npm - @charlescms/astro - Versions diffs - 0.1.0 → 0.2.1 - Mend

@charlescms/astro 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/README.md +72 -54
package/package.json +1 -1
package/scripts/setup.js +7 -1
package/src/admin.astro +118 -90
package/src/asset-images.js +2 -2
package/src/boot.js +0 -2
package/src/client.js +32 -19
package/src/connector-client.js +2 -1
package/src/content-panel.js +3 -6
package/src/element-editor.js +0 -19
package/src/index.js +117 -6
package/src/local-client.js +50 -0
package/src/publishing.js +10 -6
package/src/runtime-controller.js +10 -2
package/src/toolbar.js +10 -12

package/README.md CHANGED Viewed

@@ -8,31 +8,14 @@ Static-first visual editing for Astro sites. Free and open source (MIT).
 > [report anything that breaks](https://github.com/Charles-CMS/astro/issues).
 > APIs may change before 1.0.
-## Quickstart (≈2 minutes)
+## Quickstart — edit in 60 seconds
-Requires Node.js 22.12 or newer and Astro 6.2.
-Local preview needs no service account. To publish edits, you only need a GitHub
-repository and a Cloudflare account; the connector is designed to fit within the
-Cloudflare Workers free tier for typical small-site use.
+Requires Node.js 22.12 or newer and Astro 6.2. **No account, no service, no config.**
 ```bash
 npm install @charlescms/astro
 ```
-Astro 6 currently permits an `esbuild` release affected by June 2026 security
-advisories. Until Astro/Vite require the patched release themselves, pin it in
-the consuming site's root `package.json`, reinstall, and verify with
-`npm audit --omit=dev`:
-```json
-{
-  "overrides": {
-    "esbuild": "^0.28.1"
-  }
-}
-```
 ```js
 // astro.config.mjs
 import { defineConfig } from "astro/config";
@@ -45,44 +28,64 @@ export default defineConfig({ integrations: [charlesCMS()] });
 npm run dev
 ```
-Open **`/cms`**, then click any text or image on the page to edit it. That's the
-whole setup — no schema, no content models, no config.
-Edits are a local preview until you connect the connector (below) — then
-**Publish** commits them straight to your Git repo.
+Open **`/cms`**, click **Start editing locally**, then click any text or image on
+the page to change it. No schema, no content models, no setup.
-## Publish your edits
-To go live, deploy the connector — a small Cloudflare Worker that commits edits to
-GitHub. One command walks you through it (GitHub repo, where you'll edit, Worker
-name, branch, and an editor password):
+In `npm run dev` your changes are written **straight to your real source files** —
+`src/pages/index.astro`, your Markdown, your data — byte-for-byte and conservative
+by design. Press **Save to local files**, then commit with your own Git when you're
+happy:
 ```bash
-npx charlescms setup --deploy
+git add -A && git commit -m "Edit copy in CharlesCMS"
 ```
-Then **connect the site to it once on `/cms`** — paste the connector URL and the
-browser remembers it. No config editing needed.
+That's the whole loop: **click → edit → Save → `git commit`**. No GitHub App, no
+Cloudflare, nothing to deploy — this alone is a complete local visual editor.
-> **Optional:** to skip even that form, bake the connection into `astro.config` so
-> editors land straight on **Start editing**:
->
-> ```js
-> charlesCMS({
->   connector: "https://<your-worker>.workers.dev",
->   repo: "owner/name",
->   branch: "main",
-> })
-> ```
+> Want non-technical people to edit the **live** site themselves (no local checkout,
+> no Git)? That's the optional connector below — about two more minutes.
-Verify anytime:
+## Publish from your live site (optional)
-```bash
-npx charlescms doctor https://<your-worker>.workers.dev
-```
+> **This deploys the _connector_, not your website.** Your site stays hosted wherever you
+> already put it (Vercel, Netlify, Cloudflare Pages, GitHub Pages…). The connector is a
+> tiny *extra* Cloudflare Worker whose only job is to commit editors' changes to GitHub —
+> then your existing host rebuilds the site as usual. The loop is:
+> **edit in `/cms` → connector commits to GitHub → your host redeploys → live.**
-No Wrangler install needed — `npx` fetches it. Prefer clicking or no CLI? See
-[Manual setup](#manual-setup).
+Local editing needs nothing. To let people edit your **live** site — each save committed
+to GitHub for you — deploy that connector. You need a **GitHub repo** and a **free
+Cloudflare account** (it fits the Workers free tier). Nothing to install first — `npx`
+fetches the tools; just say yes if it offers to install one.
+**One-time setup (~5 min).** Do it in this order so you never have to come back:
+1. Put your site in a GitHub repo and **deploy it** to your host (push → it builds; any
+   host works — see [Deploy your site](#deploy-your-site)). You now have your site's URL.
+2. `npx wrangler login` — opens a browser to sign in to Cloudflare.
+3. `npx charlescms setup --deploy --open` — answer the prompts; when it asks for your
+   **live site URL**, paste the one from step 1 (and set an editor password). A browser
+   opens to **create the GitHub App** (click create); it then deploys the Worker and
+   prints your **connector URL**.
+4. Click the **install** link it prints, to add the GitHub App to your repo.
+5. On your live site, open `/cms` → **Connect a publisher** → paste the connector URL,
+   repo (`owner/name`), and password.
+Now **Edit → Publish → live** — each Publish commits to GitHub and your host rebuilds.
+Verify anytime: `npx charlescms doctor <connector-url>`.
+> **Not deployed yet?** You can still set up the connector — leave the live-site URL blank,
+> finish, then add it later by re-running `npx charlescms setup --deploy` once your site is
+> live (it remembers your answers). Deploying first just saves that second trip.
+> **Skip the form:** bake the connection into `astro.config` so editors land straight on
+> **Start editing** (only the password is asked):
+> ```js
+> charlesCMS({ connector: "https://<worker>.workers.dev", repo: "owner/name", branch: "main" })
+> ```
+Prefer clicking / no CLI? See [Manual setup](#manual-setup).
 ### CLI reference
@@ -243,7 +246,6 @@ charlesCMS({
   sourceRoot: "website",             // monorepos only
   editablePaths: ["/demo", "/blog"], // limit where the editor activates
-  previewOnly: false,                // true = local preview only, no publishing
   adminPath: "/cms",                 // change the editor route
 })
 ```
@@ -310,11 +312,27 @@ Skip the assistant and set up the Worker by hand:
 ## How it works & safety
 The editor ships as static HTML/JS, reads a build-time source map, and stages edits
-as a live preview. Publish sends the exact source span to the Worker, which commits
-to GitHub — credentials stay in the Worker, never in the site or `localStorage`.
-Before each commit the file is re-read and the edit refused if the source changed;
-rich text and section HTML are re-sanitized before the authenticated connector
-writes the complete updated file.
+as a live preview. In `npm run dev` with no connector, **Save** applies the edit to
+your local source file on disk through a dev-only endpoint — the same byte-verified
+transform, no network. With a connector, **Publish** sends the exact source span to
+the Worker, which commits to GitHub — credentials stay in the Worker, never in the
+site or `localStorage`. Either way the file is re-read first and the edit refused if
+the source changed, and rich text and section HTML are re-sanitized before the
+complete updated file is written.
+## esbuild dev-server pin (Windows only)
+A path-traversal advisory ([GHSA-g7r4-m6w7-qqqr](https://github.com/advisories/GHSA-g7r4-m6w7-qqqr))
+affects esbuild's **development server on Windows** in versions before `0.28.1`.
+It is dev-only and Windows-only — it does **not** affect your built or published
+site. Vite 7 still permits `esbuild@0.27.x`, so if you run `astro dev` on Windows,
+pin the patched release in your site's **root** `package.json` and reinstall:
+```json
+{ "overrides": { "esbuild": "^0.28.1" } }
+```
+You can drop this once your installed Vite requires `esbuild >= 0.28.1`.
 ## Checks

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@charlescms/astro",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Source-native live CMS editor for Astro sites.",
   "type": "module",
   "repository": {

package/scripts/setup.js CHANGED Viewed

@@ -321,7 +321,13 @@ function renderGitHubManifestPage({ config, state, redirectUrl }) {
   const repoOwner = config.repo.split("/")[0];
   const manifest = {
     name: appName,
-    url: config.origin,
+    // GitHub validates `url` as ONE homepage URL. config.origin can be a
+    // comma-separated allow-list (localhost + the live site), which GitHub rejects
+    // with "Url must be a valid URL" — so pick a single valid URL: the public site
+    // if given, else the first origin, else localhost.
+    url: parseOrigins(config.origin).find((origin) => !isLocalOrigin(origin))
+      || parseOrigins(config.origin)[0]
+      || "http://localhost:4321",
     redirect_url: `${redirectUrl}/callback`,
     callback_urls: [`${redirectUrl}/callback`],
     public: false,

package/src/admin.astro CHANGED Viewed

@@ -1,9 +1,13 @@
 ---
 import config from "virtual:charlescms-config";
-const previewOnly = Boolean(config.previewOnly);
 const defaultEditPath = String(config.defaultEditPath || config.editablePaths?.[0] || "/");
 const connection = config.connection || {};
+const projectId = config.projectId || "default";
+// In `astro dev` the editor can save straight to disk with no connector, so /cms
+// leads with "Start editing locally" instead of a setup form. A built/hosted site
+// has no dev server, so there it still needs the connector (rung 2).
+const dev = import.meta.env.DEV;
 ---
 <!doctype html>
 <html lang="en">
@@ -41,7 +45,9 @@ const connection = config.connection || {};
       .demo-actions { display: grid; gap: 12px; }
       .access { display: grid; gap: 3px; padding: 10px 12px; border: 1px solid #d8ded8; border-radius: 7px; background: #f8faf7; color: #5b6970; font-size: 13px; line-height: 1.4; }
       .access strong { color: #172026; }
-      .secondary { display: inline-flex; justify-content: center; color: #172026; text-decoration: none; border: 1px solid #bdc7d0; border-radius: 7px; padding: 12px 14px; font-weight: 850; background: #fbfcfd; }
+      .secondary { display: inline-flex; justify-content: center; color: #172026; text-decoration: none; border: 1px solid #bdc7d0; border-radius: 7px; padding: 12px 14px; font-weight: 850; background: #fbfcfd; box-shadow: none; }
+      .secondary:hover { background: #eef1f4; color: #172026; box-shadow: none; }
+      .secondary:active { transform: translateY(1px); }
       .footnote { color: rgba(255,255,255,.76); font-size: 13px; text-align: center; }
       .advanced { border-top: 1px solid #e4e8ec; padding-top: 8px; }
       .advanced summary { cursor: pointer; font-weight: 800; color: #3a4a55; padding: 4px 0; }
@@ -56,90 +62,81 @@ const connection = config.connection || {};
     <main>
       <div class="brand"><svg class="mark" viewBox="0 0 80 80" width="34" height="34" aria-hidden="true"><path d="M55 22 A24 24 0 1 0 55 58" fill="none" stroke="#f2c14e" stroke-width="10" stroke-linecap="round"/><rect x="47" y="30" width="7" height="20" rx="3.5" fill="#f6f4ee"/></svg><span>CharlesCMS</span></div>
       <section class="panel">
-        {previewOnly ? (
-          <>
-            <div>
-              <h1>Preview the editor</h1>
-              <p>This public demo lets you edit pages locally in your browser. Publish, versions, and uploads are disabled here.</p>
-            </div>
-            <div class="access"><strong>Demo access</strong><span>No username or password required.</span></div>
-            <div class="demo-actions">
-              <button id="preview-demo">Open preview-only editor</button>
-              <a class="secondary" href={defaultEditPath}>Open demo without editor</a>
-            </div>
-          </>
-        ) : (
-          <>
-            <div id="ready" hidden>
-              <div>
-                <h1>Ready to edit</h1>
-                <p>You're connected to <strong id="ready-repo">this site</strong>. Open the site and click any text to start editing.</p>
-              </div>
-              <form id="ready-form" class="demo-actions">
-                <label>
-                  Editor password
-                  <input id="ready-password" name="editorKey" type="password" autocomplete="current-password" placeholder="Required Worker AUTH_SECRET" required />
-                  <span class="sub">Must match the connector's required AUTH_SECRET.</span>
-                </label>
-                <button id="start-editing">Start editing</button>
-                <button type="button" id="switch-connection" class="secondary">Use a different connection</button>
-              </form>
-              <div class="error" id="ready-error"></div>
-            </div>
-            <div id="connect" hidden>
-              <div>
-                <h1>Connect CharlesCMS</h1>
-                <p>Paste the details printed by <code>npx charlescms setup --deploy --open</code>. Git credentials stay in the Worker, not in this browser.</p>
-              </div>
-              <form id="connect-form">
-                <label>
-                  Connector URL
-                  <input name="connector" placeholder="https://site-charlescms.workers.dev" autocomplete="off" required />
-                </label>
-                <label>
-                  Repository
-                  <input name="repo" placeholder="owner/name" autocomplete="off" required />
-                </label>
-                <label>
-                  Branch
-                  <input name="branch" placeholder="default branch (e.g. main)" autocomplete="off" />
-                  <span class="sub">Leave blank to use the repository's default branch.</span>
-                </label>
-                <label>
-                  Editor password
-                  <input name="editorKey" type="password" autocomplete="current-password" placeholder="Required Worker AUTH_SECRET" required />
-                  <span class="sub">Must match the connector's required AUTH_SECRET.</span>
-                </label>
-                <details class="advanced">
-                  <summary>Advanced</summary>
-                  <label>
-                    Source root
-                    <input name="sourceRoot" placeholder="website" autocomplete="off" />
-                    <span class="sub">Only for monorepos — the subfolder your Astro site lives in (e.g. website). Leave blank otherwise.</span>
-                  </label>
-                </details>
-                <div class="error" id="error"></div>
-                <button>Connect</button>
-              </form>
-            </div>
-          </>
-        )}
+        <div id="local" hidden>
+          <div>
+            <h1>Start editing</h1>
+            <p>Click any text or image on your site to edit it — your changes are written straight to your source files. Commit them with git when you're happy. No account, no setup.</p>
+          </div>
+          <div class="demo-actions">
+            <button id="start-local">Start editing locally</button>
+            <button type="button" id="show-connect" class="secondary">Connect a publisher (to edit your live site)</button>
+          </div>
+        </div>
+        <div id="ready" hidden>
+          <div>
+            <h1>Ready to edit</h1>
+            <p>You're connected to <strong id="ready-repo">this site</strong>. Open the site and click any text to start editing.</p>
+          </div>
+          <form id="ready-form" class="demo-actions">
+            <label>
+              Editor password
+              <input id="ready-password" name="editorKey" type="password" autocomplete="current-password" placeholder="Required Worker AUTH_SECRET" required />
+              <span class="sub">Must match the connector's required AUTH_SECRET.</span>
+            </label>
+            <button id="start-editing">Start editing</button>
+            <button type="button" id="switch-connection" class="secondary">Use a different connection</button>
+          </form>
+          <div class="error" id="ready-error"></div>
+        </div>
+        <div id="connect" hidden>
+          <div>
+            <h1>Connect CharlesCMS</h1>
+            <p>Paste the details printed by <code>npx charlescms setup --deploy --open</code>. Git credentials stay in the Worker, not in this browser.</p>
+          </div>
+          <form id="connect-form">
+            <label>
+              Connector URL
+              <input name="connector" placeholder="https://site-charlescms.workers.dev" autocomplete="off" required />
+            </label>
+            <label>
+              Repository
+              <input name="repo" placeholder="owner/name" autocomplete="off" required />
+            </label>
+            <label>
+              Branch
+              <input name="branch" placeholder="default branch (e.g. main)" autocomplete="off" />
+              <span class="sub">Leave blank to use the repository's default branch.</span>
+            </label>
+            <label>
+              Editor password
+              <input name="editorKey" type="password" autocomplete="current-password" placeholder="Required Worker AUTH_SECRET" required />
+              <span class="sub">Must match the connector's required AUTH_SECRET.</span>
+            </label>
+            <details class="advanced">
+              <summary>Advanced</summary>
+              <label>
+                Source root
+                <input name="sourceRoot" placeholder="website" autocomplete="off" />
+                <span class="sub">Only for monorepos — the subfolder your Astro site lives in (e.g. website). Leave blank otherwise.</span>
+              </label>
+            </details>
+            <div class="error" id="error"></div>
+            <button>Connect</button>
+          </form>
+        </div>
       </section>
       <div class="footnote">Protected visual editing for Astro.</div>
     </main>
-    <script type="module" define:vars={{ defaultEditPath, previewOnly, connection }}>
-      const configKey = "charlescms_connector";
+    <script type="module" define:vars={{ defaultEditPath, connection, projectId, dev }}>
+      // Storage is namespaced per project so two local sites sharing a dev port
+      // (origin is just localhost:<port>) never read each other's connection.
+      const configKey = `charlescms_connector::${projectId}`;
       const lastKey = `${configKey}_last`;
+      const LEGACY_CONFIG_KEY = "charlescms_connector";
       const explicitNext = new URLSearchParams(location.search).get("next");
       const nextPath = safeLocalPath(explicitNext || defaultEditPath, defaultEditPath);
-      const previewDemo = document.querySelector("#preview-demo");
-      if (previewOnly) {
-        if (!explicitNext) location.replace(defaultEditPath);
-        previewDemo?.addEventListener("click", () => { location.href = nextPath; });
-      } else {
-        setupConnect();
-      }
+      setupConnect();
       function setupConnect() {
         const saved = readSession();
@@ -157,11 +154,29 @@ const connection = config.connection || {};
           showReady(preset);
           return;
         }
-        // No connection anywhere → show the form, prefilled from the last
-        // connection used (so Logout never forces a full retype) or a partial preset.
+        // No connection. In dev, lead with instant local editing (writes to disk,
+        // no setup); the connector form is a secondary path for publishing a live
+        // site. In a built/hosted site there's no dev server, so the connector is
+        // required — show the form straight away.
+        if (dev) {
+          showLocal({ ...preset, ...last });
+          return;
+        }
         showForm({ ...preset, ...last });
       }
+      function showLocal(prefill) {
+        const local = document.querySelector("#local");
+        local.hidden = false;
+        document.querySelector("#start-local")?.addEventListener("click", () => {
+          location.href = nextPath;
+        });
+        document.querySelector("#show-connect")?.addEventListener("click", () => {
+          local.hidden = true;
+          showForm(prefill);
+        });
+      }
       function showReady(preset) {
         const ready = document.querySelector("#ready");
         const repoEl = document.querySelector("#ready-repo");
@@ -285,21 +300,34 @@ const connection = config.connection || {};
         }
       }
+      function parseStore(store, key) {
+        try { return JSON.parse(store.getItem(key) || "{}") || {}; } catch { return {}; }
+      }
       function readSession() {
-        try {
-          const current = JSON.parse(sessionStorage.getItem(configKey) || "{}") || {};
-          if (current.connector && current.repo) return current;
+        const current = parseStore(sessionStorage, configKey);
+        if (current.connector && current.repo) return current;
-          // Migrate older CharlesCMS sessions away from persistent localStorage.
-          const legacy = JSON.parse(localStorage.getItem(configKey) || "{}") || {};
-          if (legacy.connector && legacy.repo) {
+        // Adopt a connection saved in persistent localStorage, or under the old
+        // un-namespaced key, into this project's session — then clear the old
+        // copies (the un-namespaced ones leaked between projects on a shared port).
+        const legacy = [
+          parseStore(localStorage, configKey),
+          parseStore(sessionStorage, LEGACY_CONFIG_KEY),
+          parseStore(localStorage, LEGACY_CONFIG_KEY)
+        ].find((value) => value.connector && value.repo);
+        if (legacy) {
+          try {
             sessionStorage.setItem(configKey, JSON.stringify(legacy));
             const { editorKey, ...prefill } = legacy;
             localStorage.setItem(lastKey, JSON.stringify(prefill));
             localStorage.removeItem(configKey);
-            return legacy;
-          }
-        } catch {}
+            sessionStorage.removeItem(LEGACY_CONFIG_KEY);
+            localStorage.removeItem(LEGACY_CONFIG_KEY);
+            localStorage.removeItem(`${LEGACY_CONFIG_KEY}_last`);
+          } catch {}
+          return legacy;
+        }
         return {};
       }

package/src/asset-images.js CHANGED Viewed

@@ -96,8 +96,8 @@ export function createAssetImages({ state, sourceMapData, fileToBase64, setToolb
         if (other.closest("[data-charlescms-ui]")) continue;
         if (sourceAssetForImg(other, assetIndex) === repoPath) showPreview(other, blobUrl);
       }
-      if (state.previewOnly || !state.connector) {
-        setToolbarStatus("Preview only — image not saved in this demo.");
+      if (!state.connector) {
+        setToolbarStatus("Connect a publisher to save image changes.");
         return;
       }
       try {

package/src/boot.js CHANGED Viewed

@@ -1,6 +1,5 @@
 const adminPath = window.__CHARLESCMS_PATH__ || "/cms";
 const editPaths = Array.isArray(window.__CHARLESCMS_EDIT_PATHS__) ? window.__CHARLESCMS_EDIT_PATHS__ : [];
-const previewOnly = Boolean(window.__CHARLESCMS_PREVIEW_ONLY__);
 // When editablePaths is configured, the editor only activates on those route
 // prefixes. This keeps non-content pages (e.g. a marketing landing page) free of
@@ -26,7 +25,6 @@ function isAdminRoute() {
 export function bootCharlesCMS() {
   if (!isAdminRoute() && isEditableHere()) {
-    window.__CHARLESCMS_PREVIEW_ONLY__ = previewOnly;
     // Keep this a STATIC specifier: Vite only rewrites bare-specifier dynamic
     // imports when the string is literal. A template (e.g. a ?v= cache-bust)
     // leaves the bare specifier unresolved and the browser throws.

package/src/client.js CHANGED Viewed

@@ -2,6 +2,7 @@ import sourceMapData from "virtual:charlescms-source-map";
 import sectionTemplatesData from "virtual:charlescms-section-templates";
 import { createAssetImages } from "./asset-images.js";
 import { createConnectorClient } from "./connector-client.js";
+import { createLocalClient } from "./local-client.js";
 import { createContentBridge } from "./content-bridge.js";
 import { createContentPanel } from "./content-panel.js";
 import { createEditAffordance } from "./edit-affordance.js";
@@ -30,10 +31,16 @@ import { createStagedPanel } from "./staged-panel.js";
 // only shared state, module wiring, session helpers, and the direct Tiptap
 // dynamic imports required by Vite for vendored `file:` installations.
 const adminPath = window.__CHARLESCMS_PATH__ || "/cms";
-const configKey = "charlescms_connector";
+// Storage is namespaced per project so two local sites sharing a dev port (where
+// the origin is just `localhost:<port>`) never read each other's saved connection.
+const configKey = `charlescms_connector::${window.__CHARLESCMS_PROJECT_ID__ || "default"}`;
+const lastKey = `${configKey}_last`;
+// The key used before storage was namespaced per project — adopted once, then
+// cleared, so a pre-upgrade connection isn't lost but also stops leaking.
+const LEGACY_CONFIG_KEY = "charlescms_connector";
 const state = {
   authenticated: false,
-  previewOnly: Boolean(window.__CHARLESCMS_PREVIEW_ONLY__),
+  local: false,
   active: null,
   edits: [],
   allSourceMap: [],
@@ -197,6 +204,7 @@ const {
   state,
   readConnectorConfig,
   createConnectorClient,
+  createLocalClient,
   closeEditor,
   loadSourceMap,
   applySourceMapIds,
@@ -257,25 +265,30 @@ async function waitForLivePage(markers = []) {
   return false;
 }
+function readStoredJSON(store, key) {
+  try { return JSON.parse(store.getItem(key) || "null"); } catch { return null; }
+}
 function readConnectorConfig() {
   const preset = (typeof window !== "undefined" && window.__CHARLESCMS_CONNECTION__) || {};
-  let saved = null;
-  try {
-    saved = JSON.parse(sessionStorage.getItem(configKey) || "null");
-  } catch {
-    saved = null;
-  }
+  let saved = readStoredJSON(sessionStorage, configKey);
   if (!saved?.connector || !saved?.repo) {
-    try {
-      const legacy = JSON.parse(localStorage.getItem(configKey) || "null");
-      if (legacy?.connector && legacy?.repo) {
-        sessionStorage.setItem(configKey, JSON.stringify(legacy));
-        const { editorKey, ...prefill } = legacy;
-        localStorage.setItem(`${configKey}_last`, JSON.stringify(prefill));
-        localStorage.removeItem(configKey);
-        saved = legacy;
-      }
-    } catch {}
+    // Adopt a connection saved in persistent localStorage, or under the old
+    // un-namespaced key, into this project's session — then remove the old copies
+    // (the un-namespaced ones are what leaked between projects on a shared port).
+    const legacy = readStoredJSON(localStorage, configKey)
+      || readStoredJSON(sessionStorage, LEGACY_CONFIG_KEY)
+      || readStoredJSON(localStorage, LEGACY_CONFIG_KEY);
+    if (legacy?.connector && legacy?.repo) {
+      sessionStorage.setItem(configKey, JSON.stringify(legacy));
+      const { editorKey, ...prefill } = legacy;
+      localStorage.setItem(lastKey, JSON.stringify(prefill));
+      localStorage.removeItem(configKey);
+      sessionStorage.removeItem(LEGACY_CONFIG_KEY);
+      localStorage.removeItem(LEGACY_CONFIG_KEY);
+      localStorage.removeItem(`${LEGACY_CONFIG_KEY}_last`);
+      saved = legacy;
+    }
   }
   // A connection the editor saved in this browser wins; otherwise fall back to
   // the owner's baked-in preset so editors are connected without any form.
@@ -330,7 +343,7 @@ async function logout() {
     const current = sessionStorage.getItem(configKey);
     if (current) {
       const { editorKey, ...prefill } = JSON.parse(current) || {};
-      localStorage.setItem(`${configKey}_last`, JSON.stringify(prefill));
+      localStorage.setItem(lastKey, JSON.stringify(prefill));
     }
   } catch {}
   sessionStorage.removeItem(configKey);

package/src/connector-client.js CHANGED Viewed

@@ -79,7 +79,8 @@ export function createConnectorClient(config) {
   const persistBranch = (value) => {
     try {
-      const key = "charlescms_connector";
+      const projectId = globalThis.window?.__CHARLESCMS_PROJECT_ID__ || "default";
+      const key = `charlescms_connector::${projectId}`;
       const saved = JSON.parse(globalThis.sessionStorage?.getItem(key) || "{}");
       if (saved?.connector) {
         saved.branch = value;

package/src/content-panel.js CHANGED Viewed

@@ -318,16 +318,13 @@ export function createContentPanel({
   function mediaFieldHtml(media) {
     const repoPath = downloadRepoPath(media.path);
     const thumb = `<img src="${escapeAttribute(media.path)}" alt="" style="width:44px;height:44px;object-fit:cover;border-radius:6px;margin-right:10px;vertical-align:middle;border:1px solid rgba(0,0,0,.1)">`;
-    const control = state.previewOnly
-      ? "<span>Uploads are disabled in this demo.</span>"
-      : repoPath
-        ? `<input type="file" accept="image/*" data-data-media="${escapeAttribute(repoPath)}">`
-        : "<span>External or dynamic image — not replaceable.</span>";
+    const control = repoPath
+      ? `<input type="file" accept="image/*" data-data-media="${escapeAttribute(repoPath)}">`
+      : "<span>External or dynamic image — not replaceable.</span>";
     return `<label>${escapeHtml(media.label)} · image\n<span style="display:flex;align-items:center">${thumb}${control}</span></label>`;
   }
   async function replaceDataMedia(event) {
-    if (state.previewOnly) return;
     const file = event.target.files?.[0];
     const repoPath = event.target.dataset.dataMedia;
     if (!file || !repoPath) return;

package/src/element-editor.js CHANGED Viewed

@@ -232,17 +232,6 @@ export function createElementEditor({
   function renderMediaTools(item) {
     if (!isMediaItem(item)) return "";
-    if (state.previewOnly) {
-      return `
-        <div class="charlescms-media-tools">
-          <p>Uploads are disabled in this public demo. The real installed version can upload through your connector.</p>
-          <div>
-            <button type="button" data-upload-disabled disabled title="Uploads are disabled in this public demo">Upload replacement</button>
-            <button type="button" data-remove>Remove</button>
-          </div>
-        </div>
-      `;
-    }
     return `
       <div class="charlescms-media-tools">
         <label>Upload replacement<input type="file" data-upload></label>
@@ -256,14 +245,6 @@ export function createElementEditor({
     if (!repoPath) {
       return '<div class="charlescms-media-tools"><p>This link points to an external or dynamic file, so it can\'t be replaced here.</p></div>';
     }
-    if (state.previewOnly) {
-      return `
-        <div class="charlescms-media-tools">
-          <p>Uploads are disabled in this public demo. The real installed version can replace files through your connector.</p>
-          <div><button type="button" disabled title="Uploads are disabled in this public demo">Replace file</button></div>
-        </div>
-      `;
-    }
     return `
       <div class="charlescms-media-tools">
         <label>Replace file<input type="file" data-replace-download></label>

package/src/index.js CHANGED Viewed

@@ -31,6 +31,7 @@ import { transformAstroSource, extractNavCollections, extractDataCollections } f
 import { collectFrontmatterFields } from "./frontmatter.js";
 import { transformMarkdownSource } from "./markdown-analyzer.js";
 import { normalizeBlockHtml, sanitizeBlockHtml } from "./sanitize.js";
+import { createEditedSource, UnsafeSourceEditError } from "./source-edit.js";
 /**
  * CharlesCMS Astro integration — adds a source-native visual editor to an Astro
@@ -43,8 +44,6 @@ import { normalizeBlockHtml, sanitizeBlockHtml } from "./sanitize.js";
  *   Defaults to all pages. Accepts a single string or an array.
  * @param {string} [options.defaultEditPath] Page the editor opens first.
  *   Defaults to the first `editablePaths` entry, else `/`.
- * @param {boolean} [options.previewOnly=false] Run the editor read-only with no
- *   publishing (e.g. a public demo).
  * @param {string} [options.connector] Preset Cloudflare connector worker URL,
  *   so editors never type connection details into a form.
  * @param {string} [options.repo] Preset `owner/name` GitHub repository.
@@ -57,7 +56,11 @@ export default function charlesCMS(options = {}) {
   const adminPath = normalizePath(options.adminPath || "/cms");
   const editablePaths = normalizeEditablePaths(options.editablePaths);
   const defaultEditPath = normalizePath(options.defaultEditPath || editablePaths[0] || "/");
-  const previewOnly = Boolean(options.previewOnly);
+  // A stable id for THIS project, derived from its directory. Browser storage is
+  // keyed by origin, which on localhost is just the port — so two local sites on
+  // the same dev port would otherwise share one saved connection. Namespacing the
+  // storage keys with this id keeps each project's connection to itself.
+  const projectId = hashId(process.cwd());
   // Optional connection baked in by the site owner so editors never have to type
   // connector/repo/branch (or the jargon-y source root) into a form. When set,
   // /cms shows a clean "Start editing" screen instead of the developer form.
@@ -98,7 +101,7 @@ export default function charlesCMS(options = {}) {
           adminPath,
           editablePaths,
           defaultEditPath,
-          previewOnly,
+          projectId,
           connection
         }));
         updateConfig({
@@ -162,7 +165,7 @@ export default function charlesCMS(options = {}) {
                     return `export default ${JSON.stringify(await buildSerializableSourceMap(projectRoot, sourceMap))};`;
                   }
                   if (id === resolvedVirtualConfigId) {
-                    return `export default ${JSON.stringify({ adminPath, editablePaths, defaultEditPath, previewOnly, connection })};`;
+                    return `export default ${JSON.stringify({ adminPath, editablePaths, defaultEditPath, projectId, connection })};`;
                   }
                   if (id === resolvedVirtualRuntimeId) {
                     return `import { bootCharlesCMS } from "@charlescms/astro/src/boot.js"; bootCharlesCMS();`;
@@ -284,6 +287,84 @@ export default function charlesCMS(options = {}) {
                     });
                   });
+                  // Local-first editing: with no connector configured, `astro dev`
+                  // applies a staged edit straight to the project's source on disk
+                  // here — the same byte-verified transform the connector runs, just
+                  // written locally instead of committed to GitHub. The server reads
+                  // the current file, re-verifies the recorded bytes still match
+                  // (so a hand-edit since the last build fails safely, never a blind
+                  // overwrite), writes the result, and lets the editor own the single
+                  // reload. There is no production counterpart: a deployed site has no
+                  // dev server, so saving requires the connector (rung 2).
+                  server.middlewares.use("/_charlescms/apply-edit", (request, response) => {
+                    if (request.method !== "POST") { response.statusCode = 405; response.end(); return; }
+                    let body = "";
+                    request.on("data", (chunk) => { body += chunk; });
+                    request.on("end", async () => {
+                      const fail = (status, error) => {
+                        response.statusCode = status;
+                        response.setHeader("content-type", "application/json");
+                        response.end(JSON.stringify({ error }));
+                      };
+                      try {
+                        const { file, entry, edit } = JSON.parse(body || "{}");
+                        const target = safeProjectSourcePath(projectRoot, file);
+                        if (!target || !entry || !edit) { fail(400, "Invalid edit request."); return; }
+                        let current;
+                        try {
+                          current = await readFile(target, "utf8");
+                        } catch {
+                          fail(404, `Source file not found: ${file}`);
+                          return;
+                        }
+                        let next;
+                        try {
+                          next = createEditedSource(current, { ...entry, file }, edit);
+                        } catch (error) {
+                          if (error instanceof UnsafeSourceEditError) { fail(409, error.message); return; }
+                          throw error;
+                        }
+                        if (next === current) {
+                          response.statusCode = 200;
+                          response.setHeader("content-type", "application/json");
+                          response.end(JSON.stringify({ unchanged: true }));
+                          return;
+                        }
+                        mirrorReloadGuardUntil = Date.now() + 2000;
+                        await writeFile(target, next);
+                        response.statusCode = 200;
+                        response.setHeader("content-type", "application/json");
+                        response.end(JSON.stringify({ ok: true }));
+                      } catch (error) {
+                        fail(500, String(error?.message || error));
+                      }
+                    });
+                  });
+                  // Local-first media: write a replaced image/upload straight to disk
+                  // (the connector path commits to GitHub instead). Limited to images
+                  // under src/ (astro:assets source overwrite, re-optimized on reload)
+                  // and files under public/ (uploads and replaced downloads).
+                  server.middlewares.use("/_charlescms/write-binary", (request, response) => {
+                    if (request.method !== "POST") { response.statusCode = 405; response.end(); return; }
+                    let body = "";
+                    request.on("data", (chunk) => { body += chunk; });
+                    request.on("end", async () => {
+                      try {
+                        const { path, base64 } = JSON.parse(body || "{}");
+                        const target = safeProjectBinaryPath(projectRoot, path);
+                        if (!target) { response.statusCode = 400; response.end("invalid path"); return; }
+                        await mkdir(dirname(target), { recursive: true });
+                        await writeFile(target, Buffer.from(String(base64 || ""), "base64"));
+                        response.statusCode = 204;
+                        response.end();
+                      } catch (error) {
+                        response.statusCode = 500;
+                        response.end(String(error?.message || error));
+                      }
+                    });
+                  });
                   let refreshTimer;
                   let refreshQueue = Promise.resolve();
                   const scheduleRefresh = (file) => {
@@ -394,7 +475,7 @@ function renderPageScript(config) {
   return `window.__CHARLESCMS_PATH__=${JSON.stringify(config.adminPath)};
 window.__CHARLESCMS_EDIT_PATHS__=${JSON.stringify(config.editablePaths)};
 window.__CHARLESCMS_DEFAULT_EDIT_PATH__=${JSON.stringify(config.defaultEditPath)};
-window.__CHARLESCMS_PREVIEW_ONLY__=${JSON.stringify(config.previewOnly)};
+window.__CHARLESCMS_PROJECT_ID__=${JSON.stringify(config.projectId)};
 window.__CHARLESCMS_CONNECTION__=${JSON.stringify(config.connection || {})};
 import("virtual:charlescms-runtime");`;
 }
@@ -534,6 +615,36 @@ function safeProjectSourcePath(root, relativePath) {
   return target;
 }
+// Resolve a project-relative binary path (a replaced image or upload) for the dev
+// write endpoint, only if it stays inside the project and names a file we allow:
+// images under src/ (astro:assets source overwrite) or any file under public/.
+// Anything traversing out, absolute, or elsewhere is rejected.
+function safeProjectBinaryPath(root, relativePath) {
+  const value = String(relativePath || "").replace(/\\/g, "/");
+  if (!value || value.startsWith("/") || value.split("/").includes("..")) return null;
+  if (!/^[A-Za-z0-9._/-]+$/.test(value)) return null;
+  const inSrc = value.startsWith("src/");
+  const inPublic = value.startsWith("public/");
+  if (!inSrc && !inPublic) return null;
+  if (inSrc && !IMAGE_EXT_RE.test(value)) return null;
+  if (inPublic && !/\.[A-Za-z0-9]+$/.test(value)) return null;
+  const target = resolve(root, value);
+  const base = resolve(root);
+  if (target !== base && !target.startsWith(base + sep)) return null;
+  return target;
+}
+// A short, stable id for a project directory (djb2). Dependency-free; only used to
+// namespace per-project browser storage, so collision resistance isn't critical.
+function hashId(value) {
+  let hash = 5381;
+  const text = String(value || "");
+  for (let index = 0; index < text.length; index++) {
+    hash = ((hash << 5) + hash + text.charCodeAt(index)) >>> 0;
+  }
+  return hash.toString(36);
+}
 function isSectionTemplateFile(file, root) {
   const path = String(file || "").replace(/\\/g, "/");
   const directory = join(root, "src/charlescms/templates").replace(/\\/g, "/").replace(/\/+$/, "");

package/src/local-client.js ADDED Viewed

@@ -0,0 +1,50 @@
+import { ConnectorError } from "./connector-client.js";
+// Local (no-connector) client used in `astro dev` to write visual edits straight
+// to the project's source files on disk, through the dev-only endpoints in
+// index.js. It mirrors the slice of the connector-client API the editor calls, so
+// publishing.js and the media tools work unchanged — they just write locally
+// instead of committing to GitHub. The user keeps their edits with their own git.
+//
+// Version history (listCommits/revertCommit) has no local equivalent, so the UI
+// hides those affordances via `supportsVersions: false` / `local: true`.
+export function createLocalClient() {
+  const post = async (path, body) => {
+    const response = await fetch(path, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    const data = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      throw new ConnectorError(data.error || `Local save failed (${response.status}).`, response.status);
+    }
+    return data;
+  };
+  const applyEdit = async (entry, edit) => {
+    const data = await post("/_charlescms/apply-edit", { file: entry.file, entry, edit });
+    return { id: edit.id, file: entry.file, commit: null, unchanged: Boolean(data.unchanged) };
+  };
+  const putBase64 = async (path, base64) => {
+    await post("/_charlescms/write-binary", { path, base64: String(base64).replace(/\s/g, "") });
+    return { commit: null };
+  };
+  // No GitHub locally: getFile is only ever called to fetch a blob SHA before an
+  // overwrite, which doesn't apply on disk — return null so callers skip it.
+  const getFile = async () => null;
+  return {
+    applyEdit,
+    putBase64,
+    getFile,
+    listCommits: async () => [],
+    revertCommit: async () => { throw new ConnectorError("Version history needs a connector.", 0); },
+    verifyAccess: async () => ({ local: true }),
+    local: true,
+    supportsVersions: false,
+    config: { local: true, branch: "" }
+  };
+}

package/src/publishing.js CHANGED Viewed

@@ -176,16 +176,20 @@ export function createPublishing({
       renderPendingTray();
       const count = published.length;
       const plural = count === 1 ? "" : "s";
+      // Local mode writes to the project's source files; the connector publishes.
+      const done = state.local
+        ? `Saved ${count} change${plural} to your source files.`
+        : `Published ${count} change${plural}.`;
-      // Dev mirrors the new source to disk immediately, so a quick reload gives a
-      // fresh, byte-consistent map.
+      // Dev mirrors the new source to disk immediately (and local mode writes it
+      // there directly), so a quick reload gives a fresh, byte-consistent map.
       if (import.meta.env?.DEV && count && !window.__CHARLESCMS_NO_RELOAD__ && !window.__CHARLESCMS_FORCE_PUBLISH_WAIT__) {
-        setToolbarStatus(`Published ${count} change${plural}.`);
+        setToolbarStatus(done);
         setTimeout(() => location.reload(), 700);
         return;
       }
       if (window.__CHARLESCMS_NO_RELOAD__) {
-        setToolbarStatus(`Published ${count} change${plural}.`);
+        setToolbarStatus(done);
         return;
       }
@@ -229,7 +233,7 @@ export function createPublishing({
   }
   async function uploadActiveMedia(event) {
-    if (!state.active || state.previewOnly) return;
+    if (!state.active) return;
     const file = event.target.files?.[0];
     if (!file) return;
     const { dialog, item } = state.active;
@@ -260,7 +264,7 @@ export function createPublishing({
   }
   async function replaceDownloadFile(event) {
-    if (!state.active || state.previewOnly) return;
+    if (!state.active) return;
     const file = event.target.files?.[0];
     if (!file) return;
     const { dialog, item } = state.active;

package/src/runtime-controller.js CHANGED Viewed

@@ -10,6 +10,7 @@ export function createRuntimeController({
   state,
   readConnectorConfig,
   createConnectorClient,
+  createLocalClient,
   closeEditor,
   loadSourceMap,
   applySourceMapIds,
@@ -31,10 +32,17 @@ export function createRuntimeController({
     if (state.initializedPath === location.pathname && state.toolbar?.isConnected) return;
     resetEditorUi();
     const config = readConnectorConfig();
-    state.authenticated = state.previewOnly || Boolean(config);
+    // No connector configured? In `astro dev` fall back to local mode: the editor
+    // boots and saves edits straight to the project's source files on disk, no
+    // account or form required. A connector, when present, always wins (it can
+    // publish from a deployed site). Without either, in a non-dev build, the editor
+    // stays dormant and /cms shows the connect form (rung 2).
+    const local = !config && Boolean(import.meta.env?.DEV);
+    state.local = local;
+    state.authenticated = local || Boolean(config);
     if (!state.authenticated) return;
-    state.connector = state.previewOnly ? null : createConnectorClient(config);
+    state.connector = config ? createConnectorClient(config) : createLocalClient();
     loadSourceMap();
     applySourceMapIds();
     // Bring any edits staged before a reload/navigation back into memory, then

package/src/toolbar.js CHANGED Viewed

@@ -27,10 +27,13 @@ export function createToolbar({
         <button type="button" data-charlescms-publish hidden>Publish</button>
         <button type="button" data-charlescms-page-settings hidden title="Fields that don't show on the page itself, like the Google title and description">Page info</button>
         <button type="button" data-charlescms-highlight title="Outline everything you can edit on this page">Show editable</button>
-        <button type="button" data-charlescms-versions ${state.previewOnly ? 'disabled title="Disabled in this public demo"' : ""}>Versions</button>
-        ${state.previewOnly ? "" : '<button type="button" data-charlescms-logout>Logout</button>'}
+        <button type="button" data-charlescms-versions ${state.local ? 'disabled title="Connect a publisher to use version history"' : ""}>Versions</button>
+        ${state.local ? "" : '<button type="button" data-charlescms-logout>Logout</button>'}
       </div>
     `;
+    // Local mode writes to disk, so the action saves files rather than publishing.
+    const publishButton = toolbar.querySelector("[data-charlescms-publish]");
+    if (publishButton && state.local) publishButton.textContent = "Save to local files";
     toolbar.querySelector("[data-charlescms-logout]")?.addEventListener("click", logout);
     // Editors start with all editable regions outlined; the toggle provides an
@@ -43,7 +46,7 @@ export function createToolbar({
     };
     setHighlight(true);
     highlight.addEventListener("click", () => setHighlight(!document.documentElement.classList.contains("charlescms-show-all")));
-    toolbar.querySelector("[data-charlescms-publish]")?.addEventListener("click", state.previewOnly ? explainPreviewOnly : publishPending);
+    toolbar.querySelector("[data-charlescms-publish]")?.addEventListener("click", publishPending);
     toolbar.querySelector("[data-charlescms-discard]").addEventListener("click", discardPending);
     toolbar.querySelector("[data-charlescms-review]")?.addEventListener("click", openStagedPanel);
@@ -53,7 +56,7 @@ export function createToolbar({
     const pageSettings = toolbar.querySelector("[data-charlescms-page-settings]");
     pageSettings.hidden = !currentPageHasFrontmatter();
     pageSettings.addEventListener("click", openPageSettings);
-    toolbar.querySelector("[data-charlescms-versions]")?.addEventListener("click", state.previewOnly ? explainPreviewOnly : openVersionsPanel);
+    toolbar.querySelector("[data-charlescms-versions]")?.addEventListener("click", openVersionsPanel);
     document.body.append(toolbar);
     state.toolbar = toolbar;
@@ -81,9 +84,8 @@ export function createToolbar({
     const count = state.pending.size;
     if (publish) {
       publish.hidden = false;
-      publish.disabled = state.previewOnly || state.busy;
-      if (state.previewOnly) publish.title = "Disabled in this public demo";
-      else publish.title = count === 0 ? "No changes to publish" : "";
+      publish.disabled = state.busy;
+      publish.title = count === 0 ? (state.local ? "No changes to save" : "No changes to publish") : "";
     }
     discard.hidden = count === 0;
     const review = state.toolbar.querySelector("[data-charlescms-review]");
@@ -92,7 +94,7 @@ export function createToolbar({
     // staged-change indicator. Transient messages reuse the same slot.
     setToolbarInfo(count > 0
       ? `${count} change${count === 1 ? "" : "s"} staged`
-      : state.previewOnly ? "Preview only" : `${scanEditableElements().length} editable`);
+      : `${scanEditableElements().length} editable`);
   }
   function setToolbarInfo(text) {
@@ -102,10 +104,6 @@ export function createToolbar({
     info.classList.toggle("charlescms-info-pending", state.pending.size > 0);
   }
-  function explainPreviewOnly() {
-    setToolbarStatus("Disabled in this public demo. Real installations can publish through your connector.");
-  }
   function setBusy(value, message = "") {
     state.busy = value;
     if (message) setToolbarStatus(message);