Add bead separator support to Rosary Builder

- Bead Markers section in library panel with Small, Large, Crucifix cards
- Bead steps render as amber-tinted cards in the sequence (no attribution)
- migrate_v5.php: adds step_type/bead_type columns, makes prayer_id nullable
- Bead steps produce slides with proper bead+bead_index so the ring advances
  during presentation — allows participants to follow along on physical beads
- Prayer steps between beads still show bead_index=null (ring stays on last bead)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

admin/builder.php

@@ -33,12 +33,12 @@ if (isset($_GET['id'])) {
     }
     // Load steps with prayer data
     $step_stmt = $pdo->prepare("
-        SELECT bs.prayer_id, bs.attribution,
+        SELECT bs.step_type, bs.bead_type, bs.prayer_id, bs.attribution,
                cp.name, cp.leader_text, cp.all_text, cp.is_global, cp.created_by,
                IF(cp.is_global=1 AND u.role='superadmin','standard',
                   IF(cp.is_global=1,'global','mine')) AS source_tag
         FROM   builder_steps bs
-        JOIN   custom_prayers cp ON cp.id = bs.prayer_id
+        LEFT   JOIN custom_prayers cp ON cp.id = bs.prayer_id
         LEFT   JOIN users u ON u.id = cp.created_by
         WHERE  bs.session_id = ?
         ORDER  BY bs.step_order ASC
@@ -168,6 +168,37 @@ $page_title = $session ? 'Edit: ' . htmlspecialchars($session['name']) : 'Rosary
                         <button class="tab-btn" data-tab="mine">My Prayers</button>
                     </div>
                 </div>
+                <!-- Bead markers — always visible, not filtered by search/tab -->
+                <div class="bead-markers-section">
+                    <div class="bead-markers-label">Bead Markers</div>
+                    <div class="bead-marker-cards">
+                        <button class="bead-marker-card" onclick="builderAddBead('small')">
+                            <span class="bead-icon-sm">&#x25CB;</span>
+                            <span class="bead-card-text">
+                                <strong>Small Bead</strong>
+                                <small>Hail Mary</small>
+                            </span>
+                            <span class="bead-add-label">+ Add</span>
+                        </button>
+                        <button class="bead-marker-card" onclick="builderAddBead('large')">
+                            <span class="bead-icon-lg">&#x25CF;</span>
+                            <span class="bead-card-text">
+                                <strong>Large Bead</strong>
+                                <small>Our Father</small>
+                            </span>
+                            <span class="bead-add-label">+ Add</span>
+                        </button>
+                        <button class="bead-marker-card" onclick="builderAddBead('crucifix')">
+                            <span class="bead-icon-cx">&#x271D;</span>
+                            <span class="bead-card-text">
+                                <strong>Crucifix</strong>
+                                <small>Cross bead</small>
+                            </span>
+                            <span class="bead-add-label">+ Add</span>
+                        </button>
+                    </div>
+                </div>
+
                 <div id="prayer-list">
                     <div class="library-empty" style="grid-column:1/-1;padding:40px;text-align:center;color:var(--muted)">
                         Loading…
@@ -255,8 +286,10 @@ var IS_ADMIN         = <?= $is_admin ? 'true' : 'false' ?>;
 var EDIT_SESSION_ID  = <?= $session ? (int)$session['id'] : 'null' ?>;
 var PRAYERS_DATA     = <?= json_encode(array_values($prayers_data)) ?>;
 var EXISTING_STEPS   = <?= json_encode(array_map(fn($s) => [
-    'prayer_id'   => (int)$s['prayer_id'],
-    'attribution' => $s['attribution'],
+    'step_type'   => $s['step_type'] ?? 'prayer',
+    'bead_type'   => $s['bead_type'] ?? null,
+    'prayer_id'   => $s['prayer_id'] ? (int)$s['prayer_id'] : null,
+    'attribution' => $s['attribution'] ?? 'leader_all',
 ], $edit_steps)) ?>;
 </script>
 <script src="<?= BASE_URL ?>/assets/js/builder.js?v=1"></script>

api/builder_session.php

@@ -49,28 +49,40 @@ if ($name === '') json_err('Session name is required');
 if (empty($steps)) json_err('Add at least one prayer to your sequence');
 
 $valid_attributions = ['leader_all', 'leader_only', 'all_only', 'none'];
+$valid_bead_types   = ['small', 'large', 'crucifix'];
 
-// Validate steps
+// Validate steps and collect prayer IDs to verify
+$prayer_ids = [];
 foreach ($steps as $i => $step) {
-    $pid = (int)($step['prayer_id'] ?? 0);
-    $att = $step['attribution'] ?? 'leader_all';
-    if (!$pid) json_err("Step " . ($i + 1) . " is missing a prayer");
-    if (!in_array($att, $valid_attributions)) json_err("Invalid attribution on step " . ($i + 1));
+    $type = $step['step_type'] ?? 'prayer';
+    if ($type === 'bead') {
+        if (!in_array($step['bead_type'] ?? '', $valid_bead_types)) {
+            json_err("Invalid bead type on step " . ($i + 1));
+        }
+    } else {
+        $pid = (int)($step['prayer_id'] ?? 0);
+        $att = $step['attribution'] ?? 'leader_all';
+        if (!$pid) json_err("Step " . ($i + 1) . " is missing a prayer");
+        if (!in_array($att, $valid_attributions)) json_err("Invalid attribution on step " . ($i + 1));
+        $prayer_ids[] = $pid;
+    }
 }
 
 // Verify all prayer_ids exist and are accessible
-$prayer_ids = array_unique(array_column($steps, 'prayer_id'));
-$in_placeholders = implode(',', array_fill(0, count($prayer_ids), '?'));
-$valid_stmt = $pdo->prepare("
-    SELECT id FROM custom_prayers
-    WHERE id IN ($in_placeholders)
-      AND (is_global = 1 OR created_by = ?)
-");
-$valid_stmt->execute([...$prayer_ids, $uid]);
-$valid_ids = array_column($valid_stmt->fetchAll(), 'id');
-foreach ($prayer_ids as $pid) {
-    if (!in_array((string)$pid, array_map('strval', $valid_ids))) {
-        json_err("Prayer ID {$pid} not found or not accessible");
+if (!empty($prayer_ids)) {
+    $prayer_ids = array_unique($prayer_ids);
+    $in_placeholders = implode(',', array_fill(0, count($prayer_ids), '?'));
+    $valid_stmt = $pdo->prepare("
+        SELECT id FROM custom_prayers
+        WHERE id IN ($in_placeholders)
+          AND (is_global = 1 OR created_by = ?)
+    ");
+    $valid_stmt->execute([...$prayer_ids, $uid]);
+    $valid_ids = array_column($valid_stmt->fetchAll(), 'id');
+    foreach ($prayer_ids as $pid) {
+        if (!in_array((string)$pid, array_map('strval', $valid_ids))) {
+            json_err("Prayer ID {$pid} not found or not accessible");
+        }
     }
 }
 
@@ -111,11 +123,16 @@ try {
 
     // Insert steps
     $step_stmt = $pdo->prepare(
-        "INSERT INTO builder_steps (session_id, step_order, prayer_id, attribution)
-         VALUES (?, ?, ?, ?)"
+        "INSERT INTO builder_steps (session_id, step_type, bead_type, step_order, prayer_id, attribution)
+         VALUES (?, ?, ?, ?, ?, ?)"
     );
     foreach ($steps as $order => $step) {
-        $step_stmt->execute([$session_id, $order, (int)$step['prayer_id'], $step['attribution']]);
+        $type = $step['step_type'] ?? 'prayer';
+        if ($type === 'bead') {
+            $step_stmt->execute([$session_id, 'bead', $step['bead_type'], $order, null, 'none']);
+        } else {
+            $step_stmt->execute([$session_id, 'prayer', null, $order, (int)$step['prayer_id'], $step['attribution']]);
+        }
     }
 
     $pdo->commit();

assets/css/builder.css

@@ -439,6 +439,97 @@
     margin-top: 2px;
 }
 
+/* ── Bead markers section ────────────────────────────────────── */
+
+.bead-markers-section {
+    padding: 10px 16px 8px;
+    border-bottom: 1px solid var(--border);
+    background: var(--bg-card);
+    flex-shrink: 0;
+}
+
+.bead-markers-label {
+    font-size: 10px;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: .06em;
+    color: var(--muted);
+    margin-bottom: 8px;
+}
+
+.bead-marker-cards {
+    display: flex;
+    gap: 8px;
+}
+
+.bead-marker-card {
+    flex: 1;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 8px 10px;
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    background: var(--bg);
+    cursor: pointer;
+    font-family: var(--font);
+    font-size: 12px;
+    text-align: left;
+    transition: border-color .15s, background .15s;
+}
+
+.bead-marker-card:hover {
+    border-color: var(--primary);
+    background: #eff6ff;
+}
+
+.bead-icon-sm { font-size: 18px; color: #6b7280; flex-shrink: 0; line-height: 1; }
+.bead-icon-lg { font-size: 20px; color: #374151; flex-shrink: 0; line-height: 1; }
+.bead-icon-cx { font-size: 18px; color: var(--gold); flex-shrink: 0; line-height: 1; }
+
+.bead-card-text {
+    display: flex;
+    flex-direction: column;
+    flex: 1;
+    min-width: 0;
+}
+
+.bead-card-text strong { font-size: 12px; font-weight: 600; color: var(--text); }
+.bead-card-text small  { font-size: 10px; color: var(--muted); }
+
+.bead-add-label {
+    font-size: 11px;
+    color: var(--primary);
+    font-weight: 600;
+    flex-shrink: 0;
+}
+
+/* ── Bead step card (in sequence list) ───────────────────────── */
+
+.step-card.bead-step {
+    background: #fefce8;
+    border-color: #fde68a;
+}
+
+.step-card.bead-step:hover {
+    border-color: #f59e0b;
+}
+
+.bead-step-name {
+    font-size: 13px;
+    font-weight: 600;
+    color: #92400e;
+    display: flex;
+    align-items: center;
+    gap: 6px;
+}
+
+.bead-step-sub {
+    font-size: 11px;
+    color: #b45309;
+    margin-top: 2px;
+}
+
 /* ── Library footer ──────────────────────────────────────────── */
 
 .library-footer {

assets/js/builder.js

@@ -23,8 +23,12 @@
         // Populate existing steps when editing a session
         if (window.EXISTING_STEPS && window.EXISTING_STEPS.length) {
             window.EXISTING_STEPS.forEach(function (s) {
-                const prayer = PRAYERS.find(p => String(p.id) === String(s.prayer_id));
-                if (prayer) STEPS.push({ prayer_id: s.prayer_id, attribution: s.attribution, _prayer: prayer });
+                if (s.step_type === 'bead') {
+                    STEPS.push({ step_type: 'bead', bead_type: s.bead_type });
+                } else {
+                    const prayer = PRAYERS.find(p => String(p.id) === String(s.prayer_id));
+                    if (prayer) STEPS.push({ step_type: 'prayer', prayer_id: s.prayer_id, attribution: s.attribution, _prayer: prayer });
+                }
             });
         }
 
@@ -146,8 +150,30 @@
             return;
         }
 
+        const beadMeta = {
+            small:    { icon: '○', label: 'Small Bead',  sub: 'Hail Mary bead' },
+            large:    { icon: '●', label: 'Large Bead',  sub: 'Our Father bead' },
+            crucifix: { icon: '✝', label: 'Crucifix',    sub: 'Cross bead' },
+        };
+
         list.innerHTML = STEPS.map(function (step, i) {
-            const p         = step._prayer;
+            const moveUp   = `<button class="btn-icon" title="Move up"   onclick="builderMove(${i},-1)" ${i===0?'disabled':''}>↑</button>`;
+            const moveDn   = `<button class="btn-icon" title="Move down" onclick="builderMove(${i}, 1)" ${i===STEPS.length-1?'disabled':''}>↓</button>`;
+            const remove   = `<button class="btn-icon remove" title="Remove" onclick="builderRemove(${i})">✕</button>`;
+
+            if (step.step_type === 'bead') {
+                const m = beadMeta[step.bead_type] || beadMeta.small;
+                return `<div class="step-card bead-step">
+                    <div class="step-num">${i + 1}</div>
+                    <div class="step-body">
+                        <div class="bead-step-name">${m.icon} ${m.label}</div>
+                        <div class="bead-step-sub">${m.sub}</div>
+                    </div>
+                    <div class="step-actions">${moveUp}${moveDn}${remove}</div>
+                </div>`;
+            }
+
+            const p          = step._prayer;
             const leaderPrev = (p.leader_text || '').replace(/\n/g, ' ').substring(0, 60);
             const allPrev    = (p.all_text    || '').replace(/\n/g, ' ').substring(0, 60);
 
@@ -164,11 +190,7 @@
                         <option value="none"        ${step.attribution==='none'        ? 'selected':''}>No attribution</option>
                     </select>
                 </div>
-                <div class="step-actions">
-                    <button class="btn-icon" title="Move up"    onclick="builderMove(${i}, -1)" ${i===0 ? 'disabled' : ''}>↑</button>
-                    <button class="btn-icon" title="Move down"  onclick="builderMove(${i},  1)" ${i===STEPS.length-1 ? 'disabled' : ''}>↓</button>
-                    <button class="btn-icon remove" title="Remove" onclick="builderRemove(${i})">✕</button>
-                </div>
+                <div class="step-actions">${moveUp}${moveDn}${remove}</div>
             </div>`;
         }).join('');
     }
@@ -176,6 +198,18 @@
     /* ─────────────────────────────────────────────────────────
        Step manipulation (exposed globally)
     ───────────────────────────────────────────────────────── */
+    window.builderAddBead = function (beadType) {
+        STEPS.push({ step_type: 'bead', bead_type: beadType });
+        renderSequence();
+        const cards = document.querySelectorAll('#step-list .step-card');
+        const last  = cards[cards.length - 1];
+        if (last) {
+            last.style.outline = '2px solid #f59e0b';
+            setTimeout(() => { last.style.outline = ''; }, 800);
+            last.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+        }
+    };
+
     window.builderAddPrayer = function (prayerId) {
         const prayer = PRAYERS.find(p => String(p.id) === String(prayerId));
         if (!prayer) return;
@@ -186,7 +220,7 @@
         else if (!prayer.all_text) attr = 'leader_only';
         else if (!prayer.leader_text) attr = 'all_only';
 
-        STEPS.push({ prayer_id: prayerId, attribution: attr, _prayer: prayer });
+        STEPS.push({ step_type: 'prayer', prayer_id: prayerId, attribution: attr, _prayer: prayer });
         renderSequence();
         // Briefly highlight the new step
         const list = document.getElementById('step-list');
@@ -381,7 +415,9 @@
             subject_name:     document.getElementById('subject-name').value.trim(),
             subject_pronoun:  document.getElementById('subject-pronoun').value,
             subject_dates:    document.getElementById('subject-dates').value.trim(),
-            steps:            STEPS.map(s => ({ prayer_id: s.prayer_id, attribution: s.attribution })),
+            steps: STEPS.map(s => s.step_type === 'bead'
+                ? { step_type: 'bead', bead_type: s.bead_type }
+                : { step_type: 'prayer', prayer_id: s.prayer_id, attribution: s.attribution }),
         };
 
         const btn = document.getElementById('btn-save');

includes/build_slides.php

@@ -15,9 +15,10 @@ require_once __DIR__ . '/../data/prayers.php';
  */
 function get_builder_steps(PDO $pdo, int $session_id): array {
     $st = $pdo->prepare("
-        SELECT bs.attribution, cp.name, cp.leader_text, cp.all_text
+        SELECT bs.step_type, bs.bead_type, bs.attribution,
+               cp.name, cp.leader_text, cp.all_text
         FROM   builder_steps bs
-        JOIN   custom_prayers cp ON cp.id = bs.prayer_id
+        LEFT   JOIN custom_prayers cp ON cp.id = bs.prayer_id
         WHERE  bs.session_id = ?
         ORDER  BY bs.step_order ASC
     ");
@@ -104,8 +105,25 @@ function build_slides(array $session): array {
             'photo_path' => $session['photo_path'] ?? null,
         ];
 
+        $bead_idx = 0; // increments for each bead separator step
         foreach ($steps as $i => $step) {
-            $attr   = $step['attribution'];
+            $type = $step['step_type'] ?? 'prayer';
+
+            if ($type === 'bead') {
+                $slides[] = [
+                    'id'         => 'bead_' . $i,
+                    'type'       => 'prayer',
+                    'section'    => 'bead',
+                    'title'      => '',
+                    'leader'     => '',
+                    'all'        => '',
+                    'bead'       => $step['bead_type'] ?? 'small',
+                    'bead_index' => $bead_idx++,
+                ];
+                continue;
+            }
+
+            $attr   = $step['attribution'] ?? 'leader_all';
             $leader = '';
             $all    = '';
 
@@ -116,7 +134,6 @@ function build_slides(array $session): array {
                 $all = $step['all_text'] ?? '';
             }
             if ($attr === 'none') {
-                // Show prayer text without attribution labels — put in leader field
                 $leader = ($step['leader_text'] ?: $step['all_text']) ?? '';
             }
 

migrate_v5.php

@@ -0,0 +1,67 @@
+<?php
+/**
+ * migrate_v5.php — Adds step_type and bead_type columns to builder_steps
+ * for bead separator support. Makes prayer_id nullable.
+ * Run once in browser, then delete.
+ */
+require_once __DIR__ . '/config/db.php';
+$pdo = get_pdo();
+$log = [];
+
+function mig5_sql(PDO $pdo, string $label, string $sql, array &$log): void {
+    try {
+        $pdo->exec($sql);
+        $log[] = ['ok', $label];
+    } catch (PDOException $e) {
+        if (in_array($e->errorInfo[1], [1060, 1061, 1054], true)) {
+            $log[] = ['skip', $label . ' (already exists)'];
+        } else {
+            $log[] = ['err', $label . ': ' . $e->getMessage()];
+        }
+    }
+}
+
+mig5_sql($pdo, 'Add step_type column', "
+    ALTER TABLE builder_steps
+    ADD COLUMN step_type ENUM('prayer','bead') NOT NULL DEFAULT 'prayer' AFTER session_id
+", $log);
+
+mig5_sql($pdo, 'Add bead_type column', "
+    ALTER TABLE builder_steps
+    ADD COLUMN bead_type ENUM('small','large','crucifix') NULL AFTER step_type
+", $log);
+
+mig5_sql($pdo, 'Make prayer_id nullable', "
+    ALTER TABLE builder_steps
+    MODIFY COLUMN prayer_id INT NULL
+", $log);
+
+?><!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Migrate v5</title>
+    <style>
+        body { font-family: system-ui; max-width: 700px; margin: 40px auto; padding: 0 20px; }
+        .ok { color: #15803d; } .skip { color: #b45309; } .err { color: #dc2626; }
+        li { margin: 4px 0; font-size: 14px; }
+        .done { background: #f0fdf4; border: 1px solid #86efac; padding: 16px; border-radius: 8px; margin-top: 20px; }
+    </style>
+</head>
+<body>
+<h2>Migrate v5 — Bead Separator Support</h2>
+<ul>
+<?php foreach ($log as [$status, $msg]): ?>
+    <li class="<?= $status ?>">
+        <?= $status === 'ok' ? '&#x2713;' : ($status === 'skip' ? '&#x25CC;' : '&#x2717;') ?>
+        <?= htmlspecialchars($msg) ?>
+    </li>
+<?php endforeach; ?>
+</ul>
+<?php if (!array_filter($log, fn($l) => $l[0] === 'err')): ?>
+<div class="done">
+    <strong>Migration complete.</strong> Delete this file: <code>migrate_v5.php</code>
+</div>
+<?php endif; ?>
+</body>
+</html>