@mahe_pkm/buzl-html-editor 0.1.0 → 0.2.0

package/HANDBOOK.md

@@ -0,0 +1,234 @@
+# Buzl HTML Editor Handbook
+
+This handbook explains how to install and run Buzl HTML Editor in the root of an ordinary static HTML website. It is for Windows, macOS, and Linux users.
+
+## What Buzl does
+
+`buzl-editor` starts one local server with two ways to work:
+
+| Address | Use it for |
+| --- | --- |
+| `http://localhost:4000/` | Normal website preview with the floating **Edit Text** toolbar |
+| `http://localhost:4000/admin/` | The full visual editor, page controls, and image upload tools |
+
+`buzl-site` starts a clean website-only preview. It has no editor, edit toolbar, or editor API routes.
+
+## Before you start
+
+You need Node.js 18 or newer. Node.js 20 LTS or newer is recommended.
+
+```powershell
+node --version
+npm --version
+```
+
+Your website root is the folder that contains `index.html`. It normally also contains folders such as `assets`, `images`, `css`, or `js`.
+
+```text
+client-website/
+├── index.html
+├── about.html
+├── assets/
+├── images/
+└── css/
+```
+
+Before editing, make a copy of the complete website folder or commit the current work to Git. Buzl makes page backups on save, but a full-site backup is still the simplest recovery point.
+
+## Install Buzl
+
+### Recommended: install for one website
+
+Open a terminal in the website root, then run:
+
+```powershell
+npm install --save-dev @mahe_pkm/buzl-html-editor
+```
+
+Run it with `npx`, which always uses the version installed for this website:
+
+```powershell
+npx buzl-editor
+```
+
+### Optional: install globally
+
+Use this only when you want one command available for many websites on the same computer:
+
+```powershell
+npm install -g @mahe_pkm/buzl-html-editor
+```
+
+Then use `buzl-editor` and `buzl-site` directly instead of `npx buzl-editor` and `npx buzl-site`.
+
+## First-time checks
+
+From the website root, create Buzl's optional local configuration and run diagnostics:
+
+```powershell
+npx buzl-editor init
+npx buzl-editor doctor
+```
+
+`init` creates `.buzl/config.json`, `.env.example`, and safe Git-ignore rules only when they are missing. It does not replace website HTML. `doctor` checks that Buzl can find HTML pages and start safely.
+
+## Start the website and editor
+
+```powershell
+npx buzl-editor
+```
+
+The default addresses are:
+
+```text
+Website preview:  http://localhost:4000/
+Advanced editor: http://localhost:4000/admin/
+```
+
+Use a different port when `4000` is already in use:
+
+```powershell
+npx buzl-editor --port 4173
+```
+
+Then open:
+
+```text
+http://localhost:4173/
+http://localhost:4173/admin/
+```
+
+To run a site while your terminal is in another folder, provide its root explicitly:
+
+```powershell
+npx buzl-editor --root "C:\Websites\client-website" --port 4000
+```
+
+By default, Buzl opens the normal website preview. To open the advanced editor instead:
+
+```powershell
+npx buzl-editor --open-admin
+```
+
+To prevent a browser tab opening automatically:
+
+```powershell
+npx buzl-editor --no-open
+```
+
+Press `Ctrl+C` in the same terminal window to stop the server.
+
+## Edit text from the normal website preview
+
+1. Open the normal preview URL, such as `http://localhost:4000/`.
+2. Use the floating toolbar in the lower-right corner.
+3. Select **Edit Text**.
+4. Click highlighted text, type your change, and inspect the result.
+5. Select **Undo** to reverse the latest edit, or **Cancel** to discard all unsaved edits.
+6. Select **Save** only when the page is correct.
+
+The toolbar is available only from `buzl-editor` while it is bound to your local machine. Simply opening the preview or turning on Edit Text does not write the toolbar into your website files. Saving writes only the approved page content and creates a recoverable backup under `.buzl/backups/`.
+
+Use the advanced editor when you need image upload, optimization, page controls, or richer editing tools.
+
+## Use the advanced editor
+
+Open `http://localhost:4000/admin/`.
+
+Use the page list to choose an HTML page. Make changes, preview the page, and save only after checking text, links, mobile layout, and images. Uploaded raster images are optimized to AVIF and saved under `assets/images/`; safe SVG images remain SVG.
+
+## Run a clean website-only preview
+
+Use this when you want to show or test the local website without any editing controls:
+
+```powershell
+npx buzl-site
+```
+
+For a different port:
+
+```powershell
+npx buzl-site --port 4173
+```
+
+Website-only mode deliberately blocks `/admin/`, editor APIs, local configuration, dependencies, package files, and the Preview Live Edit toolbar.
+
+## macOS and Linux
+
+The commands are the same in Terminal. Change into the website root first:
+
+```bash
+cd "/path/to/client-website"
+npm install --save-dev @mahe_pkm/buzl-html-editor
+npx buzl-editor
+```
+
+Stop the server with `Ctrl+C`.
+
+## Backups and rollback
+
+Every saved HTML change gets a timestamped backup in `.buzl/backups/`. To recover, stop the editor, copy the required backup over the affected HTML file, then restart and check the page in a browser.
+
+For an entire website rollback, restore the full copy or Git commit made before editing. Do not delete current work until the restored copy has been checked.
+
+## Troubleshooting
+
+### `buzl-editor` is not recognized
+
+Use the project-local command:
+
+```powershell
+npx buzl-editor
+```
+
+Or reinstall the global package and reopen the terminal:
+
+```powershell
+npm install -g @mahe_pkm/buzl-html-editor
+```
+
+### The browser shows `Cannot GET /`
+
+Confirm you started Buzl from the folder containing `index.html`. If the website has no root `index.html`, open the actual page URL or add the correct entry page before starting.
+
+### Port already in use
+
+Stop the earlier server with `Ctrl+C`, or choose another port:
+
+```powershell
+npx buzl-editor --port 4173
+```
+
+### The Edit Text toolbar is missing
+
+Use `buzl-editor`, not `buzl-site`, and open the local website URL from the terminal output. The toolbar is intentionally disabled on a network-bound server.
+
+### Images or styles are missing
+
+Start from the true website root and use the local HTTP address. Do not open pages directly with `file://`, because relative asset paths and scripts can behave differently.
+
+## Update Buzl
+
+For a website-local installation:
+
+```powershell
+npm update @mahe_pkm/buzl-html-editor
+```
+
+For a global installation:
+
+```powershell
+npm update -g @mahe_pkm/buzl-html-editor
+```
+
+Back up the website, run `doctor`, start the editor, and test the website preview and `/admin/` after every update.
+
+## Safety checklist before deployment
+
+- Confirm every changed page in a browser.
+- Test navigation, forms, images, and mobile layout.
+- Keep a dated full-site backup.
+- Deploy with your existing hosting or Git workflow only after local review.
+- Never upload `.env` files or API keys.
+
+This version supports ordinary static HTML, CSS, JavaScript, and multi-page websites. Server-rendered and build-system websites require a separate integration workflow.

