domma-cms 0.102.1 → 0.103.0

package/plugins/_lib/public/call/call.js

@@ -0,0 +1,468 @@
+/**
+ * The call page - a video call in the browser, on the site itself.
+ *
+ * Mounts on every `[data-dm-call]` element. Its JSON config:
+ *
+ *   {api, room, cred: {t|key|h: '…'}, title, name?, askName?}
+ *
+ *   api   the Tool's call API (e.g. /api/plugins/booking-pro/call)
+ *   room  the room id the Tool gave the link
+ *   cred  what the link carried; posted with the join, the Tool decides who you are
+ *
+ * The screen is domma-reactive (M) - stages, controls, people waiting, chat -
+ * and plain code only where bindings cannot reach: the <video> elements'
+ * streams, the recording canvas, and the RTCPeerConnections themselves.
+ * Browsers connect to each other directly (a mesh - up to 6 people); the
+ * site only passes the messages that set that up (see _lib/call/routes.js).
+ * Every piece of text goes in through bindings (textContent), never as HTML.
+ */
+
+const M = window.M;
+
+const TEMPLATE = `
+<div class="dmc">
+  <header class="dmc-head">
+    <h1 class="dmc-title" data-bind-text="title.value"></h1>
+    <span class="dmc-rec" data-bind-hidden="!recording.value" role="status">● Recording</span>
+    <span class="dmc-count" data-bind-text="countText.value"></span>
+  </header>
+
+  <section class="dmc-panel" data-bind-hidden="stage.value !== 'check'">
+    <div class="dmc-preview"><video class="dmc-self-preview" muted playsinline autoplay></video>
+      <p class="dmc-nocam" data-bind-hidden="camOn.value">Camera off</p></div>
+    <div class="dmc-check">
+      <h2>Ready to join?</h2>
+      <p class="dmc-note" data-bind-text="deviceNote.value"></p>
+      <label class="dmc-label" data-bind-hidden="!askName">Your name
+        <input class="dmc-input" data-model="name.value" maxlength="60" autocomplete="name"></label>
+      <div class="dmc-row">
+        <button type="button" class="dmc-btn" data-on-click="toggleMic" data-bind-class="!micOn.value && 'is-off'" data-bind-text="micOn.value ? 'Mic on' : 'Mic off'"></button>
+        <button type="button" class="dmc-btn" data-on-click="toggleCam" data-bind-class="!camOn.value && 'is-off'" data-bind-text="camOn.value ? 'Camera on' : 'Camera off'"></button>
+      </div>
+      <p class="dmc-note" data-bind-hidden="!recordingAllowed.value">The host may record this call. You will see a red Recording notice while they do.</p>
+      <p class="dmc-error" data-bind-hidden="!error.value" data-bind-text="error.value" role="alert"></p>
+      <button type="button" class="dmc-btn dmc-btn--go" data-on-click="join" data-bind-disabled="busy.value">Join the call</button>
+    </div>
+  </section>
+
+  <section class="dmc-panel dmc-panel--msg" data-bind-hidden="stage.value !== 'waiting'">
+    <h2>Waiting for the host</h2><p>They know you are here and will let you in shortly.</p>
+    <button type="button" class="dmc-btn" data-on-click="leave">Leave</button>
+  </section>
+
+  <section class="dmc-panel dmc-panel--msg" data-bind-hidden="!(stage.value === 'ended' || stage.value === 'away' || stage.value === 'error')">
+    <h2 data-bind-text="endTitle.value"></h2><p data-bind-text="endText.value"></p>
+  </section>
+
+  <section class="dmc-call" data-bind-hidden="stage.value !== 'in'">
+    <div class="dmc-main" data-bind-data-people="people.value">
+      <div class="dmc-grid">
+        <figure class="dmc-tile dmc-tile--me"><video class="dmc-self" muted playsinline autoplay></video>
+          <figcaption data-bind-text="meCaption.value"></figcaption></figure>
+      </div>
+      <div class="dmc-remote" data-each="peers key=id">
+        <figure class="dmc-tile" data-bind-data-peer="id"><video class="dmc-video" playsinline autoplay></video>
+          <figcaption data-bind-text="caption.value"></figcaption></figure>
+      </div>
+    </div>
+
+    <aside class="dmc-side" data-bind-hidden="!(sideOpen.value || waiting.value.length)">
+      <div class="dmc-waiting" data-bind-hidden="!waiting.value.length">
+        <h3>Waiting to join</h3>
+        <ul data-each="waiting key=id">
+          <li><span data-bind-text="name"></span>
+            <button type="button" class="dmc-btn dmc-btn--small dmc-btn--go" data-on-click="$parent.admit($data)">Let in</button>
+            <button type="button" class="dmc-btn dmc-btn--small" data-on-click="$parent.turnAway($data)">Turn away</button></li>
+        </ul>
+      </div>
+      <div class="dmc-chat" data-bind-hidden="!sideOpen.value">
+        <h3>Chat</h3>
+        <ol class="dmc-messages" data-each="messages key=id">
+          <li data-bind-class="mine && 'is-mine'"><strong data-bind-text="name"></strong> <span data-bind-text="text"></span></li>
+        </ol>
+        <form class="dmc-send" data-on-submit="sendChat">
+          <input class="dmc-input" data-model="draft.value" maxlength="1000" placeholder="Message everyone" aria-label="Message everyone">
+          <button type="submit" class="dmc-btn dmc-btn--small">Send</button>
+        </form>
+      </div>
+    </aside>
+
+    <nav class="dmc-bar" aria-label="Call controls">
+      <button type="button" class="dmc-btn" data-on-click="toggleMic" data-bind-class="!micOn.value && 'is-off'" data-bind-text="micOn.value ? 'Mute' : 'Unmute'"></button>
+      <button type="button" class="dmc-btn" data-on-click="toggleCam" data-bind-class="!camOn.value && 'is-off'" data-bind-text="camOn.value ? 'Stop video' : 'Start video'"></button>
+      <button type="button" class="dmc-btn" data-on-click="toggleShare" data-bind-hidden="!canShare" data-bind-text="sharing.value ? 'Stop sharing' : 'Share screen'"></button>
+      <button type="button" class="dmc-btn" data-on-click="toggleSide" data-bind-text="chatLabel.value"></button>
+      <button type="button" class="dmc-btn dmc-btn--rec" data-on-click="toggleRecord" data-bind-hidden="!(host.value && recordingAllowed.value && canRecord)" data-bind-text="iRecord.value ? 'Stop recording' : 'Record'"></button>
+      <button type="button" class="dmc-btn dmc-btn--leave" data-on-click="leave">Leave</button>
+    </nav>
+  </section>
+</div>`;
+
+function mount(el) {
+    let cfg;
+    try { cfg = JSON.parse(el.getAttribute('data-dm-call') || '{}'); } catch { cfg = {}; }
+    if (!M || !cfg.api || !cfg.room) { el.textContent = 'This call page could not start.'; return; }
+
+    // ---- State the screen shows -------------------------------------------------------
+    const stage = M.observable('check');                // check | waiting | in | ended | away | error
+    const name = M.observable(cfg.name || '');
+    const micOn = M.observable(true);
+    const camOn = M.observable(true);
+    const sharing = M.observable(false);
+    const recording = M.observable(false);               // someone (the host) is recording
+    const iRecord = M.observable(false);                 // this browser is recording
+    const recordingAllowed = M.observable(cfg.recordingAllowed === true);
+    const host = M.observable(false);
+    const busy = M.observable(false);
+    const error = M.observable('');
+    const deviceNote = M.observable('Checking your camera and microphone…');
+    const sideOpen = M.observable(false);
+    const unread = M.observable(0);
+    const draft = M.observable('');
+    const peers = M.observableArray([]);                 // {id, name, host, caption: observable}
+    const waiting = M.observableArray([]);               // {id, name}
+    const messages = M.observableArray([]);              // {id, name, text, mine}
+    const ended = M.observable({title: 'You have left the call', text: 'You can close this page.'});
+    const max = M.observable(6);
+
+    const endTitle = M.computed(() => ended.value.title);
+    const endText = M.computed(() => ended.value.text);
+    const meCaption = M.computed(() => `${name.value || 'You'} (you)${micOn.value ? '' : ' · muted'}`);
+    const countText = M.computed(() => (stage.value === 'in' ? `${peers.value.length + 1} of ${max.value}` : ''));
+    const people = M.computed(() => String(Math.min(6, peers.value.length + 1)));
+    const chatLabel = M.computed(() => (sideOpen.value ? 'Hide chat' : unread.value ? `Chat (${unread.value})` : 'Chat'));
+    const title = M.observable(cfg.title || 'Call');
+
+    // ---- The connection to the site ---------------------------------------------------
+    let me = null;                                       // {id, secret}
+    let since = 0;
+    let polling = false;
+    const headers = () => ({'Content-Type': 'application/json', 'X-Call-Id': me?.id || '', 'X-Call-Secret': me?.secret || ''});
+    const url = (p) => `${cfg.api}/${encodeURIComponent(cfg.room)}/${p}`;
+    const post = (p, body = {}, extra = {}) => fetch(url(p), {method: 'POST', headers: headers(), body: JSON.stringify(body), ...extra});
+
+    // ---- Media -------------------------------------------------------------------------
+    let local = null;                                    // the camera + mic stream
+    let screen = null;
+    let iceServers = [];
+    const pcs = new Map();                               // peer id -> {pc, polite, makingOffer, ignore, stream}
+
+    const selfVideos = () => el.querySelectorAll('.dmc-self, .dmc-self-preview');
+    const showSelf = () => selfVideos().forEach(v => { v.srcObject = screen || local; });
+
+    async function getDevices() {
+        try {
+            local = await navigator.mediaDevices.getUserMedia({video: {width: {ideal: 1280}, height: {ideal: 720}}, audio: true});
+            deviceNote.value = 'Your camera and microphone are working.';
+        } catch {
+            try {
+                local = await navigator.mediaDevices.getUserMedia({audio: true});
+                camOn.value = false;
+                deviceNote.value = 'No camera found, or it is blocked - you can still join with your microphone.';
+            } catch {
+                local = new MediaStream();
+                camOn.value = false;
+                micOn.value = false;
+                deviceNote.value = 'Your camera and microphone are blocked or missing. You can join and use the chat; allow them in your browser to be seen and heard.';
+            }
+        }
+        showSelf();
+    }
+    const setTracks = () => {
+        local?.getAudioTracks().forEach(t => { t.enabled = micOn.value; });
+        local?.getVideoTracks().forEach(t => { t.enabled = camOn.value; });
+    };
+
+    // ---- Peer connections (perfect negotiation) ----------------------------------------
+    function connect(peer) {
+        if (pcs.has(peer.id)) return pcs.get(peer.id);
+        const pc = new RTCPeerConnection({iceServers});
+        const entry = {pc, polite: me.id > peer.id, makingOffer: false, ignore: false, stream: new MediaStream(), chain: Promise.resolve()};
+        pcs.set(peer.id, entry);
+        const out = screen ? [...(local?.getAudioTracks() || []), ...screen.getVideoTracks()] : (local?.getTracks() || []);
+        out.forEach(track => pc.addTrack(track, local));
+        pc.ontrack = (e) => { entry.stream.addTrack(e.track); attach(); if (e.track.kind === 'audio') addToMix(e.track); };
+        pc.onicecandidate = (e) => { if (e.candidate) post('signal', {to: peer.id, data: {candidate: e.candidate}}); };
+        pc.onnegotiationneeded = async () => {
+            try {
+                entry.makingOffer = true;
+                await pc.setLocalDescription();
+                post('signal', {to: peer.id, data: {description: pc.localDescription}});
+            } catch (err) { console.warn('[call] offer:', err?.message || err); } finally { entry.makingOffer = false; }
+        };
+        pc.onconnectionstatechange = () => {
+            const row = peers.value.find(p => p.id === peer.id);
+            if (row) row.caption.value = captionFor(row, pc.connectionState);
+            if (pc.connectionState === 'failed') pc.restartIce?.();
+        };
+        return entry;
+    }
+    const captionFor = (p, state) => `${p.name}${p.host ? ' (host)' : ''}${state === 'failed' ? ' · can’t connect' : state === 'connecting' || state === 'new' ? ' · connecting…' : ''}`;
+
+    /**
+     * One peer's messages are applied strictly in order: a candidate that
+     * arrives while the offer before it is still being applied would otherwise
+     * be refused and lost, and the call would never connect.
+     */
+    function onSignal(from, data) {
+        const peer = peers.value.find(p => p.id === from);
+        if (!peer) return;
+        const entry = connect(peer);
+        entry.chain = entry.chain.then(() => applySignal(entry, from, data));
+    }
+
+    async function applySignal(entry, from, data) {
+        const {pc} = entry;
+        try {
+            if (data.description) {
+                const collision = data.description.type === 'offer' && (entry.makingOffer || pc.signalingState !== 'stable');
+                entry.ignore = !entry.polite && collision;
+                if (entry.ignore) return;
+                await pc.setRemoteDescription(data.description);
+                if (data.description.type === 'offer') {
+                    await pc.setLocalDescription();
+                    post('signal', {to: from, data: {description: pc.localDescription}});
+                }
+            } else if (data.candidate) {
+                try { await pc.addIceCandidate(data.candidate); } catch (err) { if (!entry.ignore) throw err; }
+            }
+        } catch (err) { console.warn('[call] negotiation:', err?.message || err); /* the tile shows "can't connect" */ }
+    }
+
+    function dropPeer(id) {
+        pcs.get(id)?.pc.close();
+        pcs.delete(id);
+        const row = peers.value.find(p => p.id === id);
+        if (row) peers.remove(row);
+    }
+
+    /** Give each remote tile its stream (bindings cannot set srcObject). */
+    function attach() {
+        requestAnimationFrame(() => {
+            el.querySelectorAll('.dmc-remote [data-peer]').forEach(fig => {
+                const entry = pcs.get(fig.getAttribute('data-peer'));
+                const video = fig.querySelector('video');
+                if (entry && video && video.srcObject !== entry.stream) video.srcObject = entry.stream;
+            });
+        });
+    }
+    const stopAttach = M.effect(() => { peers.value; attach(); });
+
+    // ---- Events from the site ----------------------------------------------------------
+    function addPeer(p) {
+        if (p.id === me.id || peers.value.some(x => x.id === p.id)) return;
+        const row = {id: p.id, name: p.name, host: p.host, caption: M.observable('')};
+        row.caption.value = captionFor(row, 'new');
+        peers.push(row);
+        connect(row);
+    }
+
+    function handle(e) {
+        if (!me) return;   // the call ended part-way through a batch of events
+        switch (e.type) {
+            case 'knocking': stage.value = 'waiting'; break;
+            case 'admitted':
+                stage.value = 'in';
+                recording.value = e.recording === true;
+                (e.peers || []).forEach(addPeer);
+                showSelf();
+                break;
+            case 'joined': addPeer(e.peer); break;
+            case 'left': dropPeer(e.id); break;
+            case 'signal': onSignal(e.from, e.data || {}); break;
+            case 'waiting': waiting.value = (e.waiting || []).map(w => ({id: w.id, name: w.name})); break;
+            case 'chat':
+                messages.push({id: `${e.seq}`, name: e.name, text: e.text, mine: e.from === me.id});
+                if (!sideOpen.value && e.from !== me.id) unread.value += 1;
+                requestAnimationFrame(() => { const list = el.querySelector('.dmc-messages'); if (list) list.scrollTop = list.scrollHeight; });
+                break;
+            case 'recording': recording.value = e.on === true; break;
+            case 'turned-away': finish('away', 'The host did not let you in', 'You can close this page.'); break;
+            case 'ended': finish('ended', 'The call has ended', 'You can close this page.'); break;
+            default: break;
+        }
+    }
+
+    async function pollLoop() {
+        if (polling) return;
+        polling = true;
+        while (me && !['ended', 'away', 'error'].includes(stage.value)) {
+            try {
+                const r = await fetch(`${url('poll')}?since=${since}`, {headers: headers(), cache: 'no-store'});
+                if (r.status === 410) { finish('ended', 'You are no longer in the call', 'Your connection dropped for too long. Reload the page to join again.'); break; }
+                if (!r.ok) { await pause(2000); continue; }
+                const {events = []} = await r.json();
+                for (const e of events) { since = Math.max(since, e.seq); handle(e); }
+            } catch {
+                await pause(2000);
+            }
+        }
+        polling = false;
+    }
+    const pause = (ms) => new Promise(r => setTimeout(r, ms));
+
+    function finish(kind, title, text) {
+        ended.value = {title, text};
+        stage.value = kind;
+        stopRecording();
+        for (const id of [...pcs.keys()]) dropPeer(id);
+        [local, screen].forEach(s => s?.getTracks().forEach(t => t.stop()));
+        me = null;
+    }
+
+    // ---- Recording (host, in this browser; the file is downloaded here) ----------------
+    let recorder = null;
+    let recordTimer = null;
+    let audioCtx = null;
+    let mix = null;
+    /** Someone's audio reaching us while we record (a late joiner) goes into the recording too. */
+    function addToMix(track) {
+        if (!audioCtx || !mix) return;
+        try { audioCtx.createMediaStreamSource(new MediaStream([track])).connect(mix); } catch { /* ended already */ }
+    }
+    const canRecord = typeof MediaRecorder !== 'undefined' && typeof HTMLCanvasElement.prototype.captureStream === 'function';
+
+    function startRecording() {
+        const canvas = document.createElement('canvas');
+        canvas.width = 1280; canvas.height = 720;
+        const g = canvas.getContext('2d');
+        recordTimer = setInterval(() => {
+            const videos = [...el.querySelectorAll('.dmc-call video')].filter(v => v.srcObject && v.videoWidth);
+            g.fillStyle = '#111'; g.fillRect(0, 0, 1280, 720);
+            const n = Math.max(1, videos.length);
+            const cols = Math.ceil(Math.sqrt(n));
+            const rows = Math.ceil(n / cols);
+            const w = 1280 / cols; const h = 720 / rows;
+            videos.forEach((v, i) => {
+                const scale = Math.min(w / v.videoWidth, h / v.videoHeight);
+                const vw = v.videoWidth * scale; const vh = v.videoHeight * scale;
+                g.drawImage(v, (i % cols) * w + (w - vw) / 2, Math.floor(i / cols) * h + (h - vh) / 2, vw, vh);
+            });
+        }, 1000 / 15);
+        audioCtx = new AudioContext();
+        mix = audioCtx.createMediaStreamDestination();
+        [local, ...[...pcs.values()].map(e => e.stream)].forEach(s => s?.getAudioTracks().forEach(addToMix));
+        const stream = new MediaStream([...canvas.captureStream(15).getVideoTracks(), ...mix.stream.getAudioTracks()]);
+        const chunks = [];
+        const type = ['video/webm;codecs=vp9,opus', 'video/webm;codecs=vp8,opus', 'video/webm'].find(t => MediaRecorder.isTypeSupported?.(t)) || '';
+        recorder = new MediaRecorder(stream, type ? {mimeType: type} : undefined);
+        recorder.ondataavailable = (e) => { if (e.data.size) chunks.push(e.data); };
+        recorder.onstop = () => {
+            const blob = new Blob(chunks, {type: 'video/webm'});
+            const a = document.createElement('a');
+            a.href = URL.createObjectURL(blob);
+            a.download = `call-${new Date().toISOString().slice(0, 16).replace(/[:T]/g, '-')}.webm`;
+            a.click();
+            setTimeout(() => URL.revokeObjectURL(a.href), 60000);
+        };
+        recorder.start(1000);
+        iRecord.value = true;
+    }
+    function stopRecording() {
+        clearInterval(recordTimer); recordTimer = null;
+        if (recorder && recorder.state !== 'inactive') recorder.stop();
+        recorder = null;
+        audioCtx?.close(); audioCtx = null; mix = null;
+        iRecord.value = false;
+    }
+
+    // ---- What the buttons do -------------------------------------------------------------
+    const model = {
+        title, people, chatLabel, askName: cfg.askName !== false, canShare: Boolean(navigator.mediaDevices?.getDisplayMedia), canRecord,
+        stage, name, micOn, camOn, sharing, recording, iRecord, recordingAllowed, host, busy, error, deviceNote, sideOpen, unread,
+        draft, peers, waiting, messages, endTitle, endText, meCaption, countText,
+
+        toggleMic() { micOn.value = !micOn.value; setTracks(); },
+        toggleCam() {
+            if (!local?.getVideoTracks().length) { error.value = 'No camera is available.'; return; }
+            camOn.value = !camOn.value; setTracks();
+        },
+        toggleSide() { sideOpen.value = !sideOpen.value; if (sideOpen.value) unread.value = 0; },
+
+        async join() {
+            error.value = '';
+            if (model.askName && !name.value.trim()) { error.value = 'Your name, please - the others will see it.'; return; }
+            busy.value = true;
+            try {
+                const r = await fetch(url('join'), {method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({name: name.value.trim(), ...(cfg.cred || {})})});
+                const body = await r.json().catch(() => ({}));
+                if (r.status === 425 && body.opensAt) { error.value = `This call opens at ${new Date(body.opensAt).toLocaleTimeString([], {hour: '2-digit', minute: '2-digit'})}. Come back then.`; return; }
+                if (!r.ok) { error.value = body.error || 'Could not join the call.'; return; }
+                me = {id: body.id, secret: body.secret};
+                iceServers = body.iceServers || [];
+                host.value = body.host === true;
+                if (body.name) name.value = body.name;
+                max.value = body.max || 6;
+                recordingAllowed.value = body.recordingAllowed === true;
+                if (body.title) title.value = body.title;
+                stage.value = body.state === 'in' ? 'in' : 'waiting';
+                since = 0;
+                pollLoop();
+            } catch {
+                error.value = 'Could not reach the site. Check your connection and try again.';
+            } finally { busy.value = false; }
+        },
+
+        async leave() {
+            if (me) post('leave', {}, {keepalive: true});
+            finish('ended', 'You have left the call', 'You can close this page.');
+        },
+
+        admit(w) { post('answer', {who: w.id, yes: true}); },
+        turnAway(w) { post('answer', {who: w.id, yes: false}); },
+
+        sendChat() {
+            const text = draft.value.trim();
+            if (text && me) post('chat', {text});
+            draft.value = '';
+            return false;
+        },
+
+        async toggleShare() {
+            // Each connection's video sender: the camera's, or one added for a screen when there was no camera
+            // (remembered, so sharing again reuses it rather than adding another).
+            const videoSender = (entry) => entry.pc.getSenders().find(s => s.track?.kind === 'video') || entry.videoSender || null;
+            if (sharing.value) {
+                screen?.getTracks().forEach(t => t.stop());
+                screen = null;
+                sharing.value = false;
+                const cam = local?.getVideoTracks()[0] || null;
+                pcs.forEach(entry => videoSender(entry)?.replaceTrack(cam));
+                showSelf();
+                return;
+            }
+            try {
+                screen = await navigator.mediaDevices.getDisplayMedia({video: true});
+                const track = screen.getVideoTracks()[0];
+                track.onended = () => { if (sharing.value) model.toggleShare(); };
+                sharing.value = true;
+                pcs.forEach(entry => {
+                    const sender = videoSender(entry);
+                    if (sender) sender.replaceTrack(track);
+                    else entry.videoSender = entry.pc.addTrack(track, screen);
+                });
+                showSelf();
+            } catch { /* cancelled the picker */ }
+        },
+
+        async toggleRecord() {
+            if (!host.value) return;
+            if (iRecord.value) {
+                stopRecording();
+                post('recording', {on: false});
+                return;
+            }
+            const r = await post('recording', {on: true});
+            if (!r.ok) { error.value = (await r.json().catch(() => ({}))).error || 'Recording is not allowed here.'; return; }
+            startRecording();
+        }
+    };
+
+    el.innerHTML = TEMPLATE;
+    const handleBindings = M.applyBindings(model, el.firstElementChild);
+    window.addEventListener('pagehide', () => { if (me) post('leave', {}, {keepalive: true}); });
+    getDevices().then(setTracks);
+    return () => { stopAttach?.(); handleBindings?.dispose?.(); };
+}
+
+document.querySelectorAll('[data-dm-call]').forEach(mount);

