SpinStream paper

Minted Verification Protocol

Verification procedure for confirming mode state, minted output, canonical URL structure, and immutable final behavior.

Download original source Back to main landing page

Minted Verification Protocol

Version: 1.0

**Purpose:** Strict, repeatable verification procedure for minted artifacts under `https://spinstream.xyz/finals/<slug>_<id>/`

**Audience:** Copilot agents, human contributors, and quality-assurance personnel

---

1. Terminology & State Model

This protocol uses precise terminology to distinguish between editing, preview, and minted states:

Editor Mode

- The editable interface where users create and configure their SpinStream

- Contains form fields, toggle controls, and configuration options

- Hero section displays in edit mode with form inputs

- No finalization or minting actions available

- **DOM marker:** `body` does NOT have `preview-mode` or `finalized` classes

Preview Mode

- Read-only preview of the configured SpinStream **before** finalization

- Accessed by clicking "Switch to Preview Mode" in the editor

- Shows how the content will appear when finalized, but is NOT permanent

- Form fields hidden, but still accessible by returning to Edit Mode

- Mint button available (if authenticated)

- **DOM marker:** `body.preview-mode`

Finalize (pre-upload)

- The action of preparing content for permanent minting

- Triggered by clicking "Mint" in Preview Mode (requires authentication)

- Generates the exported HTML snapshot via `buildInlineExportHtml()`

- Content becomes immutable at this stage

- **DOM marker:** `body.finalized` (set before upload)

Minted Artifact

- The **permanent, immutable, public** artifact served at `https://spinstream.xyz/finals/<slug>_<id>/`

- Generated by the external Cloudflare Worker mint endpoint: `https://spinstream-mint-v2.cptnspacetime.workers.dev/mint`

- Contains exported HTML with all assets inlined or referenced

- Hero section populated from editor form values

- Gold seal and verification metadata present

- **DOM marker:** `body[data-exported="true"]`

Key Distinction

- **Preview/Final UI** = local editor states (ephemeral)

- **Minted Artifact** = production URL at `/finals/...` (permanent)

---

2. Historical Failure Mode

**Problem:** Fixes validated in Preview mode or local Finalized state often fail to appear on the actual Minted Artifact served at `https://spinstream.xyz/finals/...`.

Why This Happens

1. Export snapshot timing issues

- `buildInlineExportHtml()` captures a DOM snapshot at a specific moment

- If CSS/JS state isn't fully materialized before snapshot, it's missing from export

- Hero section visibility, content population, and attribute persistence must occur **before** snapshot

2. CSS inlining vs external stylesheets

- Minted pages may use different CSS delivery strategies

- Fully inlined CSS (bundled)

- External `style.css` loaded from root domain

- External CSS loaded from `/finals/` path

- CSS selectors that work in Preview may fail if specificity/loading differs in minted context

3. JavaScript execution differences

- Preview mode has full `script.js` runtime

- Minted artifacts may have limited or no JS (depending on export config)

- Features relying on client-side JS initialization will fail on minted pages

4. Validation gaps

- Testing only Preview/Finalized in local editor

- Not testing the actual production minted URL

- Not verifying network delivery and asset loading

Example Case: Hero Section Missing

A classic failure: Hero displays perfectly in Preview, but the minted artifact at `/finals/...` has no hero section in the HTML source.

**Root cause:** Hero content not materialized into DOM before `document.documentElement.outerHTML` snapshot in `buildInlineExportHtml()`.

**Fix:** Ensure hero input values are persisted to DOM attributes and preview elements are populated before export (see lines 2216-2243 in `script.js`).

---

3. Required Test Matrix

All UI changes MUST be verified across this complete state and device matrix:

|-------|------------------|-----------------|------------|

Edge Cases (Minted Only)

- [ ] Missing CTA: no layout gaps or broken sections

- [ ] Missing links: footer/nav handle gracefully

- [ ] No audio file: player hidden or displays placeholder

- [ ] Long artist names: text wrapping works on mobile

- [ ] Seal + footer overlap: adequate spacing on small screens

Verification Requirement

**You MUST test the actual minted URL at `https://spinstream.xyz/finals/<slug>_<id>/` on both desktop and mobile.**

Local Preview/Finalized states are necessary but **not sufficient**. Only the production minted artifact represents the true user experience.

---

4. Step 0: Network & Asset Delivery Test

Before debugging visual/layout issues on minted artifacts, determine the asset delivery strategy:

Run This Test First

1. Open the minted artifact URL in a browser: `https://spinstream.xyz/finals/<slug>_<id>/`

2. Open DevTools → Network tab

3. Refresh the page and observe requests

Asset Delivery Modes

Mode A: Fully Bundled (Inlined)

- All CSS and JS inlined in the HTML `<head>` and `<body>`

- No external requests to `style.css` or `script.js`

