diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md
index 79ec129..2830458 100644
--- a/PROJECT_CONTEXT.md
+++ b/PROJECT_CONTEXT.md
@@ -1,6 +1,6 @@
# Practitioner Protocols — Project Context (for Claude)
-_Snapshot: 2026-11-09 · Live Railway deployment active (`practitioner-protocols-production.up.railway.app`) with internal Postgres & ledger migrations · Production app record "Practitioner Protocols" released (v2, Public distribution) · Production hardening complete · Milestones M9a, M9b-1, M9b-2, M9b-3a & M9b-3b VERIFIED LIVE on dev store · Milestone M11 (Shopper Opt-In & Merchant Contact Hardening) implemented · Pre-submission hardening complete · Spikes S2, S3, S4, S5, S6 resolved; S1 resolved on the Plus dev store only · Brand assets v2 & v3 produced and verified · Demo gaps and accuracy fixes branch (`feat/demo-gaps-and-accuracy-fixes`) implemented with Liquid injection defense and App Bridge resource picker · 588 tests passing across 132 suites._
+_Snapshot: 2026-11-09 · Live Railway deployment active (`practitioner-protocols-production.up.railway.app`) with internal Postgres & ledger migrations · Production app record "Practitioner Protocols" released (v2, Public distribution) · Production hardening complete · Milestones M9a, M9b-1, M9b-2, M9b-3a & M9b-3b VERIFIED LIVE on dev store · Milestone M11 (Shopper Opt-In & Merchant Contact Hardening) implemented · Pre-submission hardening complete · Spikes S2, S3, S4, S5, S6 resolved; S1 resolved on the Plus dev store only · Brand assets v2 & v3 produced and verified · Demo gaps and accuracy fixes merged (PR #28) · Issue #29 resolved (modal in-page error messaging) · 591 tests passing across 132 suites._
_Contains NO secrets. Never paste `.env` values or tokens into chat or docs._
## 1. What this is
@@ -1246,6 +1246,31 @@ Following a full live dev store demo recording, 7 discrepancies between document
- **Standards Mode DOCTYPE Order (Blocker 2):** Removed `` prepended before `` in `routes.js`. Injected `` inside `
` in `renderHandoutHtml`, ensuring `{% layout none %}` is followed immediately by standards-mode ``.
- Comprehensive regression tests in `test/handout.test.js`, `test/routes.test.js`, `test/portal.test.js`, and `test/admin.test.js` bringing total passing unit tests to 588 across 132 suites with zero failures.
+---
+
+## 47. Replace alert() in Starter Modal with Accessible In-Page Messages (Issue #29, 2026-11-09)
+
+In modern Shopify embedded admin apps running inside an iframe on `admin.shopify.com`, native browser `alert()` dialogs are frequently suppressed, blocked, or cause poor UX. Issue #29 addressed this in branch `fix/starter-modal-alerts`:
+
+1. **Elimination of all `alert()` calls in the starter modal:**
+ - Invalid variant GID (`must be a product variant GID`)
+ - Duplicate variant warning (`This product variant is already in the starter template.`)
+ - Maximum 20-item cap (`Maximum 20 lines allowed per starter template.`)
+ - Empty variant input on manual add (`Please enter a variant GID.`)
+ - Malformed variant ID on manual add (`Variant ID must be numeric or gid://shopify/ProductVariant/`)
+ - Empty line items on template submission (`Please add at least one product line item to the starter template.`)
+ - Variant fetch failures on search suggestion click (`Could not load product variants`)
+
+2. **Unified In-Page Message & Alert Banner:**
+ - Introduced `showStarterMessage(msg, isError, asHtml)` and `clearStarterMessage()`.
+ - Utilizes `#admin-starter-search-message` rendered in normal document flow with appropriate semantic styles (critical red for errors, amber for notices/warnings) and dynamic `role="alert"` / `role="status"` accessibility attributes.
+ - Clears automatically when the user selects a product, resets the modal, enters text in manual inputs, or clears the search field.
+
+3. **Verification:**
+ - Added unit test in `test/admin.test.js` verifying zero `alert()` calls in the starter modal script and asserting in-page error message rendering.
+ - 591 unit tests passing across 132 suites (`npm test`). Zero failures.
+
+
diff --git a/app/lib/protocols/admin.js b/app/lib/protocols/admin.js
index 5e0dad6..ebb5250 100644
--- a/app/lib/protocols/admin.js
+++ b/app/lib/protocols/admin.js
@@ -2732,19 +2732,45 @@ ${appBridgeHead} Practitioner Protocols — Admin
});
}
- function resetStarterModalState() {
- if (starterSearchInput) starterSearchInput.value = '';
- if (starterSearchDropdown) {
- starterSearchDropdown.style.display = 'none';
- starterSearchDropdown.innerHTML = '';
+ function showStarterMessage(msg, isError, asHtml) {
+ const msgEl = document.getElementById('admin-starter-search-message');
+ if (!msgEl) return;
+ msgEl.style.display = 'block';
+ msgEl.setAttribute('role', isError ? 'alert' : 'status');
+ if (isError) {
+ msgEl.style.background = '#fee2e2';
+ msgEl.style.border = '1px solid #fca5a5';
+ msgEl.style.color = '#991b1b';
+ } else {
+ msgEl.style.background = '#fef3c7';
+ msgEl.style.border = '1px solid #fcd34d';
+ msgEl.style.color = '#92400e';
+ }
+ if (asHtml) {
+ msgEl.innerHTML = msg;
+ } else {
+ msgEl.textContent = msg;
}
+ }
+
+ function clearStarterMessage() {
const msgEl = document.getElementById('admin-starter-search-message');
if (msgEl) {
msgEl.style.display = 'none';
msgEl.innerHTML = '';
+ msgEl.removeAttribute('role');
}
}
+ function resetStarterModalState() {
+ if (starterSearchInput) starterSearchInput.value = '';
+ if (starterSearchDropdown) {
+ starterSearchDropdown.style.display = 'none';
+ starterSearchDropdown.innerHTML = '';
+ }
+ clearStarterMessage();
+ }
+
function closeStarterModal() {
resetStarterModalState();
const modal = document.getElementById('create-starter-modal');
@@ -2757,11 +2783,7 @@ ${appBridgeHead} Practitioner Protocols — Admin
function performStarterSearch() {
const q = (starterSearchInput ? starterSearchInput.value : '').trim();
- const msgEl = document.getElementById('admin-starter-search-message');
- if (msgEl) {
- msgEl.style.display = 'none';
- msgEl.innerHTML = '';
- }
+ clearStarterMessage();
if (q.length < 2 || !starterSearchDropdown) return;
starterSearchDropdown.style.display = 'block';
@@ -2801,7 +2823,7 @@ ${appBridgeHead} Practitioner Protocols — Admin
if (p.variants && p.variants.length > 0) {
addVariantToStarter(p, p.variants[0], handle);
} else {
- alert('Could not load product variants');
+ showStarterMessage('Could not load product variants', true, false);
}
});
});
@@ -2813,13 +2835,7 @@ ${appBridgeHead} Practitioner Protocols — Admin
starterSearchDropdown.style.display = 'none';
starterSearchDropdown.innerHTML = '';
}
- if (msgEl) {
- msgEl.style.display = 'block';
- msgEl.style.background = '#fef3c7';
- msgEl.style.border = '1px solid #fcd34d';
- msgEl.style.color = '#92400e';
- msgEl.innerHTML = 'Storefront catalog search is unavailable from the embedded admin iframe without storefront CORS. Please click Browse Products above to open the native Shopify picker, or use the Advanced: Enter Variant GID directly section below (now opened).';
- }
+ showStarterMessage('Storefront catalog search is unavailable from the embedded admin iframe without storefront CORS. Please click Browse Products above to open the native Shopify picker, or use the Advanced: Enter Variant GID directly section below (now opened).', false, true);
const advDetails = document.getElementById('admin-starter-advanced-details');
if (advDetails) {
advDetails.open = true;
@@ -2829,16 +2845,16 @@ ${appBridgeHead} Practitioner Protocols — Admin
function addVariantToStarter(prod, variant, handle) {
if (starterItems.length >= 20) {
- alert('Maximum 20 lines allowed per starter template.');
+ showStarterMessage('Maximum 20 lines allowed per starter template.', true, false);
return;
}
const vGid = variant.id ? (String(variant.id).startsWith('gid://') ? String(variant.id) : 'gid://shopify/ProductVariant/' + variant.id) : '';
if (!vGid || !vGid.startsWith('gid://shopify/ProductVariant/')) {
- alert('Invalid variant: must be a product variant GID');
+ showStarterMessage('Invalid variant: must be a product variant GID', true, false);
return;
}
if (starterItems.some(function(i) { return i.variantGid === vGid; })) {
- alert('This product variant is already in the starter template.');
+ showStarterMessage('This product variant is already in the starter template.', true, false);
return;
}
const title = variant.title && variant.title !== 'Default Title' ? (prod.title + ' - ' + variant.title) : (prod.title || 'Product');
@@ -2883,14 +2899,7 @@ ${appBridgeHead} Practitioner Protocols — Admin
addVariantToStarter(prod, v, prod.handle);
});
} else {
- const msgEl = document.getElementById('admin-starter-search-message');
- if (msgEl) {
- msgEl.style.display = 'block';
- msgEl.style.background = '#fef3c7';
- msgEl.style.border = '1px solid #fcd34d';
- msgEl.style.color = '#92400e';
- msgEl.textContent = 'This product has no selectable variants';
- }
+ showStarterMessage('This product has no selectable variants', false, false);
}
});
}).catch(function(err) {
@@ -2899,14 +2908,7 @@ ${appBridgeHead} Practitioner Protocols — Admin
} else {
const adv = document.getElementById('admin-starter-advanced-details');
if (adv) adv.open = true;
- const msgEl = document.getElementById('admin-starter-search-message');
- if (msgEl) {
- msgEl.style.display = 'block';
- msgEl.style.background = '#fef3c7';
- msgEl.style.border = '1px solid #fcd34d';
- msgEl.style.color = '#92400e';
- msgEl.innerHTML = 'Shopify Resource Picker is active when viewed inside Shopify Admin. Please use the Advanced: Enter Variant GID directly section below to add variants.';
- }
+ showStarterMessage('Shopify Resource Picker is active when viewed inside Shopify Admin. Please use the Advanced: Enter Variant GID directly section below to add variants.', false, true);
}
});
}
@@ -2920,23 +2922,23 @@ ${appBridgeHead} Practitioner Protocols — Admin
manualAddBtn.addEventListener('click', function() {
let gid = (manualGidInput ? manualGidInput.value : '').trim();
if (!gid) {
- alert('Please enter a variant GID.');
+ showStarterMessage('Please enter a variant GID.', true, false);
return;
}
if (!gid.startsWith('gid://shopify/ProductVariant/')) {
if (/^\d+$/.test(gid)) {
gid = 'gid://shopify/ProductVariant/' + gid;
} else {
- alert('Variant ID must be numeric or gid://shopify/ProductVariant/');
+ showStarterMessage('Variant ID must be numeric or gid://shopify/ProductVariant/', true, false);
return;
}
}
if (starterItems.some(function(i) { return i.variantGid === gid; })) {
- alert('This product variant is already in the starter template.');
+ showStarterMessage('This product variant is already in the starter template.', true, false);
return;
}
if (starterItems.length >= 20) {
- alert('Maximum 20 lines allowed per starter template.');
+ showStarterMessage('Maximum 20 lines allowed per starter template.', true, false);
return;
}
const handle = (manualHandleInput ? manualHandleInput.value : '').trim().toLowerCase();
@@ -2954,10 +2956,19 @@ ${appBridgeHead} Practitioner Protocols — Admin
if (manualHandleInput) manualHandleInput.value = '';
if (manualTitleInput) manualTitleInput.value = '';
+ clearStarterMessage();
updateStarterRows();
});
}
+ [manualGidInput, manualHandleInput, manualTitleInput].forEach(function(inp) {
+ if (inp) {
+ inp.addEventListener('input', function() {
+ clearStarterMessage();
+ });
+ }
+ });
+
if (starterSearchBtn) {
starterSearchBtn.addEventListener('click', performStarterSearch);
}
@@ -2966,11 +2977,7 @@ ${appBridgeHead} Practitioner Protocols — Admin
starterSearchInput.addEventListener('input', function() {
clearTimeout(debounceTimer);
if (!starterSearchInput.value.trim()) {
- const msgEl = document.getElementById('admin-starter-search-message');
- if (msgEl) {
- msgEl.style.display = 'none';
- msgEl.innerHTML = '';
- }
+ clearStarterMessage();
if (starterSearchDropdown) {
starterSearchDropdown.style.display = 'none';
starterSearchDropdown.innerHTML = '';
@@ -2984,7 +2991,7 @@ ${appBridgeHead} Practitioner Protocols — Admin
starterForm.addEventListener('submit', function(e) {
if (starterItems.length === 0) {
e.preventDefault();
- alert('Please add at least one product line item to the starter template.');
+ showStarterMessage('Please add at least one product line item to the starter template.', true, false);
}
});
}
diff --git a/test/admin.test.js b/test/admin.test.js
index 84823b4..25f74d7 100644
--- a/test/admin.test.js
+++ b/test/admin.test.js
@@ -1597,6 +1597,30 @@ describe('Merchant Admin Layer (app/lib/protocols/admin.js)', () => {
assert.ok(!html.includes('placeholder="gid://shopify/ProductVariant/...'));
});
+ it('uses in-page messages and zero alert() calls in the starter template modal (Issue #29)', () => {
+ const html = renderAdminHtml({
+ shop: testShop,
+ starters: mockStarters,
+ activeTab: 'starters'
+ });
+
+ // Extract the starter modal script portion
+ const starterScriptStart = html.indexOf('// Admin Starter Product Search & Selection');
+ assert.ok(starterScriptStart !== -1, 'Starter script must be present');
+ const starterScript = html.slice(starterScriptStart);
+
+ // Verify zero alert() calls exist in the starter modal logic
+ assert.ok(!starterScript.includes('alert('), 'Starter modal script must contain zero alert() calls');
+
+ // Verify helper functions and in-page message handling exist
+ assert.ok(starterScript.includes('function showStarterMessage'), 'Must define showStarterMessage');
+ assert.ok(starterScript.includes('function clearStarterMessage'), 'Must define clearStarterMessage');
+ assert.ok(starterScript.includes('Maximum 20 lines allowed per starter template.'), 'Must have 20-line cap message');
+ assert.ok(starterScript.includes('Invalid variant: must be a product variant GID'), 'Must have invalid variant message');
+ assert.ok(starterScript.includes('This product variant is already in the starter template.'), 'Must have duplicate variant message');
+ assert.ok(starterScript.includes('Please add at least one product line item to the starter template.'), 'Must have empty template validation message');
+ });
+
it('formats currency minor units with ISO currency code (Item 6)', () => {
const formattedUsd = formatCurrencyMinor(125360, 'USD', 'en-US');
assert.ok(formattedUsd.includes('1,253.60'));