package/plugins/booking/CLAUDE.md

@@ -0,0 +1,123 @@
+# booking - AI Assistant Guide
+
+## Purpose
+
+Appointments and resources booked from the site. 1.0.0 (2026-09-30): people (appointments with you or your team)
+and resources (rooms, equipment) with weekly hours, days off and business-wide closed days; services with a length,
+buffers before and after, a start step, notice and how far ahead; a public booking page at a configurable address
+(`/booking`) and the `[booking /]` shortcode; confirmation, reminder and owner emails with an .ics; a private link for
+the customer to move or cancel within the notice; a Diary (day / week), a Bookings list, Services and People & rooms
+in the admin; a sidebar badge for bookings still to come today.
+
+Links to other Tools, each absent when that Tool is: customers become contacts (the booked person's address book,
+else the settings' owner, else whoever booked); "Book {name}…" on a contact's menu and a Bookings panel on the
+contact card (core `registerRelatedItems('contact')`); "Book {name}…" on an email's menu in Email / Mail Reader
+(core 0.103 `registerRelatedItems('message')`; an older core ignores it); a Bookings calendar source; a person's own
+Calendar events block their times (read from `calendar-occurrences` / `calendar-events` through the collections
+service - no import of the Calendar, which is a separate paid Tool).
+
+`tier: free`, ships with the engine, disabled on arrival. Plan and phases: `dcms-marketplace/docs/booking-plan.md`.
+Booking Pro (not yet built) is an ADD-ON that registers into this one (`lib/extensions.js`), the Cart / Cart Pro
+pattern - it does not supersede it. Payment is Pro only.
+
+1.3.0 (2026-09-30): online bookings (plan: `dcms-marketplace/docs/online-meetings-plan.md`). An extension's
+`rules()` may say `online` (+ `recordingAllowed`); `placeBooking` then stores `online: true`, `hostKey`,
+`recordingAllowed` ON THE BOOKING, so Booking (free) serves the call for it even after Pro lapses. `lib/call.js`:
+a room is a SESSION (`sessionOf` = service + start + person, so a class shares one call), `whoIsCalling` (customer
+token -> guest, host key -> host, only while HOLDING, window 10 min before to 60 after). The engine is core's
+`_lib/call` (dynamic import - an older core has no calls); routes at `/call/...`, page at `<bookingPath>/call/<session>
+?b=&t=|h=` (plugin.public.js). Emails: customer's main button becomes "Join the call" (change/cancel moves into the
+text), the owner's copy gets "Start the call"; .ics LOCATION/DESCRIPTION carry the join link. `adminBooking` swaps
+`hostKey` for `hostUrl`; `publicBooking` adds `online`, `callUrl`. Staff-made bookings still do not email the owner.
+
+1.2.0 (2026-09-30): an email's sender who is already one of the caller's contacts is booked AS that contact:
+`GET /contact?email=` (`contactByEmail`, main address or Contacts Pro `emails[]`) fills the slideover (the
+sender's own address kept). Without a `contactId`, `POST /bookings` leaves it to `linkContact`, which already finds
+the booked person's (else the caller's) contact by email - never the caller's for someone else's booking.
+
+1.1.0 (2026-09-30): extension points for Booking Pro - see "Extensions" below. The slot engine now knows places (a
+class), companions (a booking that also holds a room), and a daily limit, all OFF unless an extension's `rules`
+turn them on; bookings carry `holds` (every bookable they block, first = `bookableId`) and `alsoNames`.
+
+## The one rule about time
+
+Bookings are UTC instants (`startAt`, `endAt`, and the span they BLOCK, `blockStart` / `blockEnd`, buffers
+included - stored, so changing a service's buffers never moves what existing bookings hold). Opening hours, days
+off and everything a person reads are the business's wall clock in `settings.timeZone`. `public/lib/time.js` is the
+only place one becomes the other (`wallClock`, `atWallClock`; Intl, no library; DST-tested: a skipped time is never
+offered, a repeated one is the first). Never build a Date from a date string and a time string anywhere else.
+
+## The one rule about clashes
+
+`public/lib/slots.js` `slotsFor` decides what is free - the page, the admin and the server all ask it, and
+`lib/store.js` `placeBooking` checks AGAIN inside `withLock` before writing. The public `POST /public/book` also
+requires the time to be one the page would offer (in range, on the service's steps, in hours). Staff may book over a
+clash with `force: true` after a 409 (`code: 'slot-taken'`). Statuses that hold time: pending, confirmed,
+completed, no-show (`HOLDING`); cancelled frees it.
+
+## Files
+
+- `plugin.json`, `config.js` (every setting, documented), `plugin.js` (API, shortcode, emails, reminders, links)
+- `plugin.public.js` - the booking pages from ONE onRequest hook on the LIVE `bookingPath` (moving it needs no
+  restart): `<base>`, `<base>/<service-slug>`, `<base>/manage/<id>?t=<token>`.
+- `public/lib/time.js`, `slots.js`, `clean.js` - PURE, shared by server, admin and page (public/ is served; lib/ is not).
+- `lib/store.js` - collections I/O, live settings, `withLock`, `placeBooking` / `changeBooking`, Calendar busy time,
+  contact linking. `shelfNow` / `settingsNow` for the synchronous shortcode.
+- `lib/mail.js` - one way out (copied from Waypoint Pro): never throws, not sent without SMTP (`mailReady()`),
+  `setMailer()` for tests; `icsFor` (stable UID per booking, SEQUENCE = history length, CANCEL on cancel).
+- `lib/extensions.js` - the registry (`globalThis[Symbol.for('domma.booking')]`): `on` {made, moved, cancelled,
+  status}, `tabs`, and `registry.services` (Booking's data functions, `sendReminders`).
+- `admin/` - the Tool (tab host `admin/views/booking.js`), `templates/` + `public/booking.js|css` - the page.
+- `public/booking.js` - the page in the browser: domma-reactive (`window.M`, Domma is on every public page) - one
+  template holding every step (shown by `data-bind-hidden` on `step`), one `M.applyBindings`; plain code only fetches,
+  writes observables, and moves focus / scroll. Without `window.M` the server's page is left as it is.
+- `docs/guide.md` - the user guide in the admin Documentation folder.
+- `tests/pure.test.js` (time, slots, cleaning), `tests/api.test.js` (the whole API against the real collection
+  service; restores config/plugins.json and contacts-contacts), `tests/public.test.js` (the page's paths).
+
+## Data
+
+Collections `booking-bookables`, `booking-services`, `booking-bookings` (made at every boot if missing; API access
+all off - bookings hold customers' details). Settings: `config/plugins.json` `booking.settings`.
+
+A booking: `serviceId`, `serviceName`, `duration`, `bookableId`, `bookableName`, `startAt`, `endAt`, `blockStart`,
+`blockEnd`, `status`, `name`, `email`, `phone`, `notes`, `staffNote`, `contactId`, `source` (public | admin),
+`createdBy`, `token` (the customer's link; never sent to the admin), `reminderSentAt`, `history` [{at, what, by,
+from?, reason?}], `cancelledAt`, `ext` (Pro's). Services and bookables carry `ext` too (Pro's fields, kept by the
+free Tool untouched).
+
+## Extensions (Booking Pro)
+
+`bookingRegistry()` (`lib/extensions.js`, `version: 2`): `register(owner, {rules, form, answers, check, admin, waitlistUrl,
+on, tabs})` - every hook optional and guarded (one that throws counts as absent). `rules(service)` ->
+{capacity, companions: [[ids]], maxPerDay, waitlist}, resolved to bookable objects by `registry.rules(service,
+bookables)` and applied by `slotsFor` / `whoCanTake` / `placeBooking` (same session = same service + start +
+primary bookable: shares places, never clashes with itself; a day's limit counts sessions). `form` / `answers`: extra
+questions on the page, cleaned into `ext.answers` (errors come back as `errors['answers.<id>']`). `check(ctx)`: a
+reason refuses a public booking (409 `code: 'refused'`). `admin`: section modules mounted in Booking's own
+slideovers (service editor, new booking, booking panel) - the contract is in `admin/lib/extension-sections.js`.
+`registry.services`: Booking's data functions plus `book()` (the whole flow: contacts, emails, notices, events; throws
+SlotTaken with `code: 'slot-taken'`), `cancel()`, `mail` {send, compose, mailReady}, `time` helpers and
+`timeZone()` - so an extension never imports Booking's files. Without an extension every service is plain; existing
+bookings keep blocking what they hold.
+
+## Emails
+
+Customer: confirmation (setting), moved, cancelled, reminder (`reminderHours` before; not for a booking made inside
+that window - its confirmation was the reminder), with "Change or cancel" while `customerMayChange`. Owner copy: the
+booked person's email, else `notifyAddress`, else the site's. Staff changes email the customer only when the
+admin's "email the customer" box is ticked (`notify`). Reminders: a 5-minute `setInterval` (unref'd, cleared on
+close) - no engine scheduler exists. Without SMTP nothing is sent; the settings slideover says so.
+
+## Permissions
+
+`booking` (read = see, manage = change), granted to admin; admins give it to other roles in Users & Roles. The
+contact and email "Book…" actions carry `permission: {resource: 'booking', action: 'manage'}`, so core shows them
+only to roles that hold it.
+
+## Gotchas
+
+- Add `return reply.send(...)` / return a value in every async route (compressed responses come back empty).
+- `siteBase()` uses `site.baseUrl` when set, else the last request's origin (emails from reminders have no request).
+- The API tests create contacts in domma-cms's `content/collections/contacts-contacts/data.json` (tracked) - they
+  snapshot and restore it; a crashed run can leave it changed: `git checkout` it in domma-cms.