- **Implication:** Changes to root `style.css` will NOT affect minted artifacts. CSS must be present in the export snapshot.

Mode B: Shared Runtime (External)

- Requests to `https://spinstream.xyz/style.css` and/or `https://spinstream.xyz/script.js`

- Assets loaded from **root domain**

- **Implication:** Changes to root CSS/JS files WILL affect minted artifacts.

Mode C: Finals-Scoped (External)

- Requests to `https://spinstream.xyz/finals/<slug>_<id>/style.css`

- Assets loaded from **finals subdirectory**

- **Implication:** Minted artifacts use per-page CSS bundles. Root CSS changes may not apply.

Why This Matters

- **Bundled:** CSS fixes must be added to `style.css` **before** minting. Updating root CSS after minting has no effect.

- **Shared Runtime:** CSS fixes can be applied retroactively by updating root `style.css`.

- **Finals-Scoped:** Each minted artifact is isolated. Fixes require re-minting.

**Document your findings** in bug reports and PRs. Include a screenshot of the Network tab showing asset loading.

---

5. Copilot Procedure for Minted Bugs

When a bug is reported on a minted artifact that does NOT appear in Preview/Finalized states:

Phase 1: Export Snapshot Verification

**Objective:** Confirm the bug is present in the exported HTML snapshot, not just a CSS/JS runtime issue.

Steps

1. Access the minted artifact HTML source:

- If accessible: Open `https://spinstream.xyz/finals/<slug>_<id>/` and view source

- If inaccessible (Copilot limitation): Request user to provide HTML source via `curl` or browser "Save Page As"

2. Search for key markers (string checks):

```bash

Check if page is properly exported

grep 'data-exported="true"' minted_artifact.html

Check if hero section is present

grep 'hero-reference' minted_artifact.html

grep 'heroPreview' minted_artifact.html

Check for hero content population

grep 'previewName' minted_artifact.html

grep 'previewTagline' minted_artifact.html

grep 'previewCTA' minted_artifact.html

Check for CTA sections

grep 'heroCTA' minted_artifact.html

grep 'finalCTA' minted_artifact.html

Check for gold seal

grep 'gold-seal' minted_artifact.html

grep 'promoperm-badge' minted_artifact.html

🔒 VERIFY HELPERS ARE REMOVED (should return NO matches)

grep 'helperButtons' minted_artifact.html # Should be absent

grep 'helperStateWhisper' minted_artifact.html # Should be absent

grep 'Helper: Commercial Fill' minted_artifact.html # Should be absent

grep 'dev-helpers' minted_artifact.html # Should be absent

grep 'devQuickFill' minted_artifact.html # Should be absent

grep '__HELPER_STATE__' minted_artifact.html # Should be absent

```

3. Analyze findings:

- **Markers present:** Issue is CSS/JS styling, proceed to Phase 2

- **Markers missing:** Issue is export snapshot bug, proceed to Phase 3

- **Helper strings found:** Export sanitization failed, requires code fix

Phase 2: Exported-Mode Simulation

**Objective:** Reproduce the bug locally by simulating the exported/minted state.

Steps

1. Set up local exported mode:

```javascript

// In browser console on local editor

document.body.setAttribute('data-exported', 'true');

document.body.classList.add('finalized');

document.body.classList.remove('preview-mode');

```

2. Apply minted-specific CSS classes:

```javascript

// Simulate gold seal presence

const seal = document.querySelector('.promoperm-badge');

if (seal) seal.classList.add('show');

```

3. Disable JS features (if applicable):

- Comment out dynamic initialization code

- Test with `script.js` blocked in DevTools

4. Compare rendering:

- Does the bug reproduce locally in exported mode?

- If YES: CSS fix is viable

- If NO: Deeper snapshot/export issue

Phase 3: Decision Rules

CSS-Only Fix is Viable If:

- Hero/content markup is present in exported HTML

- Bug is purely visual (layout, spacing, colors, visibility)

- Shared runtime mode detected (external `style.css`)

- No JS gating or dynamic content population required

**Action:** Add CSS patch to `style.css` following UI Patch Protocol (ADD ONLY, append at end).

CSS-Only Fix is NOT Viable If:

- Hero/content markup is MISSING from exported HTML

- Bug requires JS initialization (event listeners, dynamic DOM manipulation)

- Inlined styles in HTML conflict with external CSS (specificity issues)

- Content requires programmatic population (form values → preview elements)

**Action:** Fix the export snapshot logic in `buildInlineExportHtml()` or `freezeAndUpload()`. Requires code changes to `script.js`.

Phase 4: Re-Test on Minted Artifact

**Critical:** After applying any fix, you MUST re-mint and verify the actual production URL.

1. Deploy changes to the branch/environment being tested

2. Perform a new mint action with the fixed code