package/README.md

@@ -1,12 +1,17 @@
 # Buzl HTML Editor
 
 A local visual editor and static-site server for ordinary multi-page HTML, CSS,
-and JavaScript websites. It includes Live Edit, image uploads, AVIF image
+and JavaScript websites. It includes on-page Live Edit, image uploads, AVIF image
 optimization, AI-assisted text, and AI image generation.
 
 The server is local-only by default. It edits the website folder from which it
 is started; the editor's own files stay inside the npm package.
 
+## Documentation
+
+- Full setup handbook: [HANDBOOK.md](./HANDBOOK.md)
+- Printable handbook: [docs/Buzl-HTML-Editor-Handbook.pdf](./docs/Buzl-HTML-Editor-Handbook.pdf)
+
 ## Requirements
 
 - Node.js 18 or newer
@@ -29,8 +34,19 @@ npx buzl-editor
 
 Default addresses:
 
-- Website: `http://localhost:4000/`
-- Editor: `http://localhost:4000/admin/`
+- Website with a floating **Edit Text** toolbar: `http://localhost:4000/`
+- Advanced editor: `http://localhost:4000/admin/`
+
+`buzl-editor` opens the website preview by default. Select **Edit Text** to edit
+visible text directly on any page, then use **Save**, **Undo**, or **Cancel**.
+The toolbar is injected only while the local editor server is running and is
+never added to the saved website.
+
+Open the advanced editor by default when needed:
+
+```bash
+npx buzl-editor --open-admin
+```
 
 Use another port or website folder when needed:
 
