@sleekcms/sync 4.3.0 → 4.5.0

package/README.md

@@ -398,7 +398,7 @@ Models describe the shape of your content. They're JSON-like files with unquoted
 **Forms** (no backend needed)
 
 ```html
-<form data-sleekcms="contact">
+<form data-sleeksite-form="Contact">
   <input name="name" type="text" required>
   <input name="email" type="email" required>
   <textarea name="message"></textarea>
@@ -406,7 +406,7 @@ Models describe the shape of your content. They're JSON-like files with unquoted
 </form>
 ```
 
-Any form with `data-sleekcms="<name>"` captures and stores submissions in the CMS dashboard automatically. File uploads work out of the box too — add an `<input type="file">` and visitors can attach documents (PDF, Word, Excel, CSV, text) and images:
+Any form with `data-sleeksite-form="<name>"` captures and stores submissions in the CMS dashboard automatically (`data-sleeksite-book` makes it a booking form with a slot picker). On sync the form is created if it doesn't exist and the CMS stores the view with the name replaced by the form's key, so the published form stays linked when it's renamed in the app; your local file keeps the name as you wrote it. File uploads work out of the box too — add an `<input type="file">` and visitors can attach documents (PDF, Word, Excel, CSV, text) and images:
 
 ```html
 <input name="resume" type="file" accept=".pdf">
@@ -420,7 +420,7 @@ Content lives in `src/content/` as plain JSON. Edit any content file and save
 
 ## Site setup (`src/setup.json`)
 
-Site-wide decisions made once — the default page title, whether Tailwind is compiled, whether a sitemap is published, the cookie consent switch, the chat bot switch, and analytics tag ids — live in `src/setup.json`, mirrored from **Settings → Website** in the CMS. The file is JSON with a comment above each key explaining it:
+Site-wide decisions made once — the default page title, whether Tailwind is compiled, whether a sitemap is published, the cookie consent switch, the chat bot switch and how the chat opens, and analytics tag ids — live in `src/setup.json`, mirrored from **Settings → Website** in the CMS. The file is JSON with a comment above each key explaining it:
 
 ```json5
 {
@@ -429,6 +429,7 @@ Site-wide decisions made once — the default page title, whether Tailwind is co
   sitemap_enabled: false,   // publish sitemap.xml + robots.txt on every build
   cookie_consent: false,    // consent banner; holds analytics + data-sleekcms-consent scripts until accepted
   chat_enabled: false,      // chat bot on every page, answering from the site's published pages
+  chat_mode: "POPUP",       // how the chat opens: "POPUP", "SIDEBAR" or "SPOTLIGHT" (any case accepted)
   analytics: {              // tag ids injected into every page; include only the ones you use
     ga4: "G-XXXXXXXXXX",
   },

package/dist/AGENTS.md

@@ -102,7 +102,7 @@ content/entries/<key>.json      Content for a single entry (object)
 content/entries/<key>+.json     Collection entry — ONE file holding a JSON array of all items
 content/images.json             Site-level reusable images: handle → shortcut (§7)
 content/videos.json             Site-level videos: handle → pexels:/pixabay: ref (user uploads show as embed_url) (§7)
-content/files.json              The site's files (Media > Files), read-only: handle → { file, name, url } (§7)
+content/files.json              The site's files (Media > Files), read-only: file name → { file, url, size } (§7)
 
 setup.json                      Site setup (JSON, comments allowed): default page title, Tailwind on/off, sitemap on/off, cookie consent on/off, analytics tag ids — edit values in place, never delete
 ```
@@ -125,6 +125,7 @@ setup.json                      Site setup (JSON, comments allowed): default pag
 | `sitemap_enabled` | boolean | `true` publishes `sitemap.xml` + `robots.txt` on every build. Turn it on for public sites and SEO work. Which pages are *excluded* is a CMS UI setting (Manage Site > Search Visibility), never this file. |
 | `cookie_consent` | boolean | `true` injects a consent banner into every page and holds the analytics tags, plus any script or iframe tagged `data-sleekcms-consent`, until the visitor accepts its category. A toggle only — banner text, position and styling are authored in HTML (§14). |
 | `chat_enabled` | boolean | `true` adds the chat bot to every published page; it answers visitor questions from the site's published pages (re-read on every publish). A toggle only — the welcome message, knowledge files and instructions are managed in the CMS. `false` removes it from the next publish and stops open chats right away. |
+| `chat_mode` | string | How the chat opens when a visitor clicks its launcher: `"POPUP"` (default, a small panel in the corner), `"SIDEBAR"` (a full-height panel docked right, over the page) or `"SPOTLIGHT"` (a centred search-style dialog). Any case is accepted and saved uppercase. On phones sidebar and spotlight open full screen. Changes with the next publish. A page can override it: `data-sleek-chat="sidebar"` (or `"spotlight"`, `"popup"`) on any button or link opens chat in that mode, and `--sleek-chat-mode` in the site's CSS sets it per page or breakpoint. |
 | `analytics` | object | Marketing/analytics tag ids injected into every published page. |
 
 `analytics` is a flat map — include only the keys the site uses:
@@ -249,7 +250,7 @@ Like JSON but with **no quotes**; each value is a field type name:
 | `image` | Shortcut string (preferred when writing) or resolved `{ "url", "alt" }` object — see §7. Shortcuts only resolve in `image`/`icon` fields — in a `text` field the string stays literal text |
 | `icon` | Svg icon. Use for icons the user is expected to edit/swap in the CMS (e.g. features/services). Fill with placeholder `"iconify:<prefix:name or search>"` (or `"cms:<handle>"` pointing at an svg); render with `svg(item.icon)`. Fixed UI icons don't need fields — call `svg('iconify:...')` directly in templates |
 | `video` | Ref string (preferred when writing) or the resolved object you read back. Write `"cms:<handle>"` to reuse a video from `content/videos.json` (or a user upload by its handle), or `"pexels:<search>\|<title>"` / `"pixabay:<search>\|<title>"` for a one-off — resolved server-side (see §7). **Never invent** `video_id`/`embed_url` objects; render with `embed()` only |
-| `file` | Write a plain file name, e.g. `"brochure.pdf"` (pdf, docx, xlsx, pptx, csv, tsv, txt, md — no path, no URL, never an object). A listed file's handle from `content/files.json` works too, and wins over a file with that name. On save the CMS attaches that file, or (for a file name nothing matches) creates a small placeholder file the user replaces in the CMS UI; reads back as the file name. Render a link with `item.x.url` / `item.x.name` |
+| `file` | Write a plain file name, e.g. `"brochure.pdf"` (pdf, docx, xlsx, pptx, csv, tsv, txt, md — no path, no URL, never an object). A file listed in `content/files.json` is written by its listed name (`"forms/booking.docx"` for one in a folder). On save the CMS attaches that file, or (for a file name nothing matches) creates a small placeholder file the user replaces in the CMS UI; reads back as the file name. Render a link with `item.x.url` / `item.x.name` |
 | `json` | Any JSON |
 | `sheet` | Array of arrays |
 | `location` | `{ "markers": [{ "lat", "lng" }], "img": "<google static map url>" }` — `img` supports Google Static Maps params; markers are already part of the URL |
@@ -362,18 +363,18 @@ Content `video` fields accept the same refs: `"cms:<handle>"` reuses a declared
 
 ### Files
 
-`content/files.json` lists the site's files (Media > Files) as `handle → { file, name, url }`: `file` is the file name, `name` its display name, `url` its public download link.
+`content/files.json` lists the site's files (Media > Files) as `file name → { file, url, size }`: `file` is the value a `file` field takes, `url` the path the site serves it at, `size` its bytes.
 
 ```json
-{ "lunch-menu": { "file": "lunch-menu.pdf", "name": "Lunch Menu", "url": "https://files.sleekcms.com/…/lunch-menu.pdf" } }
+{ "lunch-menu.pdf": { "file": "lunch-menu.pdf", "url": "/_files/lunch-menu.pdf", "size": 48213 } }
 ```
 
 It's read-only: edits to it are never saved, and every sync replaces it with the site's current list. Check it before writing a new file name.
 
-A `file` field takes a listed handle (`"lunch-menu"`) or file name (`"lunch-menu.pdf"`). Render a file no field points at with `getFile(handle)`, which returns the same `{ name, url, size, type, ext }` as a `file` field (or `undefined` for an unknown handle):
+A `file` field takes a listed file name (`"lunch-menu.pdf"`). Render a file no field points at with `getFile(name)`, which returns the same `{ name, url, size, type, ext }` as a `file` field (or `undefined` for an unknown name):
 
 ```ejs
-<% const menu = getFile('lunch-menu') %>
+<% const menu = getFile('lunch-menu.pdf') %>
 <% if (menu) { %><a href="<%= menu.url %>" download><%= menu.name %></a><% } %>
 ```
 
@@ -391,7 +392,7 @@ node upload.mjs menu-v2.pdf --name lunch-menu.pdf    # store it under another fi
 ```
 
 - **Images** (png, jpg, jpeg, webp, gif, svg, ico, up to 8 MB) become site images under a handle. The handle is `--handle`, or by default the file name lowercased and dashed (`Team Photo.jpg` → `team-photo`). The script adds the handle to `content/images.json`. Reference the image as `"cms:<handle>"` in any `image` field, or with `img('cms:<handle>')` / `src('cms:<handle>')` in a view. Uploading to an existing handle replaces that image everywhere it's used.
-- **Documents** (pdf, docx, xlsx, pptx, csv, tsv, txt, md, up to 10 MB) are added to Media > Files under their file name, and `content/files.json` is rewritten to list them. Put the printed file name (or its handle) in a `file` field, or render it with `getFile('<handle>')`. Uploading the same file name again replaces that file.
+- **Documents** (pdf, docx, xlsx, pptx, csv, tsv, txt, md, up to 10 MB) are added to Media > Files under their file name, and `content/files.json` is rewritten to list them. Put the printed file name in a `file` field, or render it with `getFile('<file name>')`. Uploading the same file name again replaces that file.
 - The script prints the ref to use for each file. Copy it from the output rather than guessing it, because the server cleans up file names. Add `--json` for one JSON result per line. Exit code `0` means every file uploaded, `1` means some failed (the reason is printed), and `2` means it couldn't run.
 - Uploading needs an EDITOR or ADMIN on the site.
 - Never copy images or documents into `src/`. Binary files there are not synced; the sync log just points you back to `upload.mjs`.
@@ -472,7 +473,7 @@ There is exactly **one** layout: `layouts/common.ejs`. It wraps every page autom
 | `getSlugs(path)` | string[] | Slugs under a collection path |
 | `getImage(handle)` | Object \| undefined | Resolved image from `images.json` (bare handle, no `cms:` prefix) |
 | `getVideo(handle)` | Object \| undefined | Video from `videos.json` as `{ title, source, video_id, embed_url }` — render with `embed()` |
-| `getFile(handle)` | Object \| undefined | File from `files.json` as `{ name, url, size, type, ext }`, like a `file` field |
+| `getFile(name)` | Object \| undefined | File from `files.json` by its name, as `{ name, url, size, type, ext }`, like a `file` field |
 | `getContent(query?)` | Any | Full content payload, optionally filtered with JMESPath |
 | `path(page)` | String | URL path of a page object |
 | `url(pathOrPage?)` | String | Site origin; pass a path or page object for a full absolute URL |
@@ -572,10 +573,10 @@ Three site-level SEO settings live in `setup.json` (§4), not in views: `sitemap
 
 ## 10. Forms
 
-Any `<form>` with `data-sleekcms="<hardcoded name>"` works automatically — submissions are captured and shown in the CMS dashboard. No backend, no action URL, no JS.
+Any `<form>` with `data-sleeksite-form="<name>"` works automatically — submissions are captured and shown in the CMS dashboard. No backend, no action URL, no JS.
 
 ```html
-<form data-sleekcms="contact">
+<form data-sleeksite-form="Contact">
   <input name="name" type="text" required>
   <input name="email" type="email" required>
   <textarea name="message"></textarea>
@@ -583,7 +584,7 @@ Any `<form>` with `data-sleekcms="<hardcoded name>"` works automatically — sub
 </form>
 ```
 
-The `data-sleekcms` value groups submissions by form; each input's `name` is stored as-is. Add an `<input type="datetime-local">` and the form becomes a **booking form** — see §11.
+Write the form's **name** (e.g. `Contact`, `Newsletter`, `Quote request`), literally — never a template expression. On sync the form is created if it doesn't exist, and the CMS stores the view with the name replaced by the form's key (e.g. `data-sleeksite-form="mh3k2x9a"`), so the published form stays linked when the user renames it in the app. Your local file keeps the name as you wrote it. A key you find in a view is the form's id: keep it as it is. Each input's `name` is stored as-is.
 
 **File uploads** are supported out of the box — add an `<input type="file">` and visitors can attach documents (PDF, Word, Excel, CSV, text) and images (add `multiple` for several):
 
@@ -591,25 +592,27 @@ The `data-sleekcms` value groups submissions by form; each input's `name` is sto
 <input name="resume" type="file" accept=".pdf,.doc,.docx">
 ```
 
+For visitors to **book a time**, use `data-sleeksite-book` instead — see §11. A walk-in queue's "Schedule a time" form uses `data-sleeksite-queue="<queue name>"` (fields `queue_date`, an empty `<select name="queue_time">`, `name`, `email`) and goes to the queue, not the inbox; the queue is created on sync, with the same name-to-key rule as forms.
+
 ## 11. Bookings
 
 Use this whenever visitors should **book or schedule** something — an appointment, a call, a demo, a consultation, a class, or a reservation ("pick a time / reserve a slot"). It fits appointment-based businesses: salon, spa, barber, dental/medical clinic, therapist, tutor, photographer, consultant, repair shop, restaurant reservations. **Only add a booking form when the business genuinely takes appointments and the user asks for it (or it is clearly core to the business) — never add one speculatively to an arbitrary site.**
 
-**A booking is just a form.** Give a normal `data-sleekcms` form an `<input type="datetime-local">` — at publish time that input is replaced by an availability slot picker, and submissions become appointments with email confirmation, calendar invites, and no-login cancel/reschedule. Every other field is yours: bookings store arbitrary fields, exactly like form submissions.
+**A booking is just a form** with `data-sleeksite-book="<name>"` instead of `data-sleeksite-form` — on the page it gets an availability slot picker, and submissions become appointments with email confirmation, calendar invites, and no-login cancel/reschedule. Every other field is yours: bookings store arbitrary fields, exactly like form submissions.
 
 ```html
-<form data-sleekcms="consultation">
+<form data-sleeksite-book="Consultation">
   <input name="name" type="text" required placeholder="Your name">
   <input name="email" type="email" required placeholder="Email">
-  <input name="slot" type="datetime-local" required>
+  <div data-sleeksite-slot></div>
   <textarea name="notes" placeholder="Anything we should know?"></textarea>
   <button type="submit">Book appointment</button>
 </form>
 ```
 
-Rules: **include an email field** (`type="email"` or `name="email"`) — confirmation and manage links go there; the datetime input's own `name` doesn't matter (it is replaced by the picker, and the chosen time is stored as the booking's slot); style the form like any other — the picker inherits the page's `--accent` CSS variable (or set `data-accent` on the form).
+Rules: **include an email field** (`type="email"` or `name="email"`) — confirmation and manage links go there; the picker goes where an element with `data-sleeksite-slot` (or an `<input type="datetime-local">`) is, and replaces it — without one it goes just before the submit button, and the chosen time is stored as the booking's slot; style the form like any other — the picker inherits the page's `--accent` CSS variable (or set `data-accent` on the form).
 
-The form named `consultation` is **auto-created on sync** like any form, and because it has a datetime input it gets default availability: 30-minute slots, one booking at a time, Mon–Fri 9 AM–5 PM in America/New_York, bookings confirmed instantly (email-confirmation off — the owner can require it in settings). The defaults are guesses — tell the user to review the timezone and open hours in the form's **Booking settings** (Customers › Inbox); appointments appear under **Customers › Bookings**. Reusing the same name across pages shares one booking form.
+The form named `Consultation` is **auto-created on sync** like any form (the same name-to-key rule as §10 applies), and as a booking form it gets default availability: 30-minute slots, one booking at a time, Mon–Fri 9 AM–5 PM in America/New_York, bookings confirmed instantly (email-confirmation off — the owner can require it in settings). The defaults are guesses — tell the user to review the timezone and open hours in the form's **Booking settings** (Customers › Inbox); appointments appear under **Customers › Bookings**. Reusing the same name (or key) across pages shares one booking form. The visitor's confirm and manage links open pages on the site's own domain (`/_book/…`) — nothing to build.
 
 ## 12. RSS Feeds
 

package/dist/upload.mjs

@@ -268,8 +268,18 @@ export async function uploadOne(opts) {
     const ext = extOf(name);
     if (TEXT_FILE_EXTS.includes(ext) && data.length <= MAX_INLINE_TEXT_BYTES) body.content = data.toString("utf-8");
     const created = await api(base, token, "POST", "/create_asset", body, fetchImpl);
-    if (created.upload) await sendBytes(created.upload, data, fetchImpl);
-    writeFilesIndex(ws, created.files);
+    let files = created.files;
+    if (created.upload) {
+        await sendBytes(created.upload, data, fetchImpl);
+        // The listing create_asset returned predates the bytes (a new file is only
+        // listed once stored), so ask again now that they are.
+        try {
+            files = await api(base, token, "GET", "/get_files?kind=files", undefined, fetchImpl);
+        } catch {
+            // keep the earlier listing; the next sync pull corrects it
+        }
+    }
+    writeFilesIndex(ws, files);
     return {
         source: filePath,
         type: "file",
@@ -277,7 +287,7 @@ export async function uploadOne(opts) {
         handle: created.handle || undefined,
         replaced: !!created.replaces_existing,
         url: created.url || undefined,
-        indexed: !!(created.files || []).some((f) => f.path === FILES_INDEX),
+        indexed: !!(files || []).some((f) => f.path === FILES_INDEX),
     };
 }
 
@@ -290,7 +300,7 @@ export function describe(r) {
         return lines;
     }
     const lines = [`✅ ${r.replaced ? "Replaced" : "Uploaded"} file ${path.basename(r.source)} → "${r.ref}"${r.url ? ` (${r.url})` : ""}`];
-    lines.push(`   Use "${r.ref}"${r.handle ? ` (or its handle "${r.handle}")` : ""} as a file field's value, or getFile('${r.handle || r.ref}') in a view.`);
+    lines.push(`   Use "${r.ref}" as a file field's value, or getFile('${r.ref}') in a view.`);
     return lines;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sleekcms/sync",
-    "version": "4.3.0",
+    "version": "4.5.0",
     "description": "Edit SleekCMS sites locally — models, content, templates, images — with live two-way sync and AI agent support.",
     "keywords": [
         "sleekcms",