# MaxiMind Study Board — embed & integration spec

Study Board is a self-hosted collaborative whiteboard (Excalidraw) at https://draw.macsvff.uk.
Embed it in any web page with a single <iframe>. Boards are EPHEMERAL: a blank board lives
only in the browser and is discarded when the page/iframe closes. Nothing is saved server-side.

This file is written to be handed to an AI assistant. Give it this URL
(https://maximind.macsvff.uk/study-board.txt) or paste this text, then ask it to embed the
board into your classroom page.

## 1. Base URLs & parameters
- Blank board:      https://draw.macsvff.uk
- Live shared room: https://draw.macsvff.uk/#room=ROOM_ID,ROOM_KEY
- ROOM_ID:  20 lowercase hex characters (0-9a-f)
- ROOM_KEY: 22-char base64url string = a 128-bit AES-GCM key. It is an END-TO-END
            encryption key: the server relays the drawing but cannot read it.

## 2. Minimal embed (blank, ephemeral)
<iframe src="https://draw.macsvff.uk"
        title="Study Board"
        style="width:100%; height:600px; border:0; border-radius:12px"
        allow="clipboard-read; clipboard-write; fullscreen"
        referrerpolicy="no-referrer"
        loading="lazy"></iframe>

## 3. Sizing & responsive rules (IMPORTANT so it "looks good")
The board is a full application, not a thumbnail. Give it real space.
- Minimum usable size: width >= 360px, height >= 420px (below that the toolbar crowds).
- Recommended desktop height: 600px, or min(80vh, 820px).
- Recommended mobile height: min(70vh, 560px), never below 420px.
- Width: always 100% of the parent container.
- Set width/height once; do NOT animate them.
- The board pans/scrolls INTERNALLY. The host page must not try to scroll the iframe.

Responsive shape with aspect-ratio:
<div style="width:100%; aspect-ratio:16/10; min-height:420px">
  <iframe src="https://draw.macsvff.uk"
          style="width:100%; height:100%; border:0; border-radius:12px"
          allow="clipboard-read; clipboard-write; fullscreen"
          referrerpolicy="no-referrer" loading="lazy"></iframe>
</div>

## 4. Fill a container / REPLACE the current classroom board
Make the classroom's board slot position:relative, then let the iframe absolutely fill it.
This swaps in the Study Board while keeping the slot's existing size.
<div style="position:relative; width:100%; height:100%; min-height:480px">
  <iframe src="https://draw.macsvff.uk"
          style="position:absolute; inset:0; width:100%; height:100%; border:0"
          allow="clipboard-read; clipboard-write; fullscreen"
          referrerpolicy="no-referrer"></iframe>
</div>

If the current classroom board is already an <iframe>, the simplest replacement is to change
its src to https://draw.macsvff.uk (blank) or a room URL (shared). Keep the existing size.

JS drop-in (replace an element with id="classroom-board"):
const slot = document.getElementById('classroom-board');
const f = document.createElement('iframe');
f.src = 'https://draw.macsvff.uk';
f.title = 'Study Board';
f.setAttribute('allow', 'clipboard-read; clipboard-write; fullscreen');
f.setAttribute('referrerpolicy', 'no-referrer');
f.style.cssText = 'width:100%;height:100%;min-height:480px;border:0;border-radius:12px';
slot.replaceChildren(f);

## 5. One board per class (Vietlingo / online classroom)
For a shared class board, give everyone the SAME room URL. Each class = one unique room.
Rooms are ephemeral (gone when everyone leaves). Mint a fresh room URL in the browser
(this matches Excalidraw's own format exactly):
async function newStudyBoardRoom() {
  const id = [...crypto.getRandomValues(new Uint8Array(10))]
             .map(b => b.toString(16).padStart(2, '0')).join('');
  const key = await crypto.subtle.generateKey({ name: 'AES-GCM', length: 128 }, true, ['encrypt','decrypt']);
  const jwk = await crypto.subtle.exportKey('jwk', key);
  return 'https://draw.macsvff.uk/#room=' + id + ',' + jwk.k;
}
// Use the returned URL as the iframe src for that class. Reuse it during the lesson to keep
// the same board; generate a new one to start fresh. For a solo or throwaway board, just use
// the blank URL https://draw.macsvff.uk (every iframe is its own independent board).

## 6. Framework snippets
### React / JSX
<iframe
  src="https://draw.macsvff.uk"
  title="Study Board"
  allow="clipboard-read; clipboard-write; fullscreen"
  referrerPolicy="no-referrer"
  loading="lazy"
  style={{ width: '100%', height: 600, border: 0, borderRadius: 12 }}
/>
### Bubble.io   -> add an HTML element, paste the section-2 iframe.
### WordPress   -> add a "Custom HTML" block, paste the section-2 iframe.

## 7. iframe attribute reference
- allow="clipboard-read; clipboard-write; fullscreen"  paste images, copy shapes, go fullscreen
- referrerpolicy="no-referrer"                          don't leak the host page URL
- loading="lazy"                                         defer load if below the fold (use eager if it is the main content)
- style border:0                                         remove the default iframe border
- Do NOT sandbox unless you also add: allow-scripts allow-same-origin allow-popups allow-modals
  (the board needs scripts and same-origin to run).

## 8. Ready-to-use AI prompt
Embed the MaxiMind Study Board (https://draw.macsvff.uk) into my classroom page. Requirements:
responsive, fills the classroom board area (replace the current board), looks good on desktop
and mobile (min height 480px), ephemeral. For a shared class board, mint a unique
#room=ID,KEY URL per class using the snippet in section 5. Follow the sizing rules in section 3.
Full spec: https://maximind.macsvff.uk/study-board.txt

## Notes
- Ephemeral: closing the page discards a blank board; a room is gone when everyone leaves.
- The board's REST persistence API (https://draw.macsvff.uk/api/v2) is separate and currently
  open. You do NOT need it to embed. It only matters if you want to SAVE a board to a link.