@@ -52,8 +68,8 @@ npx buzl-site
 npx buzl-site --port 3500
 ```
 
-Website-only mode blocks the editor, APIs, dependencies, configuration,
-development files, and local secrets.
+Website-only mode does not inject the editing toolbar and blocks the editor,
+APIs, dependencies, configuration, development files, and local secrets.
 
 ## Setup and diagnostics
 
@@ -106,6 +122,8 @@ actions require them.
 - Non-local binding requires both `--host` and `--allow-network`.
 - The editor can only load and save HTML files inside the selected website.
 - Each save creates a recoverable copy under `.buzl/backups/`.
+- Preview Live Edit uses short-lived page tokens, rejects stale-page saves, and
+  is disabled when the editor binds to a non-local network address.
 - Uploaded raster images are optimized to AVIF under `assets/images/`.
 - `.env`, `.git`, `.buzl`, `node_modules`, tests, package metadata, and server
   source are not publicly served.

package/bin/buzl-editor.js

@@ -31,7 +31,8 @@ Options:
   --port, -p         Local port (default: 4000)
   --host <address>   Bind address (default: 127.0.0.1)
   --allow-network    Required for a non-local bind address
-  --open             Open the editor in the default browser
+  --open             Open the website preview in the default browser
+  --open-admin       Open the advanced /admin editor instead
   --no-open          Do not open a browser
   --version, -v      Show package version
   --help, -h         Show this help
@@ -87,7 +88,7 @@ async function main() {
       console.log(`Editor:  ${editorUrl}`);
       console.log(`Root:    ${options.root}`);
       console.log('Press Ctrl+C to stop.\n');
-      if (options.open) openBrowser(editorUrl);
+      if (options.open) openBrowser(options.openAdmin ? editorUrl : siteUrl);
     });
 
     const stop = () => server.close(() => process.exit(0));

package/dist/public/public-live-edit.css

@@ -0,0 +1,114 @@
+:host {
+  all: initial;
+}
+
+.buzl-toolbar {
+  align-items: center;
+  background: #211717;
+  border: 1px solid rgba(212, 175, 55, 0.55);
+  border-radius: 14px;
+  bottom: 18px;
+  box-shadow: 0 14px 42px rgba(0, 0, 0, 0.35);
+  color: #f8f4eb;
+  display: flex;
+  flex-wrap: wrap;
+  font: 600 13px/1.2 Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  gap: 8px;
+  max-width: calc(100vw - 32px);
+  padding: 9px;
+  position: fixed;
+  right: 18px;
+  z-index: 2147483647;
+}
+
+.buzl-toolbar button,
+.buzl-toolbar a {
+  align-items: center;
+  background: transparent;
+  border: 1px solid rgba(255, 255, 255, 0.2);
+  border-radius: 9px;
+  box-sizing: border-box;
+  color: inherit;
+  cursor: pointer;
+  display: inline-flex;
+  font: inherit;
+  min-height: 36px;
+  padding: 8px 12px;
+  text-decoration: none;
+}
+
+.buzl-toolbar button:hover,
+.buzl-toolbar a:hover {
+  border-color: #d4af37;
+  color: #f5d975;
+}
+
+.buzl-toolbar button:focus-visible,
+.buzl-toolbar a:focus-visible {
+  outline: 3px solid rgba(212, 175, 55, 0.35);
+  outline-offset: 2px;
+}
+
+.buzl-toolbar button:disabled {
+  cursor: not-allowed;
+  opacity: 0.45;
+}
+
+.buzl-toolbar .buzl-primary {
+  background: #d4af37;
+  border-color: #d4af37;
+  color: #211717;
+}
+
+.buzl-toolbar .buzl-primary:hover {
+  background: #ebca5b;
+  color: #211717;
+}
+
+.buzl-toolbar .buzl-status {
+  color: #d9d0c7;
+  font-weight: 500;
+  max-width: 260px;
+  overflow: hidden;
+  padding: 0 5px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.buzl-toolbar .buzl-status[data-tone="success"] {
+  color: #89e6aa;
+}
+
+.buzl-toolbar .buzl-status[data-tone="warning"] {
+  color: #f5d975;
+}
+
+.buzl-toolbar .buzl-status[data-tone="error"] {
+  color: #ff9c9c;
+}
+
+@media (max-width: 680px) {
+  .buzl-toolbar {
+    bottom: 10px;
+    left: 10px;
+    right: 10px;
+  }
+
+  .buzl-toolbar .buzl-status {
+    flex: 1 1 100%;
+    max-width: none;
+    order: -1;
+  }
+}
+
+body.buzl-public-editing [data-buzl-public-edit="true"] {
+  cursor: text !important;
+  outline: 2px dashed rgba(212, 175, 55, 0.85) !important;
+  outline-offset: 3px !important;
+}
+
+body.buzl-public-editing [data-buzl-public-edit="true"]:focus {
+  background: rgba(212, 175, 55, 0.13) !important;
+  outline-style: solid !important;
+}
+

package/dist/public/public-live-edit.js

@@ -0,0 +1,267 @@
+(() => {
+  'use strict';
+
+  const runtime = document.currentScript
+    || document.querySelector('script[data-buzl-live-edit-runtime]');
+  if (!runtime || !runtime.dataset.buzlPageToken) return;
+
+  const pageToken = runtime.dataset.buzlPageToken;
+  const pagePath = runtime.dataset.buzlPagePath || window.location.pathname;
+  const editableSelector = '[data-buzl-public-edit-key]';
+  const originals = new Map();
+  const histories = new Map();
+  const dirtyKeys = new Set();
+  let editMode = false;
+  let activeKey = null;
+  let lastChangedKey = null;
+  let saving = false;
+
+  const host = document.createElement('div');
+  host.setAttribute('data-buzl-public-editor-ui', 'true');
+  const shadow = host.attachShadow({ mode: 'open' });
+  const stylesheet = document.createElement('link');
+  stylesheet.rel = 'stylesheet';
+  stylesheet.href = '/__buzl/live-edit.css';
+  shadow.appendChild(stylesheet);
+
+  const toolbar = document.createElement('div');
+  toolbar.className = 'buzl-toolbar';
+  toolbar.setAttribute('role', 'toolbar');
+  toolbar.setAttribute('aria-label', 'Buzl page editor');
+  toolbar.innerHTML = `
+    <span class="buzl-status" data-status title="${escapeAttribute(pagePath)}">Ready to edit this page</span>
+    <button class="buzl-primary" type="button" data-toggle aria-pressed="false">Edit Text</button>
+    <button type="button" data-save disabled>Save</button>
+    <button type="button" data-undo disabled>Undo</button>
+    <button type="button" data-cancel disabled>Cancel</button>
+    <a href="/admin/" data-advanced>Advanced Editor</a>
+  `;
+  shadow.appendChild(toolbar);
+  document.documentElement.appendChild(host);
+
+  const toggleButton = shadow.querySelector('[data-toggle]');
+  const saveButton = shadow.querySelector('[data-save]');
+  const undoButton = shadow.querySelector('[data-undo]');
+  const cancelButton = shadow.querySelector('[data-cancel]');
+  const statusLabel = shadow.querySelector('[data-status]');
+
+  function escapeAttribute(value) {
+    return String(value)
+      .replace(/&/g, '&amp;')
+      .replace(/"/g, '&quot;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+  }
+
+  function setStatus(message, tone = '') {
+    statusLabel.textContent = message;
+    if (tone) statusLabel.dataset.tone = tone;
+    else delete statusLabel.dataset.tone;
+  }
+
+  function visibleEditableElements() {
+    return Array.from(document.querySelectorAll(editableSelector)).filter((element) => {
+      if (!element.textContent || !element.textContent.trim()) return false;
+      if (element.closest('[data-buzl-public-editor-ui], [aria-hidden="true"], svg, script, style, noscript, input, textarea, select')) {
+        return false;
+      }
+      const styles = window.getComputedStyle(element);
+      const box = element.getBoundingClientRect();
+      return styles.display !== 'none'
+        && styles.visibility !== 'hidden'
+        && box.width > 0
+        && box.height > 0;
+    });
+  }
+
+  function ensureOriginal(element) {
+    const key = element.dataset.buzlPublicEditKey;
+    if (!originals.has(key)) originals.set(key, element.innerHTML);
+    if (!histories.has(key)) histories.set(key, []);
+    return key;
+  }
+
+  function changedElements() {
+    return Array.from(document.querySelectorAll(editableSelector)).filter((element) => (
+      dirtyKeys.has(element.dataset.buzlPublicEditKey)
+    ));
+  }
+
+  function updateControls() {
+    const changed = changedElements();
+    const dirty = changed.length > 0;
+    toggleButton.textContent = editMode ? 'Editing On' : 'Edit Text';
+    toggleButton.setAttribute('aria-pressed', String(editMode));
+    saveButton.disabled = !dirty || saving;
+    cancelButton.disabled = !dirty || saving;
+    const history = activeKey ? histories.get(activeKey) : histories.get(lastChangedKey);
+    undoButton.disabled = !history || history.length === 0 || saving;
+    if (dirty && !saving) setStatus(`${changed.length} unsaved change${changed.length === 1 ? '' : 's'}`, 'warning');
+    if (!dirty && !saving) setStatus(editMode ? 'Click highlighted text to edit' : 'Ready to edit this page');
+  }
+
+  function setEditMode(nextMode) {
+    editMode = Boolean(nextMode);
+    document.body.classList.toggle('buzl-public-editing', editMode);
+    for (const element of document.querySelectorAll(editableSelector)) {
+      if (editMode) {
+        element.setAttribute('contenteditable', 'true');
+        element.setAttribute('spellcheck', 'true');
+        element.setAttribute('data-buzl-public-edit', 'true');
+      } else {
+        element.removeAttribute('contenteditable');
+        element.removeAttribute('spellcheck');
+        element.removeAttribute('data-buzl-public-edit');
+      }
+    }
+    sessionStorage.setItem('buzl-live-edit-enabled', editMode ? '1' : '0');
+    updateControls();
+  }
+
+  function restoreOriginals() {
+    for (const key of dirtyKeys) {
+      const element = document.querySelector(`[data-buzl-public-edit-key="${CSS.escape(key)}"]`);
+      if (element && originals.has(key)) element.innerHTML = originals.get(key);
+      histories.set(key, []);
+    }
+    dirtyKeys.clear();
+    activeKey = null;
+    lastChangedKey = null;
+  }
+
+  async function saveChanges() {
+    if (saving) return;
+    const changed = changedElements();
+    if (!changed.length) return;
+
+    saving = true;
+    updateControls();
+    setStatus('Saving…', 'warning');
+    try {
+      const response = await fetch('/__buzl/live-edit/save', {
+        method: 'POST',
+        credentials: 'same-origin',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          pageToken,
+          changes: changed.map((element) => ({
+            key: element.dataset.buzlPublicEditKey,
+            html: element.innerHTML,
+          })),
+        }),
+      });
+      const result = await response.json().catch(() => ({}));
+      if (!response.ok) throw new Error(result.error || 'Could not save this page');
+
+      const savedChanges = new Map(
+        Array.isArray(result.savedChanges)
+          ? result.savedChanges.map((change) => [String(change.key), String(change.html)])
+          : [],
+      );
+      for (const element of changed) {
+        const key = ensureOriginal(element);
+        if (savedChanges.has(key)) element.innerHTML = savedChanges.get(key);
+        originals.set(key, element.innerHTML);
+        histories.set(key, []);
+        dirtyKeys.delete(key);
+      }
+      activeKey = null;
+      lastChangedKey = null;
+      const successMessage = `Saved ${result.savedCount || changed.length} change${changed.length === 1 ? '' : 's'}`;
+      setStatus(successMessage, 'success');
+      setTimeout(() => {
+        if (!changedElements().length) updateControls();
+      }, 1800);
+    } catch (error) {
+      setStatus(error.message || 'Save failed', 'error');
+    } finally {
+      saving = false;
+      updateControls();
+      if (!changedElements().length) {
+        setStatus('Saved successfully', 'success');
+      }
+    }
+  }
+
+  toggleButton.addEventListener('click', () => setEditMode(!editMode));
+  saveButton.addEventListener('click', saveChanges);
+  cancelButton.addEventListener('click', () => {
+    if (!changedElements().length || window.confirm('Discard all unsaved text changes on this page?')) {
+      restoreOriginals();
+      setEditMode(false);
+      setStatus('Changes cancelled');
+    }
+  });
+  undoButton.addEventListener('click', () => {
+    const key = activeKey || lastChangedKey;
+    if (!key) return;
+    const element = document.querySelector(`[data-buzl-public-edit-key="${CSS.escape(key)}"]`);
+    const history = histories.get(key) || [];
+    if (!element || !history.length) return;
+    element.innerHTML = history.pop();
+    activeKey = key;
+    if (element.innerHTML === originals.get(key)) dirtyKeys.delete(key);
+    else dirtyKeys.add(key);
+    updateControls();
+    element.focus();
+  });
+
+  document.addEventListener('focusin', (event) => {
+    const element = event.target.closest && event.target.closest('[data-buzl-public-edit="true"]');
+    if (element) {
+      const key = element.dataset.buzlPublicEditKey;
+      if (!dirtyKeys.has(key)) {
+        originals.set(key, element.innerHTML);
+        histories.set(key, []);
+      }
+      activeKey = key;
+    }
+  }, true);
+
+  document.addEventListener('beforeinput', (event) => {
+    const element = event.target.closest && event.target.closest('[data-buzl-public-edit="true"]');
+    if (!editMode || !element) return;
+    const key = ensureOriginal(element);
+    const history = histories.get(key);
+    if (history.at(-1) !== element.innerHTML) history.push(element.innerHTML);
+    if (history.length > 30) history.shift();
+    activeKey = key;
+    lastChangedKey = key;
+  }, true);
+
+  document.addEventListener('input', (event) => {
+    const element = event.target.closest && event.target.closest('[data-buzl-public-edit="true"]');
+    if (!editMode || !element) return;
+    lastChangedKey = ensureOriginal(element);
+    if (element.innerHTML === originals.get(lastChangedKey)) dirtyKeys.delete(lastChangedKey);
+    else dirtyKeys.add(lastChangedKey);
+    updateControls();
+  }, true);
+
+  document.addEventListener('click', (event) => {
+    if (!editMode) return;
+    const editable = event.target.closest && event.target.closest('[data-buzl-public-edit="true"]');
+    if (!editable) return;
+    if (editable.closest('a, button, summary')) event.preventDefault();
+    event.stopPropagation();
+  }, true);
+
+  document.addEventListener('keydown', (event) => {
+    if ((event.ctrlKey || event.metaKey) && event.key.toLowerCase() === 's') {
+      event.preventDefault();
+      saveChanges();
+    }
+    if (editMode && event.key === 'Escape' && document.activeElement) {
+      document.activeElement.blur();
+    }
+  }, true);
+
+  window.addEventListener('beforeunload', (event) => {
+    if (!changedElements().length) return;
+    event.preventDefault();
+    event.returnValue = '';
+  });
+
+  if (sessionStorage.getItem('buzl-live-edit-enabled') === '1') setEditMode(true);
+  else updateControls();
+})();