3. Access the NEW minted URL at `/finals/<slug>_<id>/`

4. Verify the fix is present and the bug is resolved

5. Test on both desktop and mobile

**Never consider a minted bug fixed until verified on a production minted artifact.**

---

6. Worker Black-Box Verification (Cloudflare)

The Cloudflare mint Worker endpoint is external to this repo and must be treated as a **black box**.

Mint Endpoint

**URL:** `https://spinstream-mint-v2.cptnspacetime.workers.dev/mint`

**Responsibility:** Receives the exported HTML payload, generates a unique slug and ID, stores the artifact at `https://spinstream.xyz/finals/<slug>_<id>/`, and returns the final URL.

Black-Box Principle

**You CANNOT:**

- Modify the Worker code (it's in a separate repo)

- Debug Worker internals

- Rely on Worker behavior beyond the documented API contract

**You CAN:**

- Verify the payload sent TO the Worker

- Verify the URL returned FROM the Worker

- Test the final artifact served BY the Worker

Required Evidence for Minted Bug Reports

When reporting a bug on a minted artifact, provide

1. Export Verification PASS:

- [ ] Exported HTML contains `data-exported="true"`

- [ ] Hero markup present in exported HTML source

- [ ] Key content markers present (hero IDs, CTA sections, gold seal)

- [ ] Exported HTML size reasonable (not empty or truncated)

2. Network Capture Fields:

- [ ] Mint request payload size: `_____ KB`

- [ ] Mint response status: `200 OK` or error code

- [ ] Returned final URL: `https://spinstream.xyz/finals/<slug>_<id>/`

- [ ] Asset delivery mode: Bundled / Shared Runtime / Finals-Scoped

- [ ] Screenshot of DevTools Network tab showing mint request/response

3. Human Acceptance Minted URL:

- [ ] Actual minted URL accessible: `https://spinstream.xyz/finals/___________/`

- [ ] Screenshot of minted artifact (desktop)

- [ ] Screenshot of minted artifact (mobile ≤600px)

- [ ] Bug reproduction confirmed: YES / NO

Diagnosis Rules

If export verification FAILS:

- Bug is in the EDITOR (`buildInlineExportHtml()`, `freezeAndUpload()`, or related functions)

- Fix required: Update export snapshot logic in `script.js`

- Worker is irrelevant to the bug

If export verification PASSES but minted artifact is broken:

- Bug is in the WORKER or infrastructure

- Fix required: Escalate to Worker maintainer or infrastructure team

- Editor code is not the cause

If export verification PASSES and minted artifact works, but styling is wrong:

- Bug is in CSS delivery or asset loading

- Fix required: Update `style.css` following UI Patch Protocol

- Consider asset delivery mode (Step 0)

---

7. Branching & Deployment Context

Branch Awareness

This repo may use multiple branches beyond `live`

- `live` - production branch

- `staging` - pre-production testing

- `heromint` - feature branch for hero export fixes

- `copilot/*` - temporary Copilot work branches

Acceptance Mint Requirement

**Acceptance mint MUST be performed from the deployed branch/environment being tested.**

- If testing a PR against `live`, deploy to staging environment that mimics production

- If testing a feature branch, ensure the branch is deployed and accessible for minting

- PR base branch may vary (e.g., PR to `staging` instead of `live`)

Pre-Merge Checklist

Before merging any PR that affects minted artifacts

1. [ ] Branch deployed to test environment

2. [ ] Acceptance mint performed from deployed branch

3. [ ] Minted artifact URL verified: `https://spinstream.xyz/finals/___________/`

4. [ ] Test matrix completed (all states, desktop + mobile)

5. [ ] Export verification passed (key markers present in HTML source)

6. [ ] Network capture documented (asset delivery mode confirmed)

7. [ ] Screenshots attached to PR (desktop + mobile, minted artifact)

---

8. PR Checklist Snippet

Copy and paste this checklist into PRs that affect minted artifacts:

```markdown

Minted Verification Checklist

Export Verification

- [ ] Exported HTML contains `data-exported="true"`

- [ ] Hero markup present in exported HTML source

- [ ] Key markers verified: `hero-reference`, `heroPreview`, CTA sections, gold seal

- [ ] 🔒 Dev Helper sanitization (Path 1 - protocol-compliant): No `helperButtons`, `helperStateWhisper`, `Helper: Commercial Fill`, `dev-helpers`, `devQuickFill`, `__HELPER_STATE__`, or other dev-helper/debug identifiers present. Normal editor/preview UI elements (toggleModeBtn, mode-controls, preview-indicator, etc.) are removed during export but not considered "banned".

Test Matrix

- [ ] Edit mode: Desktop + Mobile (no CTA restyling)

- [ ] Preview mode: Desktop + Mobile (mint button appears)

- [ ] Finalized (pre-upload): Desktop + Mobile (glass CTA, state whisper)

- [ ] **Minted artifact**: Desktop + Mobile (gold seal, authority CTA, all content visible)

Network & Asset Delivery

- [ ] Step 0 network test completed

- [ ] Asset delivery mode: [ ] Bundled / [ ] Shared Runtime / [ ] Finals-Scoped

- [ ] Network capture screenshot attached

Acceptance Mint

- [ ] Deployed branch: `___________`

- [ ] Minted artifact URL: `https://spinstream.xyz/finals/___________/`

- [ ] Acceptance mint performed: YES / NO

- [ ] Screenshots attached: Desktop + Mobile (minted artifact)

Edge Cases (if applicable)

- [ ] Missing CTA: no layout gaps

- [ ] Missing links: footer/nav graceful

- [ ] Long content: text wrapping works on mobile

- [ ] Seal + footer: no overlap on small screens

```

---

9. Security & Safety Considerations

Gold Seal Integrity

The gold seal (`promoperm-badge`, `gold-seal`) is the **only certification marker** for minted artifacts.

Never:

- Remove or modify the gold seal markup

- Change gold seal styling without explicit approval

- Merge seal with CTA or other UI elements

Immutability Guarantee

Once minted, artifacts at `/finals/<slug>_<id>/` MUST be immutable.

Never:

- Implement logic that modifies minted artifact content post-mint

- Add dynamic content loading to minted pages (breaks immutability guarantee)

- Cache-bust or version minted URLs (they should be permanent)

Copilot-Safe Verification

This protocol is designed for Copilot agents that cannot access production URLs.

Always:

- Request HTML source from users if URL is inaccessible

- Use string checks (`grep`, regex) on HTML source for verification

- Provide clear pass/fail criteria that don't require browser rendering

---

10. Quick Reference

Terminology Cheat Sheet

| Term | Meaning |

|------|---------|

| **Editor Mode** | Form-based editing UI |

| **Preview Mode** | Read-only preview before finalization |

| **Finalize** | Action that generates exported HTML snapshot |

| **Minted Artifact** | Permanent public URL at `/finals/...` |

| **Export Snapshot** | `document.documentElement.outerHTML` capture |

| **Gold Seal** | Verification marker on minted artifacts |

Key DOM Markers

| Marker | Meaning |

|--------|---------|

| `body.preview-mode` | Preview state (local) |

| `body.finalized` | Finalized state (local, pre-upload) |

| `body[data-exported="true"]` | Minted artifact (production) |

Critical Files

- **`script.js`**: Editor logic, `buildInlineExportHtml()`, `freezeAndUpload()`

- **`style.css`**: Main stylesheet (may be inlined or external in minted artifacts)

- **`index.html`**: Editor page structure

Mint Workflow

1. User creates content in Editor Mode

2. User switches to Preview Mode (validates presentation)

3. User clicks "Mint" → Finalize (generates export snapshot)

4. `freezeAndUpload()` sends payload to Cloudflare Worker

5. Worker returns minted URL: `https://spinstream.xyz/finals/<slug>_<id>/`

6. User redirected to Minted Artifact (permanent)

---

Appendix: Common Pitfalls

Pitfall 1: Testing Only Preview

**Mistake:** Validating changes in Preview mode and assuming they work on minted artifacts.

**Solution:** Always test the actual minted URL at `/finals/...` on both desktop and mobile.

Pitfall 2: Forgetting Hero Materialization

**Mistake:** Modifying hero CSS/JS without ensuring hero content is populated before export snapshot.

**Solution:** Verify hero input values are persisted to DOM attributes and preview elements are populated (lines 2216-2243 in `script.js`).

Pitfall 3: Ignoring Asset Delivery Mode

**Mistake:** Updating root `style.css` and expecting it to fix bundled minted artifacts.

**Solution:** Run Step 0 network test first. If bundled, CSS must be present before minting.

Pitfall 4: Modifying JS Without Re-Testing Export

**Mistake:** Changing `script.js` logic and testing only in live editor, not in exported/finalized state.

**Solution:** Use exported-mode simulation (Phase 2) to test with JS disabled or limited.

Pitfall 5: Trusting Worker Behavior

**Mistake:** Assuming the Cloudflare Worker will "fix" export issues or compensate for missing content.

**Solution:** Treat the Worker as a black box. Ensure exported HTML is complete and correct before sending to Worker.

---

Changelog

- **v1.0** (2026-01-14): Initial protocol document created

- Defined terminology and state model

- Documented historical failure mode

- Established test matrix and network test procedure

- Provided Copilot-safe verification procedure

- Added Worker black-box verification section

- Included PR checklist snippet

---

**End of Protocol**

SpinStream documentation bundle rebuilt as a single-entry protocol site. Original source files remain in /docs and /diagrams.

Minted Verification Protocol