@mahe_pkm/buzl-html-editor 0.1.0 → 0.2.1

package/HANDBOOK.md

@@ -0,0 +1,268 @@
+# 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. Select the small floating pencil button in the lower-right corner.
+3. In the compact Buzl menu, 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 pencil opens a compact vertical menu containing Edit Text, Save, Undo, Cancel, and Advanced Editor. 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.
+
+## Advanced users: global AI API keys
+
+Buzl's normal Live Edit and image optimization do not need an AI key. AI text and AI image actions can use an Anthropic or OpenRouter key.
+
+To make a key available to every website you run with the global `buzl-editor` command, store it as an operating-system environment variable. Do not place a key in HTML, browser JavaScript, Git, or a deployed website.
+
+### Windows PowerShell
+
+```powershell
+setx ANTHROPIC_API_KEY "your_anthropic_key"
+setx OPENROUTER_API_KEY "your_openrouter_key"
+```
+
+Close PowerShell completely and open a new window before starting Buzl. `setx` stores the value for your Windows user account, so treat the computer account as sensitive.
+
+### macOS and Linux
+
+Add the required key to your shell profile. Use `~/.zshrc` for the usual macOS shell or `~/.bashrc` for Bash:
+
+```bash
+export ANTHROPIC_API_KEY="your_anthropic_key"
+export OPENROUTER_API_KEY="your_openrouter_key"
+```
+
+Reload the relevant profile before starting Buzl:
+
+```bash
+source ~/.zshrc
+# or
+source ~/.bashrc
+```
+
+Global operating-system variables take priority over a website's `.env` file. Use a website-root `.env` only when a specific client requires a separate key. Keep `.env` out of Git and hosting uploads.
+
+## 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-Advanced.pdf](./docs/Buzl-HTML-Editor-Handbook-Advanced.pdf)
+
 ## Requirements
 
 - Node.js 18 or newer
@@ -29,8 +34,20 @@ 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 the small floating
+**pencil** button to open the Buzl menu, then select **Edit Text** to edit
+visible text directly on any page. Use **Save**, **Undo**, or **Cancel** from
+the compact menu. 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 +69,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 +123,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,189 @@
+:host {
+  all: initial;
+}
+
+.buzl-toolbar {
+  align-items: flex-end;
+  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-direction: column-reverse;
+  font: 600 13px/1.2 Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  gap: 0;
+  max-width: calc(100vw - 32px);
+  padding: 7px;
+  position: fixed;
+  right: 18px;
+  transition: width 210ms ease;
+  width: 56px;
+  z-index: 2147483647;
+}
+
+.buzl-toolbar[data-expanded="true"] {
+  width: min(242px, calc(100vw - 32px));
+}
+
+.buzl-toolbar .buzl-launcher {
+  align-items: center;
+  background: #d4af37;
+  border-color: #d4af37;
+  color: #211717;
+  font-size: 22px;
+  font-weight: 700;
+  height: 42px;
+  justify-content: center;
+  min-height: 42px;
+  padding: 0;
+  transition: background 160ms ease, color 160ms ease, transform 180ms ease;
+  width: 42px;
+}
+
+.buzl-toolbar .buzl-launcher:hover {
+  background: #ebca5b;
+  color: #211717;
+}
+
+.buzl-toolbar[data-expanded="true"] .buzl-launcher {
+  transform: rotate(-12deg);
+}
+
+.buzl-toolbar .buzl-menu {
+  align-items: stretch;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  flex-wrap: nowrap;
+  gap: 8px;
+  max-height: 0;
+  opacity: 0;
+  overflow: hidden;
+  pointer-events: none;
+  transform: translateY(8px) scale(0.98);
+  transform-origin: bottom right;
+  transition: max-height 210ms ease, opacity 170ms ease, padding-top 210ms ease, transform 210ms ease;
+  width: 100%;
+}
+
+.buzl-toolbar[data-expanded="true"] .buzl-menu {
+  max-height: 300px;
+  opacity: 1;
+  padding-top: 8px;
+  pointer-events: auto;
+  transform: translateY(0) scale(1);
+}
+
+.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 .buzl-menu button,
+.buzl-toolbar .buzl-menu a {
+  justify-content: center;
+  width: 100%;
+}
+
+.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;
+  box-sizing: border-box;
+  max-width: none;
+  overflow: hidden;
+  padding: 0 5px;
+  text-overflow: ellipsis;
+  text-align: center;
+  white-space: normal;
+  width: 100%;
+}
+
+.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: auto;
+    right: 10px;
+  }
+
+  .buzl-toolbar[data-expanded="true"] {
+    left: 10px;
+    width: min(242px, calc(100vw - 20px));
+  }
+
+  .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;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .buzl-toolbar .buzl-launcher,
+  .buzl-toolbar .buzl-menu {
+    transition: none;
+  }
+}