studio-engine 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14686260b35b4cd72975c3bf156020de61094144f09d8e71f3d6eeb045b5bcc3
-  data.tar.gz: 35b5f1bb5cb7f1236d21baa47c3e28d6d7f00420eb775da0719cd9874b29b4b8
+  metadata.gz: 15b4c45fed9c5a2fd6056fca154236cbc12b778c483af5922486e47fcec6baac
+  data.tar.gz: d1efa67d91b858e9ba81f9fea1cb63d4b73c1e76a97c08dd0a8ca2afcd0b4522
 SHA512:
-  metadata.gz: 4a8b31f5f092a8998590c47877fb23631316fbaee2ab8bca2199038d27497775db342a5ba4f2b759bd09b2ae44256ad57b857cea5742731f84c59a8525a3b1e3
-  data.tar.gz: 506f56fbadf51b53c7a1f779678bab0ba1de8fc485493acb4d3ac8aa19ddfd29c4b103d789107d3f4258b381d709fdefdd00fc7ab81dd8cdfffbc59f8baffb88
+  metadata.gz: ec7d708e3665fbccf82ee641f82110cc8adfda8dd19528b3748807697ae6127db02c9579e1ef414051e541ea28005cc6b525b554e46ab1d1abd11cc959f48e74
+  data.tar.gz: dbc43339aeaad12be683b260e4cfcac8aa70f9fbf3a23be136b161790ce4468c8711f1e45c2fd608257df4bf867427e7cf3f8b8e52b0100e218c6de6a85dce1c

data/CHANGELOG.md

@@ -2,6 +2,94 @@
 
 The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — `MAJOR.MINOR.PATCH`. Consumer Rails apps install the released RubyGems package with `gem "studio-engine", "~> 0.6"`; bumping the gem version and updating consumer lockfiles is a release.
 
+## 0.22.0 — 2026-07-28
+
+Two additive batches for the living style guide, converged under one release.
+No existing shared primitive changes its defaults, so MS and TM render identically
+on the bump.
+
+Modal convergence, Phase 3: homes Turf Monster's quest/leveling activity modals
+(change username + the quest flows) as engine primitives, each supporting BOTH
+modes behind the `:leveling` capability flag. Plus a Tricks batch: three
+celebration/attention effects lifted from Turf Monster into engine primitives, all
+demoed on `/admin/style`.
+
+### Added
+
+- **Leveling-activity modal — `studio/modals/blocks/_leveling_activity`.** ONE
+  primitive, **two modes**, decided by `Studio.feature?(:leveling)`:
+  - **leveling on** — the full quest framing: a "Quest N of N" pill, and on
+    success the seeds celebration (progress bar + level-up + Free Entry), composed
+    from the existing `card_header` + `_seeds_bar` chrome.
+  - **leveling off** — the plain action modal: just the action + Save, then a
+    Saved state. No quest pill, no seeds. This is the McRitchie Studio shape (MS
+    has no leveling; Turf Monster does).
+
+  It renders a title, app-authored description, an optional single-line input
+  (`input` / `input_type` / validation attrs), and a configurable CTA. Callers
+  override the `leveling` gate per callsite (the style guide passes both) or let
+  it default to the app flag.
+
+- **Change-username modal — `studio/modals/blocks/_change_username`.** A named
+  engine primitive and a thin specialization of `_leveling_activity` with username
+  defaults (3–30 char input, the on-chain-neutral default copy, a
+  `studio:username-saved` event). This is the primary migrated modal.
+
+- **`levelingActionModal` factory — `studio/_leveling_activity_assets`.** The
+  Alpine data behind both modals, shipped at page level (a `<script>` cloned out
+  of a modal-host template never runs), like `ageVerifyModal`.
+
+  **CRITICAL BOUNDARY — UI ONLY.** The actual save is an **app-supplied callback**:
+  the modal POSTs to `submit_url` and reacts to a **domain-neutral** JSON contract
+  (`{ status: "saved" | "needs_step" | "error" }`). Any second step some apps need
+  (e.g. a managed-wallet write) is delegated **opaquely**: the engine hands the
+  app-returned `challenge` blob to an app-supplied `window[finalize_hook]` and
+  POSTs back the opaque `proof` the app returns — it never inspects, parses, or
+  decodes either blob. No wallet taxonomy, signing, keys, or on-chain writes live
+  anywhere in the engine; the custodial-vs-Phantom branch stays server-side. Turf
+  Monster wires the managed-wallet write; McRitchie Studio wires a trivial endpoint
+  that returns `{ status: "saved" }`.
+
+- **Living style guide — new "Leveling activities" group.** Adds four specimens to
+  the `/admin/style` Modals section — **change username** and a generic **quest
+  activity** (a newsletter-join), each shown **both ways** (leveling on and off) so
+  the two modes are visible regardless of the app's flag. Each demo resolves the
+  save locally, wires the active-card glow, and carries an agent-ready reference.
+
+- **`window.studioConfetti` — a zero-dependency, no-CDN confetti effect.**
+  canvas-confetti (v1.9.3, MIT) is now **vendored into the engine**
+  (`app/assets/javascripts/studio/canvas_confetti.js`) and shipped through the
+  asset pipeline instead of loaded from a CDN — CSP-safe (same-origin `:self`),
+  zero per-app dependency. `studio/studio_confetti.js` builds two callable
+  effects on top, both honoring `prefers-reduced-motion: reduce`:
+  - **`studioConfetti.burst(target)`** — the radial card-burst that explodes from
+    *behind* a card/modal, emanating from its center. Aim it with a DOM element,
+    a selector, or an `{x, y}` origin (0..1 viewport space); defaults to screen
+    center. Ported from turf-monster's `fireConfettiFromModal`.
+  - **`studioConfetti.cannons()`** — the full-screen "you joined a contest"
+    celebration: a center burst plus left + right side-cannons firing inward.
+    Same choreography as the engine head's `window.fireSuccessConfetti`.
+
+- **`.pulse-cta` — an attention pulse/glow for a CTA button**
+  (`engine-motion.css`). A gentle scale + expanding fading ring on a loop, themed
+  off the CTA role token (`--pulse-cta-color`, default `--color-cta`) so it
+  restyles per app, reduced-motion aware. Ported from turf-monster's
+  "Change Username" quest CTA (`.quest-pulse`). Named `.pulse-cta` (not
+  `.btn-pulse`) so it stays a plain motion-layer effect, not a `.btn` component
+  variant the `engine.css` contract would demand.
+
+- **Three `/admin/style` Tricks specimens** — a "Confetti & pulse" group renders
+  all three live: a "Fire burst" and "Fire cannons" demo (each surfacing the
+  `window.studioConfetti.*` call name + a copyable snippet) and the `.pulse-cta`
+  button.
+
+### Changed
+
+- The engine head (`layouts/studio/_head.html.erb`) now loads the **vendored**
+  canvas-confetti via `javascript_include_tag` rather than the jsDelivr CDN.
+  `window.fireSuccessConfetti` is unchanged and rides the same global — behavior
+  is identical, only the script source moves from CDN to a bundled engine asset.
+
 ## 0.21.0 — 2026-07-27
 
 Phase 2 of the studio-engine modal convergence: homes the entry-time age-gate DOB

data/app/assets/javascripts/studio/canvas_confetti.js

@@ -0,0 +1,17 @@
+/*
+  canvas-confetti v1.9.3 — VENDORED into studio-engine (no CDN, CSP-safe).
+  Source: https://github.com/catdad/canvas-confetti (MIT, (c) Kiril Vatev).
+  Minified build: https://cdn.jsdelivr.net/npm/canvas-confetti@1.9.3/dist/confetti.browser.min.js
+  Shipped as an engine asset so consumers get zero-per-app confetti with no
+  third-party CDN dependency. Defines the global `confetti`; studio_confetti.js
+  builds window.studioConfetti (burst/cannons) on top. To re-vendor on a bump:
+  re-fetch the pinned dist file above, keep this header, bump the version.
+*/
+/**
+ * Minified by jsDelivr using Terser v5.37.0.
+ * Original file: /npm/canvas-confetti@1.9.3/dist/confetti.browser.js
+ *
+ * Do NOT use SRI with dynamically generated files! More information: https://www.jsdelivr.com/using-sri-with-dynamic-files
+ */
+!function(t,e){!function t(e,a,n,r){var o=!!(e.Worker&&e.Blob&&e.Promise&&e.OffscreenCanvas&&e.OffscreenCanvasRenderingContext2D&&e.HTMLCanvasElement&&e.HTMLCanvasElement.prototype.transferControlToOffscreen&&e.URL&&e.URL.createObjectURL),i="function"==typeof Path2D&&"function"==typeof DOMMatrix,l=function(){if(!e.OffscreenCanvas)return!1;var t=new OffscreenCanvas(1,1),a=t.getContext("2d");a.fillRect(0,0,1,1);var n=t.transferToImageBitmap();try{a.createPattern(n,"no-repeat")}catch(t){return!1}return!0}();function s(){}function c(t){var n=a.exports.Promise,r=void 0!==n?n:e.Promise;return"function"==typeof r?new r(t):(t(s,s),null)}var h,f,u,d,m,g,p,b,M,v,y,w=(h=l,f=new Map,{transform:function(t){if(h)return t;if(f.has(t))return f.get(t);var e=new OffscreenCanvas(t.width,t.height);return e.getContext("2d").drawImage(t,0,0),f.set(t,e),e},clear:function(){f.clear()}}),x=(m=Math.floor(1e3/60),g={},p=0,"function"==typeof requestAnimationFrame&&"function"==typeof cancelAnimationFrame?(u=function(t){var e=Math.random();return g[e]=requestAnimationFrame((function a(n){p===n||p+m-1<n?(p=n,delete g[e],t()):g[e]=requestAnimationFrame(a)})),e},d=function(t){g[t]&&cancelAnimationFrame(g[t])}):(u=function(t){return setTimeout(t,m)},d=function(t){return clearTimeout(t)}),{frame:u,cancel:d}),C=(v={},function(){if(b)return b;if(!n&&o){var e=["var CONFETTI, SIZE = {}, module = {};","("+t.toString()+")(this, module, true, SIZE);","onmessage = function(msg) {","  if (msg.data.options) {","    CONFETTI(msg.data.options).then(function () {","      if (msg.data.callback) {","        postMessage({ callback: msg.data.callback });","      }","    });","  } else if (msg.data.reset) {","    CONFETTI && CONFETTI.reset();","  } else if (msg.data.resize) {","    SIZE.width = msg.data.resize.width;","    SIZE.height = msg.data.resize.height;","  } else if (msg.data.canvas) {","    SIZE.width = msg.data.canvas.width;","    SIZE.height = msg.data.canvas.height;","    CONFETTI = module.exports.create(msg.data.canvas);","  }","}"].join("\n");try{b=new Worker(URL.createObjectURL(new Blob([e])))}catch(t){return void 0!==typeof console&&"function"==typeof console.warn&&console.warn("🎊 Could not load worker",t),null}!function(t){function e(e,a){t.postMessage({options:e||{},callback:a})}t.init=function(e){var a=e.transferControlToOffscreen();t.postMessage({canvas:a},[a])},t.fire=function(a,n,r){if(M)return e(a,null),M;var o=Math.random().toString(36).slice(2);return M=c((function(n){function i(e){e.data.callback===o&&(delete v[o],t.removeEventListener("message",i),M=null,w.clear(),r(),n())}t.addEventListener("message",i),e(a,o),v[o]=i.bind(null,{data:{callback:o}})}))},t.reset=function(){for(var e in t.postMessage({reset:!0}),v)v[e](),delete v[e]}}(b)}return b}),I={particleCount:50,angle:90,spread:45,startVelocity:45,decay:.9,gravity:1,drift:0,ticks:200,x:.5,y:.5,shapes:["square","circle"],zIndex:100,colors:["#26ccff","#a25afd","#ff5e7e","#88ff5a","#fcff42","#ffa62d","#ff36ff"],disableForReducedMotion:!1,scalar:1};function T(t,e,a){return function(t,e){return e?e(t):t}(t&&null!=t[e]?t[e]:I[e],a)}function E(t){return t<0?0:Math.floor(t)}function P(t){return parseInt(t,16)}function S(t){return t.map(O)}function O(t){var e=String(t).replace(/[^0-9a-f]/gi,"");return e.length<6&&(e=e[0]+e[0]+e[1]+e[1]+e[2]+e[2]),{r:P(e.substring(0,2)),g:P(e.substring(2,4)),b:P(e.substring(4,6))}}function k(t){t.width=document.documentElement.clientWidth,t.height=document.documentElement.clientHeight}function B(t){var e=t.getBoundingClientRect();t.width=e.width,t.height=e.height}function F(t,e){e.x+=Math.cos(e.angle2D)*e.velocity+e.drift,e.y+=Math.sin(e.angle2D)*e.velocity+e.gravity,e.velocity*=e.decay,e.flat?(e.wobble=0,e.wobbleX=e.x+10*e.scalar,e.wobbleY=e.y+10*e.scalar,e.tiltSin=0,e.tiltCos=0,e.random=1):(e.wobble+=e.wobbleSpeed,e.wobbleX=e.x+10*e.scalar*Math.cos(e.wobble),e.wobbleY=e.y+10*e.scalar*Math.sin(e.wobble),e.tiltAngle+=.1,e.tiltSin=Math.sin(e.tiltAngle),e.tiltCos=Math.cos(e.tiltAngle),e.random=Math.random()+2);var a=e.tick++/e.totalTicks,n=e.x+e.random*e.tiltCos,r=e.y+e.random*e.tiltSin,o=e.wobbleX+e.random*e.tiltCos,l=e.wobbleY+e.random*e.tiltSin;if(t.fillStyle="rgba("+e.color.r+", "+e.color.g+", "+e.color.b+", "+(1-a)+")",t.beginPath(),i&&"path"===e.shape.type&&"string"==typeof e.shape.path&&Array.isArray(e.shape.matrix))t.fill(function(t,e,a,n,r,o,i){var l=new Path2D(t),s=new Path2D;s.addPath(l,new DOMMatrix(e));var c=new Path2D;return c.addPath(s,new DOMMatrix([Math.cos(i)*r,Math.sin(i)*r,-Math.sin(i)*o,Math.cos(i)*o,a,n])),c}(e.shape.path,e.shape.matrix,e.x,e.y,.1*Math.abs(o-n),.1*Math.abs(l-r),Math.PI/10*e.wobble));else if("bitmap"===e.shape.type){var s=Math.PI/10*e.wobble,c=.1*Math.abs(o-n),h=.1*Math.abs(l-r),f=e.shape.bitmap.width*e.scalar,u=e.shape.bitmap.height*e.scalar,d=new DOMMatrix([Math.cos(s)*c,Math.sin(s)*c,-Math.sin(s)*h,Math.cos(s)*h,e.x,e.y]);d.multiplySelf(new DOMMatrix(e.shape.matrix));var m=t.createPattern(w.transform(e.shape.bitmap),"no-repeat");m.setTransform(d),t.globalAlpha=1-a,t.fillStyle=m,t.fillRect(e.x-f/2,e.y-u/2,f,u),t.globalAlpha=1}else if("circle"===e.shape)t.ellipse?t.ellipse(e.x,e.y,Math.abs(o-n)*e.ovalScalar,Math.abs(l-r)*e.ovalScalar,Math.PI/10*e.wobble,0,2*Math.PI):function(t,e,a,n,r,o,i,l,s){t.save(),t.translate(e,a),t.rotate(o),t.scale(n,r),t.arc(0,0,1,i,l,s),t.restore()}(t,e.x,e.y,Math.abs(o-n)*e.ovalScalar,Math.abs(l-r)*e.ovalScalar,Math.PI/10*e.wobble,0,2*Math.PI);else if("star"===e.shape)for(var g=Math.PI/2*3,p=4*e.scalar,b=8*e.scalar,M=e.x,v=e.y,y=5,x=Math.PI/y;y--;)M=e.x+Math.cos(g)*b,v=e.y+Math.sin(g)*b,t.lineTo(M,v),g+=x,M=e.x+Math.cos(g)*p,v=e.y+Math.sin(g)*p,t.lineTo(M,v),g+=x;else t.moveTo(Math.floor(e.x),Math.floor(e.y)),t.lineTo(Math.floor(e.wobbleX),Math.floor(r)),t.lineTo(Math.floor(o),Math.floor(l)),t.lineTo(Math.floor(n),Math.floor(e.wobbleY));return t.closePath(),t.fill(),e.tick<e.totalTicks}function A(t,a){var i,l=!t,s=!!T(a||{},"resize"),h=!1,f=T(a,"disableForReducedMotion",Boolean),u=o&&!!T(a||{},"useWorker")?C():null,d=l?k:B,m=!(!t||!u)&&!!t.__confetti_initialized,g="function"==typeof matchMedia&&matchMedia("(prefers-reduced-motion)").matches;function p(e,a,o){for(var l,s,h,f,u,m=T(e,"particleCount",E),g=T(e,"angle",Number),p=T(e,"spread",Number),b=T(e,"startVelocity",Number),M=T(e,"decay",Number),v=T(e,"gravity",Number),y=T(e,"drift",Number),C=T(e,"colors",S),I=T(e,"ticks",Number),P=T(e,"shapes"),O=T(e,"scalar"),k=!!T(e,"flat"),B=function(t){var e=T(t,"origin",Object);return e.x=T(e,"x",Number),e.y=T(e,"y",Number),e}(e),A=m,R=[],N=t.width*B.x,z=t.height*B.y;A--;)R.push((l={x:N,y:z,angle:g,spread:p,startVelocity:b,color:C[A%C.length],shape:P[(f=0,u=P.length,Math.floor(Math.random()*(u-f))+f)],ticks:I,decay:M,gravity:v,drift:y,scalar:O,flat:k},s=void 0,h=void 0,s=l.angle*(Math.PI/180),h=l.spread*(Math.PI/180),{x:l.x,y:l.y,wobble:10*Math.random(),wobbleSpeed:Math.min(.11,.1*Math.random()+.05),velocity:.5*l.startVelocity+Math.random()*l.startVelocity,angle2D:-s+(.5*h-Math.random()*h),tiltAngle:(.5*Math.random()+.25)*Math.PI,color:l.color,shape:l.shape,tick:0,totalTicks:l.ticks,decay:l.decay,drift:l.drift,random:Math.random()+2,tiltSin:0,tiltCos:0,wobbleX:0,wobbleY:0,gravity:3*l.gravity,ovalScalar:.6,scalar:l.scalar,flat:l.flat}));return i?i.addFettis(R):(i=function(t,e,a,o,i){var l,s,h=e.slice(),f=t.getContext("2d"),u=c((function(e){function c(){l=s=null,f.clearRect(0,0,o.width,o.height),w.clear(),i(),e()}l=x.frame((function e(){!n||o.width===r.width&&o.height===r.height||(o.width=t.width=r.width,o.height=t.height=r.height),o.width||o.height||(a(t),o.width=t.width,o.height=t.height),f.clearRect(0,0,o.width,o.height),(h=h.filter((function(t){return F(f,t)}))).length?l=x.frame(e):c()})),s=c}));return{addFettis:function(t){return h=h.concat(t),u},canvas:t,promise:u,reset:function(){l&&x.cancel(l),s&&s()}}}(t,R,d,a,o),i.promise)}function b(a){var n=f||T(a,"disableForReducedMotion",Boolean),r=T(a,"zIndex",Number);if(n&&g)return c((function(t){t()}));l&&i?t=i.canvas:l&&!t&&(t=function(t){var e=document.createElement("canvas");return e.style.position="fixed",e.style.top="0px",e.style.left="0px",e.style.pointerEvents="none",e.style.zIndex=t,e}(r),document.body.appendChild(t)),s&&!m&&d(t);var o={width:t.width,height:t.height};function b(){if(u){var e={getBoundingClientRect:function(){if(!l)return t.getBoundingClientRect()}};return d(e),void u.postMessage({resize:{width:e.width,height:e.height}})}o.width=o.height=null}function M(){i=null,s&&(h=!1,e.removeEventListener("resize",b)),l&&t&&(document.body.contains(t)&&document.body.removeChild(t),t=null,m=!1)}return u&&!m&&u.init(t),m=!0,u&&(t.__confetti_initialized=!0),s&&!h&&(h=!0,e.addEventListener("resize",b,!1)),u?u.fire(a,o,M):p(a,o,M)}return b.reset=function(){u&&u.reset(),i&&i.reset()},b}function R(){return y||(y=A(null,{useWorker:!0,resize:!0})),y}a.exports=function(){return R().apply(this,arguments)},a.exports.reset=function(){R().reset()},a.exports.create=A,a.exports.shapeFromPath=function(t){if(!i)throw new Error("path confetti are not supported in this browser");var e,a;"string"==typeof t?e=t:(e=t.path,a=t.matrix);var n=new Path2D(e),r=document.createElement("canvas").getContext("2d");if(!a){for(var o,l,s=1e3,c=s,h=s,f=0,u=0,d=0;d<s;d+=2)for(var m=0;m<s;m+=2)r.isPointInPath(n,d,m,"nonzero")&&(c=Math.min(c,d),h=Math.min(h,m),f=Math.max(f,d),u=Math.max(u,m));o=f-c,l=u-h;var g=Math.min(10/o,10/l);a=[g,0,0,g,-Math.round(o/2+c)*g,-Math.round(l/2+h)*g]}return{type:"path",path:e,matrix:a}},a.exports.shapeFromText=function(t){var e,a=1,n="#000000",r='"Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji", "EmojiOne Color", "Android Emoji", "Twemoji Mozilla", "system emoji", sans-serif';"string"==typeof t?e=t:(e=t.text,a="scalar"in t?t.scalar:a,r="fontFamily"in t?t.fontFamily:r,n="color"in t?t.color:n);var o=10*a,i=o+"px "+r,l=new OffscreenCanvas(o,o),s=l.getContext("2d");s.font=i;var c=s.measureText(e),h=Math.ceil(c.actualBoundingBoxRight+c.actualBoundingBoxLeft),f=Math.ceil(c.actualBoundingBoxAscent+c.actualBoundingBoxDescent),u=c.actualBoundingBoxLeft+2,d=c.actualBoundingBoxAscent+2;h+=4,f+=4,(s=(l=new OffscreenCanvas(h,f)).getContext("2d")).font=i,s.fillStyle=n,s.fillText(e,u,d);var m=1/a;return{type:"bitmap",bitmap:l.transferToImageBitmap(),matrix:[m,0,0,m,-h*m/2,-f*m/2]}}}(function(){return void 0!==t?t:"undefined"!=typeof self?self:this||{}}(),e,!1),t.confetti=e.exports}(window,{});
+//# sourceMappingURL=/sm/0e9ac22f62a550282b886b288da51d7892173a94bbd286c2ffc6e7b881509c88.map

data/app/assets/javascripts/studio/studio_confetti.js

@@ -0,0 +1,93 @@
+/*
+  studio-engine — window.studioConfetti: two zero-dependency celebration effects
+  built on the vendored canvas-confetti (studio/canvas_confetti.js, no CDN).
+
+  Ported faithfully from turf-monster:
+    - burst(target)  → the radial card-burst that explodes from BEHIND a card or
+      modal, emanating from its center (TM solana_utils.js fireConfettiFromModal /
+      shared/_alpine_factories fireQuestBadgeConfetti). Pass the DOM element (or a
+      selector, or an {x,y} origin in 0..1 viewport space) to aim it; defaults to
+      screen center.
+    - cannons(opts)  → the full-screen "you joined a contest" celebration: a center
+      burst plus left + right side-cannons firing inward and a top shell (the same
+      choreography as the engine head's window.fireSuccessConfetti).
+
+  Both honor prefers-reduced-motion: reduce (no-op, and disableForReducedMotion is
+  also passed through to canvas-confetti as a second belt). Colors come from
+  window.CONFETTI_COLORS when a host sets it, else a neutral festive default.
+
+  Usage:
+    window.studioConfetti.burst(cardEl);   // radial burst behind a card/modal
+    window.studioConfetti.cannons();       // side-cannons full-screen celebration
+*/
+(function () {
+  "use strict";
+
+  var DEFAULT_COLORS = [
+    "#4BAF50", "#8E82FE", "#06D6A0", "#FF7C47",
+    "#FFD700", "#00BFFF", "#FF6B9D", "#C084FC"
+  ];
+
+  function colors(opts) {
+    return (opts && opts.colors) || window.CONFETTI_COLORS || DEFAULT_COLORS;
+  }
+
+  function reducedMotion() {
+    return !!(window.matchMedia &&
+              window.matchMedia("(prefers-reduced-motion: reduce)").matches);
+  }
+
+  // Resolve a burst origin ({x,y} in 0..1 viewport space) from an element, a
+  // selector, or a literal {x,y}. Falls back to screen center when the target is
+  // missing or not laid out (e.g. a card that just unmounted).
+  function originFor(target) {
+    var el = (typeof target === "string") ? document.querySelector(target) : target;
+    if (el && el.nodeType === 1) {
+      var r = el.getBoundingClientRect();
+      if (r.width || r.height) {
+        return {
+          x: (r.left + r.width / 2) / window.innerWidth,
+          y: (r.top + r.height / 2) / window.innerHeight
+        };
+      }
+    }
+    if (target && typeof target.x === "number" && typeof target.y === "number") {
+      return { x: target.x, y: target.y };
+    }
+    return { x: 0.5, y: 0.5 };
+  }
+
+  var studioConfetti = {
+    // Radial burst from behind a card/modal — spread:360 fires in every direction
+    // from the card center, low velocity + gravity keep it clustered around the
+    // card rather than blasting off-screen. A smaller follow-shell layers texture,
+    // and two bottom-corner sweeps give the moment theatre.
+    burst: function (target, opts) {
+      if (typeof confetti === "undefined" || reducedMotion()) return;
+      opts = opts || {};
+      var origin = originFor(target);
+      var c = colors(opts);
+      var z = opts.zIndex || 9999;
+      confetti({ particleCount: 140, angle: 90, spread: 360, origin: origin, colors: c, zIndex: z, startVelocity: 30, gravity: 0.7, ticks: 220, scalar: 1.0, disableForReducedMotion: true });
+      setTimeout(function () {
+        confetti({ particleCount: 60, angle: 60, spread: 70, origin: { x: Math.max(0, origin.x - 0.18), y: Math.min(1, origin.y + 0.05) }, colors: c, zIndex: z, startVelocity: 40, gravity: 0.9, ticks: 200, scalar: 0.9, disableForReducedMotion: true });
+        confetti({ particleCount: 60, angle: 120, spread: 70, origin: { x: Math.min(1, origin.x + 0.18), y: Math.min(1, origin.y + 0.05) }, colors: c, zIndex: z, startVelocity: 40, gravity: 0.9, ticks: 200, scalar: 0.9, disableForReducedMotion: true });
+      }, 180);
+    },
+
+    // Full-screen side-cannon celebration: center burst, then left + right cannons
+    // firing inward, then a wide top shell. Mirrors window.fireSuccessConfetti.
+    cannons: function (opts) {
+      if (typeof confetti === "undefined" || reducedMotion()) return;
+      opts = opts || {};
+      var c = colors(opts);
+      var z = opts.zIndex || 9999;
+      confetti({ particleCount: 150, spread: 100, origin: { x: 0.5, y: 0.5 }, colors: c, zIndex: z, startVelocity: 45, gravity: 0.8, ticks: 300, scalar: 1.2, disableForReducedMotion: true });
+      setTimeout(function () { confetti({ particleCount: 80, angle: 60,  spread: 60,  origin: { x: 0,   y: 0.6 }, colors: c, zIndex: z, startVelocity: 55, gravity: 1,   ticks: 250, disableForReducedMotion: true }); }, 150);
+      setTimeout(function () { confetti({ particleCount: 80, angle: 120, spread: 60,  origin: { x: 1,   y: 0.6 }, colors: c, zIndex: z, startVelocity: 55, gravity: 1,   ticks: 250, disableForReducedMotion: true }); }, 150);
+      setTimeout(function () { confetti({ particleCount: 100, spread: 160, origin: { x: 0.5, y: 0.3 }, colors: c, zIndex: z, startVelocity: 30, gravity: 1.2, ticks: 200, scalar: 0.8, disableForReducedMotion: true }); }, 400);
+    }
+  };
+
+  window.studioConfetti = studioConfetti;
+})();

data/app/assets/tailwind/studio_engine/engine-motion.css

@@ -21,6 +21,7 @@
     .studio-glow          soft themed glow halo               (authored fresh)
     .surface-glass        frosted translucent glass panel     (authored fresh)
     .conic-surface        slow rotating conic-gradient wash   (authored fresh)
+    .pulse-cta            attention pulse/glow for a CTA       (ported, TM)
 
   Leveling:
     .level-badge(-1..-10) progressive level pill ladder       (ported, TM)
@@ -1111,3 +1112,49 @@ body.modal-open { overflow: hidden; }
   @keyframes modal-card-slide-out-left  { from { opacity: 1; } to { opacity: 0; } }
   @keyframes modal-card-slide-in-right  { from { opacity: 0; } to { opacity: 1; } }
 }
+
+/* =============================================================================
+   12. pulse-cta — attention pulse/glow for a CTA button
+   A gentle "look at me" beat: the element scales up a hair while an expanding,
+   fading ring radiates from its edge, then rests, on a loop. Ported from turf-
+   monster's "Change Username" quest CTA (.quest-pulse), re-themed off the CTA
+   role token so it restyles per app (purple on McRitchie Studio) rather than TM's
+   hardcoded green. Drop it on a .btn (or any element with a solid background); for
+   a green "go" pulse set --pulse-cta-color: var(--color-success) at the call site.
+   Named pulse-cta (not btn-pulse) so it stays a plain motion-layer effect, not a
+   .btn component variant the engine.css component contract would demand.
+
+   Usage:  <button class="btn btn-primary pulse-cta">Change Username</button>
+           green pulse:  style="--pulse-cta-color: var(--color-success)"
+   Tune:   --pulse-cta-color / --pulse-cta-speed / --pulse-cta-scale /
+           --pulse-cta-ring / --pulse-cta-strength
+   ========================================================================== */
+.pulse-cta {
+  --pulse-cta-color: var(--color-cta);
+  --pulse-cta-speed: 3s;
+  --pulse-cta-scale: 1.03;
+  --pulse-cta-ring: 10px;
+  --pulse-cta-strength: 0.5;
+  animation: pulse-cta var(--pulse-cta-speed) ease-out infinite;
+}
+@keyframes pulse-cta {
+  0% {
+    transform: scale(1);
+    box-shadow: 0 0 0 0 color-mix(in srgb, var(--pulse-cta-color) calc(var(--pulse-cta-strength) * 100%), transparent);
+  }
+  10% {
+    transform: scale(var(--pulse-cta-scale));
+    box-shadow: 0 0 0 calc(var(--pulse-cta-ring) * 0.6) color-mix(in srgb, var(--pulse-cta-color) calc(var(--pulse-cta-strength) * 50%), transparent);
+  }
+  22% {
+    transform: scale(1);
+    box-shadow: 0 0 0 var(--pulse-cta-ring) color-mix(in srgb, var(--pulse-cta-color) 0%, transparent);
+  }
+  100% {
+    transform: scale(1);
+    box-shadow: 0 0 0 0 color-mix(in srgb, var(--pulse-cta-color) 0%, transparent);
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .pulse-cta { animation: none; }
+}

data/app/views/layouts/studio/_head.html.erb

@@ -21,7 +21,13 @@
 <link href="https://fonts.googleapis.com/css2?family=Montserrat:wght@400;500;600;700;800;900&display=swap" rel="stylesheet">
 
 <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
-<script src="https://cdn.jsdelivr.net/npm/canvas-confetti@1.9.3/dist/confetti.browser.min.js"></script>
+<%# canvas-confetti is VENDORED into the engine (studio/canvas_confetti.js) and
+    shipped through the asset pipeline — no CDN, CSP-safe (same-origin :self),
+    zero-per-app dependency. Defines the global `confetti`; studio_confetti.js
+    then builds window.studioConfetti (burst/cannons). fireSuccessConfetti below
+    is unchanged and rides the same global. %>
+<%= javascript_include_tag "studio/canvas_confetti", "data-turbo-track": "reload" %>
+<%= javascript_include_tag "studio/studio_confetti", "data-turbo-track": "reload" %>
 <script>
   window.fireSuccessConfetti = function() {
     if (typeof confetti === 'undefined') return;

data/app/views/studio/_leveling_activity_assets.html.erb

@@ -0,0 +1,174 @@
+<%#
+  levelingActionModal factory — the Alpine data behind the engine leveling-activity
+  modals (studio/modals/blocks/_leveling_activity and its _change_username
+  specialization). Ships here, at PAGE level, on purpose: the modal partial mounts
+  inside a modal host's single-root template, and a script cloned out of a template
+  never runs. So a consumer renders THIS once in its layout (like the other shared
+  Alpine factories), and the modal partial anywhere below just references
+  window.levelingActionModal. Mirrors how studio/_age_verify_assets homes the
+  ageVerifyModal factory.
+
+  CRITICAL BOUNDARY — this factory is UI ONLY. It POSTs to an app-supplied
+  submitUrl and reacts to a NEUTRAL JSON contract; it holds ZERO on-chain logic,
+  no wallet taxonomy, no signing. Any second step some apps need (e.g. a wallet
+  approval) is delegated OPAQUELY: the engine hands the app-returned "challenge"
+  blob to an app-supplied window[finalizeHook] and POSTs back whatever opaque
+  "proof" the app returns. The engine never inspects, parses, or decodes either
+  blob, so the whole wallet dance stays in the app.
+
+  Wire contract (submitUrl + finalizeUrl responses are JSON):
+    POST submitUrl { value } -> one of:
+      { status: "saved",     seeds_earned?, seeds_total? }   done
+      { status: "needs_step", challenge, token }             app step required
+      { status: "error",     message }                       show message
+    when needs_step and a finalizeHook is wired:
+      proof = await window[finalizeHook](challenge, { token, onProgress })
+      POST finalizeUrl { token, proof } -> { status: "saved" | "error", ... }
+
+  opts: { hasInput, initialValue, minLength, submitUrl, finalizeUrl, finalizeHook,
+          savedEvent, store, leveling, demo, seedsPerLevel }.
+    hasInput      true renders + validates a single-line input; false is a
+                  no-field activity (a plain "Complete" action).
+    initialValue  seed value for the input (a plain string; never a model).
+    minLength     client-only min length for the input (0 = none).
+    submitUrl     app endpoint the action POSTs to (the app owns persistence).
+    finalizeUrl   app endpoint for the opaque second step (omit if none).
+    finalizeHook  name of a window async fn the app supplies for the step (omit
+                  if none); it owns EVERY app-side detail of that step.
+    savedEvent    DOM event dispatched on success, carrying the app payload, so
+                  the app can run its own follow-on. Default "studio:activity-saved".
+    store         Alpine modal store name backing close(). Default "modals".
+    leveling      true shows the seeds celebration on success (a UI flourish).
+    demo          style-guide preview: resolve locally, skip the network POST.
+    seedsPerLevel seeds per level for the celebration bar. Default 100.
+%>
+<script>
+  (function () {
+    if (window.levelingActionModal) return;
+    window.levelingActionModal = function (opts) {
+      opts = opts || {};
+      return {
+        hasInput: !!opts.hasInput,
+        value: opts.initialValue || "",
+        original: opts.initialValue || "",
+        minLength: parseInt(opts.minLength, 10) || 0,
+        submitUrl: opts.submitUrl || "",
+        finalizeUrl: opts.finalizeUrl || "",
+        finalizeHook: opts.finalizeHook || "",
+        savedEvent: opts.savedEvent || "studio:activity-saved",
+        store: opts.store || "modals",
+        leveling: !!opts.leveling,
+        demo: !!opts.demo,
+        seedsPerLevel: parseInt(opts.seedsPerLevel, 10) || 100,
+        saving: false,
+        error: "",
+        saved: false,
+        celebrate: false,
+        progressLabel: "",
+        seedsEarned: 0,
+        seedsTotal: 0,
+
+        // Actionable while there is a real change to save (input activities) or
+        // until the one-shot action has fired (no-field activities).
+        get changed() {
+          if (!this.hasInput) return !this.saved;
+          var v = (this.value || "").trim();
+          if (v.length < this.minLength) return false;
+          return v !== (this.original || "").trim();
+        },
+
+        _dispatch: function (payload) {
+          try {
+            window.dispatchEvent(new CustomEvent(this.savedEvent, { detail: payload || {} }));
+          } catch (e) {}
+        },
+
+        _finishSaved: function (payload) {
+          payload = payload || {};
+          this.saving = false;
+          this.saved = true;
+          this.progressLabel = "";
+          if (this.hasInput) this.original = (this.value || "").trim();
+          this._dispatch(payload);
+          if (this.leveling) {
+            this.seedsEarned = parseInt(payload.seeds_earned, 10) || 0;
+            this.seedsTotal = parseInt(payload.seeds_total, 10) || 0;
+            this.celebrate = true;
+          }
+        },
+
+        _post: function (url, body) {
+          var csrf = (document.querySelector('meta[name="csrf-token"]') || {}).content || "";
+          var fetcher = window.authedFetch || window.fetch;
+          return fetcher(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "X-CSRF-Token": csrf, "Accept": "application/json" },
+            body: JSON.stringify(body || {})
+          }).then(function (r) {
+            return r.json().then(function (j) { return { ok: r.ok, body: j || {} }; });
+          });
+        },
+
+        save: function () {
+          if (this.saving || !this.changed) return;
+          this.saving = true;
+          this.error = "";
+          var self = this;
+          if (this.demo) {
+            // Style-guide preview: no backend. Resolve to a level-crossing payload
+            // so the leveling celebration demonstrates its full flourish.
+            setTimeout(function () {
+              self._finishSaved({ seeds_earned: 30, seeds_total: self.seedsPerLevel });
+            }, 600);
+            return;
+          }
+          var body = this.hasInput ? { value: (this.value || "").trim() } : {};
+          this._post(this.submitUrl, body)
+            .then(function (res) { return self._handle(res); })
+            .catch(function (e) {
+              self.error = (e && e.message) || "Something went wrong. Please try again.";
+              self.saving = false;
+            });
+        },
+
+        _handle: function (res) {
+          var body = (res && res.body) || {};
+          var status = body.status || (res && res.ok ? "saved" : "error");
+          if (status === "saved") { this._finishSaved(body); return; }
+          if (status === "needs_step") { return this._step(body); }
+          this.error = body.message || "Something went wrong. Please try again.";
+          this.saving = false;
+        },
+
+        // The opaque second step. The engine hands the app's "challenge" blob to
+        // the app-supplied hook and POSTs back the app's "proof" blob — it inspects
+        // neither, so every app-side detail of the step stays in the app.
+        _step: function (body) {
+          var hook = this.finalizeHook && window[this.finalizeHook];
+          var self = this;
+          if (typeof hook !== "function") {
+            this.error = "This step isn't available.";
+            this.saving = false;
+            return;
+          }
+          return Promise.resolve(
+            hook(body.challenge, {
+              token: body.token,
+              onProgress: function (label) { self.progressLabel = label || ""; }
+            })
+          ).then(function (proof) {
+            return self._post(self.finalizeUrl, { token: body.token, proof: proof });
+          }).then(function (res) {
+            var rb = (res && res.body) || {};
+            var status = rb.status || (res && res.ok ? "saved" : "error");
+            if (status === "saved") { self._finishSaved(rb); }
+            else { self.error = rb.message || "Couldn't complete the step."; self.saving = false; }
+          }).catch(function (e) {
+            self.error = (e && e.message) || "Couldn't complete the step.";
+            self.saving = false;
+          });
+        }
+      };
+    };
+  })();
+</script>

data/app/views/studio/modals/blocks/_change_username.html.erb

@@ -0,0 +1,46 @@
+<%#
+  Change-username modal — a named engine primitive, and a thin specialization of
+  studio/modals/blocks/_leveling_activity with username defaults. TWO modes via
+  the :leveling flag (quest pill + seeds celebration when on; plain input + Save +
+  Saved when off).
+
+  CRITICAL BOUNDARY — UI ONLY. The engine renders the input, the Save button, the
+  saved state, and the optional leveling chrome. The actual username SAVE is an
+  APP-SUPPLIED callback: the modal POSTs to submit_url and, if the app returns a
+  second step, delegates it opaquely to an app-supplied finalize_hook (the app's
+  managed-wallet write). No wallet, signing, keys, or on-chain writes live here.
+
+  Locals (beyond _leveling_activity's):
+    current_username (String, REQUIRED) — seed value for the input (a plain
+                     string; never current_user — no model coupling in the engine).
+    submit_url       (String, REQUIRED) — app endpoint the username POSTs to.
+    description      (String) — app-authored lead copy. Pass the wallet-aware line
+                     here (e.g. "Your username is stored on-chain. Changes are
+                     saved via your managed wallet") — the engine default stays
+                     neutral so no on-chain assumption is baked in.
+
+  Everything else (finalize_url, finalize_hook, saved_event, quest_label,
+  leveling, modal_store, demo, celebration copy) passes straight through.
+%>
+<%
+  current_username = local_assigns.fetch(:current_username)
+
+  username_locals = local_assigns.except(:current_username).reverse_merge(
+    title:              "Change Username",
+    description:        "Pick a name that's right for you.",
+    input:              true,
+    initial_value:      current_username.to_s,
+    min_length:         3,
+    max_length:         30,
+    pattern:            "[a-zA-Z0-9_-]+",
+    pattern_title:      "3-30 characters — letters, numbers, hyphens, and underscores",
+    placeholder:        "username",
+    cta_label:          "Save",
+    saved_label:        "Saved",
+    saved_event:        "studio:username-saved",
+    icon_emoji:         "🌱",
+    celebrate_title:    "Great Username",
+    celebrate_subtitle: "Nice — you earned seeds for updating your profile. Keep completing quests to earn a Free Entry."
+  )
+%>
+<%= render "studio/modals/blocks/leveling_activity", username_locals %>

data/app/views/studio/modals/blocks/_leveling_activity.html.erb

@@ -0,0 +1,159 @@
+<%#
+  Leveling-activity modal — the engine primitive behind TM's quest/leveling
+  activities (change username, join newsletter, and the rest). ONE primitive,
+  TWO modes, decided by the app's :leveling capability:
+
+    leveling ON  — the full quest framing: a "Quest N of N" pill, and on success
+                   the seeds celebration (progress bar + level-up + Free Entry).
+    leveling OFF — the plain action modal: just the action + Save, and a Saved
+                   state on success. No quest pill, no seeds. (This is the
+                   McRitchie-Studio shape: MS has no leveling, TM does.)
+
+  Same primitive; the flag decides. The leveling chrome (quest pill, seeds bar) is
+  engine-owned UI — it is NOT on-chain.
+
+  CRITICAL BOUNDARY — UI ONLY. There is NO wallet, signing, key, or on-chain write
+  anywhere in this primitive. The actual save is an APP-SUPPLIED callback: the
+  modal POSTs to submit_url and reacts to a neutral JSON contract; any wallet step
+  is delegated opaquely to an app-supplied finalize_hook (see the factory,
+  studio/_leveling_activity_assets). TM wires the managed-wallet write; MS wires a
+  trivial endpoint. Requires window.levelingActionModal — render
+  studio/leveling_activity_assets once at layout level.
+
+  Locals:
+    submit_url    (String, REQUIRED) — app endpoint the action POSTs to.
+    title         (String) — modal title. Default "Complete activity".
+    description   (String) — the app-authored lead copy. App-owned so wallet-aware
+                  prose ("saved via your managed wallet") lives app-side, never here.
+    input         (Boolean) — render a single-line input. Default false.
+    input_type    (String) — the input type (e.g. "text", "email"). Default "text".
+    initial_value (String) — seed value for the input (a plain string).
+    placeholder / min_length / max_length / pattern / pattern_title — input attrs.
+    cta_label     (String) — action button label. Default "Complete".
+    saved_label   (String) — label once saved. Default "Done".
+    saving_label  (String) — label while saving. Default "Saving…".
+    finalize_url  (String) — endpoint for the opaque second step (omit if none).
+    finalize_hook (String) — window async fn name for the step (omit if none).
+    saved_event   (String) — DOM event dispatched on success. Default
+                  "studio:activity-saved".
+    quest_label   (String) — the "Quest N of N" pill text (leveling only).
+    icon_emoji    (String) — celebration glyph. Default "🌱".
+    celebrate_title    (String) — celebration headline. Default "Activity complete".
+    celebrate_subtitle (String) — celebration subtext.
+    free_entry_label   (String) — level-up reward line. Default "Free Entry Earned 🎟️".
+    seeds_per_level    (Integer) — seeds per level. Default 100.
+    leveling      (Boolean) — override the :leveling gate. Defaults to
+                  Studio.feature?(:leveling); the style guide passes both to show
+                  each mode.
+    modal_store   (String) — Alpine store name backing close(). Default "modals".
+    demo          (Boolean) — style-guide preview: resolve locally, no POST.
+
+  Single root element (the modal host mounts this through its own template x-if).
+%>
+<%
+  submit_url         = local_assigns.fetch(:submit_url)
+  title              = local_assigns.fetch(:title, "Complete activity")
+  description        = local_assigns.fetch(:description, nil)
+  input              = local_assigns.fetch(:input, false)
+  input_type         = local_assigns.fetch(:input_type, "text")
+  initial_value      = local_assigns.fetch(:initial_value, "")
+  placeholder        = local_assigns.fetch(:placeholder, "")
+  min_length         = local_assigns.fetch(:min_length, 0)
+  max_length         = local_assigns.fetch(:max_length, nil)
+  pattern            = local_assigns.fetch(:pattern, nil)
+  pattern_title      = local_assigns.fetch(:pattern_title, nil)
+  cta_label          = local_assigns.fetch(:cta_label, "Complete")
+  saved_label        = local_assigns.fetch(:saved_label, "Done")
+  saving_label       = local_assigns.fetch(:saving_label, "Saving…")
+  finalize_url       = local_assigns.fetch(:finalize_url, "")
+  finalize_hook      = local_assigns.fetch(:finalize_hook, "")
+  saved_event        = local_assigns.fetch(:saved_event, "studio:activity-saved")
+  quest_label        = local_assigns.fetch(:quest_label, nil)
+  icon_emoji         = local_assigns.fetch(:icon_emoji, "🌱")
+  celebrate_title    = local_assigns.fetch(:celebrate_title, "Activity complete")
+  celebrate_subtitle = local_assigns.fetch(:celebrate_subtitle, "Nice — you earned seeds. Keep completing quests to earn a Free Entry.")
+  free_entry_label   = local_assigns.fetch(:free_entry_label, "Free Entry Earned 🎟️")
+  seeds_per_level    = local_assigns.fetch(:seeds_per_level, 100)
+  leveling           = local_assigns.fetch(:leveling, Studio.feature?(:leveling))
+  modal_store        = local_assigns.fetch(:modal_store, "modals")
+  demo               = local_assigns.fetch(:demo, false)
+%>
+<div x-data="levelingActionModal({
+       hasInput: <%= input ? 'true' : 'false' %>,
+       initialValue: '<%= j initial_value.to_s %>',
+       minLength: <%= min_length.to_i %>,
+       submitUrl: '<%= j submit_url %>',
+       finalizeUrl: '<%= j finalize_url %>',
+       finalizeHook: '<%= j finalize_hook %>',
+       savedEvent: '<%= j saved_event %>',
+       store: '<%= j modal_store %>',
+       leveling: <%= leveling ? 'true' : 'false' %>,
+       demo: <%= demo ? 'true' : 'false' %>,
+       seedsPerLevel: <%= seeds_per_level.to_i %>
+     })">
+
+  <%# FORM VIEW — the action. Single root inside the template. %>
+  <template x-if="!celebrate">
+    <div>
+      <%= render layout: "studio/modals/blocks/shell", locals: { title: title, modal_store: modal_store } do %>
+        <% if leveling && quest_label.present? %>
+          <div class="mb-3">
+            <span class="inline-block text-[10px] font-semibold uppercase tracking-wide text-primary bg-primary/10 px-2 py-0.5 rounded-full whitespace-nowrap"><%= quest_label %></span>
+          </div>
+        <% end %>
+
+        <% if description.present? %>
+          <p class="text-sm text-muted mb-4"><%= description %></p>
+        <% end %>
+
+        <template x-if="error">
+          <p class="text-red-400 text-sm mb-3" x-text="error"></p>
+        </template>
+
+        <form @submit.prevent="save()" class="space-y-4">
+          <% if input %>
+            <input type="<%= input_type %>" x-model="value" class="input-field w-full"
+                   placeholder="<%= placeholder %>"
+                   <%= "minlength=\"#{min_length}\"".html_safe if min_length.to_i.positive? %>
+                   <%= "maxlength=\"#{max_length}\"".html_safe if max_length.present? %>
+                   <%= "pattern=\"#{pattern}\"".html_safe if pattern.present? %>
+                   <%= "title=\"#{pattern_title}\"".html_safe if pattern_title.present? %>
+                   autofocus>
+          <% end %>
+          <button type="submit" class="btn btn-primary btn-lg w-full" :disabled="saving || !changed">
+            <span x-show="!saving" x-text="changed ? '<%= j cta_label %>' : '<%= j saved_label %>'"><%= cta_label %></span>
+            <span x-show="saving" class="inline-flex items-center justify-center gap-2" style="display: none;">
+              <span class="cta-spinner" aria-hidden="true"></span>
+              <span x-text="progressLabel || '<%= j saving_label %>'"><%= saving_label %></span>
+            </span>
+          </button>
+        </form>
+      <% end %>
+    </div>
+  </template>
+
+  <%# CELEBRATION VIEW — leveling ONLY. Rendered at ERB time only when leveling is
+      on, so a leveling-off modal ships NO seeds chrome at all (not merely
+      unmounted). Mounts once celebrate flips true so the seeds bar animates from
+      the freshly-saved payload. Single root. %>
+  <% if leveling %>
+    <template x-if="celebrate">
+      <div>
+        <%= render "studio/modals/blocks/card_header",
+              size: :lg, icon_emoji: icon_emoji,
+              title: celebrate_title, subtitle: celebrate_subtitle %>
+
+        <div class="mb-5">
+          <%= render "studio/modals/blocks/seeds_bar",
+                seeds_earned_key: "seedsEarned", seeds_total_key: "seedsTotal",
+                seeds_per_level: seeds_per_level, free_entry_label: free_entry_label %>
+        </div>
+
+        <button type="button" @click="$store.<%= modal_store %>.close()"
+                class="block mx-auto mt-3 text-sm text-secondary hover:text-heading transition">
+          Close
+        </button>
+      </div>
+    </template>
+  <% end %>
+</div>

data/app/views/style/_modals.html.erb

@@ -255,6 +255,11 @@
       specimen opens live. A consumer app renders this in its layout the same way. %>
   <%= render "studio/age_verify_assets" %>
 
+  <%# levelingActionModal factory — page level (never inside the overlay template,
+      where a cloned script would not run) so the change-username + quest-activity
+      specimens open live. A consumer app renders this in its layout the same way. %>
+  <%= render "studio/leveling_activity_assets" %>
+
   <%# ---- The overlay: one backdrop + card; every specimen's real content is a
       single-root <template x-if> gated on the current modal id. Faithful to the
       shared host — backdrop fade, scroll lock, escape + click-self dismissal
@@ -376,6 +381,49 @@
                     subtitle: "You leveled up! A Free Entry lands in your account soon. Keep leveling for more." %></div>
         </template>
 
+        <%# --- Leveling activities: change username + quest activity --- %>
+        <%# Each id renders the SAME engine primitive with an EXPLICIT leveling:
+            flag, so BOTH modes stay visible here regardless of this app's real
+            :leveling setting. All demo:true — the save resolves locally (no
+            backend), and the on-chain-accurate copy is passed as an app-authored
+            description (the engine default stays neutral). %>
+        <template x-if="$store.dsModals.current().id === 'change-username'">
+          <div><%= render "studio/modals/blocks/change_username",
+                    modal_store: "dsModals", demo: true, leveling: true,
+                    current_username: "turfmonster",
+                    submit_url: "#demo-change-username",
+                    description: "Your username is stored on-chain. Changes are saved via your managed wallet.",
+                    quest_label: "Quest 1 of 4" %></div>
+        </template>
+        <template x-if="$store.dsModals.current().id === 'change-username-plain'">
+          <div><%= render "studio/modals/blocks/change_username",
+                    modal_store: "dsModals", demo: true, leveling: false,
+                    current_username: "mcritchie",
+                    submit_url: "#demo-change-username",
+                    description: "Choose the name shown across your account." %></div>
+        </template>
+        <template x-if="$store.dsModals.current().id === 'quest-activity'">
+          <div><%= render "studio/modals/blocks/leveling_activity",
+                    modal_store: "dsModals", demo: true, leveling: true,
+                    submit_url: "#demo-quest",
+                    title: "Join the Newsletter",
+                    description: "Sports news and contest updates — complete the quest for seeds.",
+                    input: true, input_type: "email", placeholder: "you@example.com",
+                    cta_label: "Subscribe", saved_label: "Subscribed", saving_label: "Subscribing…",
+                    quest_label: "Quest 2 of 4",
+                    icon_emoji: "📬", celebrate_title: "You're in",
+                    celebrate_subtitle: "Nice — you earned seeds for joining. Keep completing quests to earn a Free Entry." %></div>
+        </template>
+        <template x-if="$store.dsModals.current().id === 'quest-activity-plain'">
+          <div><%= render "studio/modals/blocks/leveling_activity",
+                    modal_store: "dsModals", demo: true, leveling: false,
+                    submit_url: "#demo-quest",
+                    title: "Join the Newsletter",
+                    description: "Sports news and contest updates.",
+                    input: true, input_type: "email", placeholder: "you@example.com",
+                    cta_label: "Subscribe", saved_label: "Subscribed", saving_label: "Subscribing…" %></div>
+        </template>
+
       </div>
     </div>
   </template>
@@ -859,4 +907,97 @@
       <% end %>
     </div>
   </section>
+
+  <%# ===================================================================== %>
+  <%# 7. LEVELING ACTIVITIES — change username + quest activities %>
+  <%# ===================================================================== %>
+  <section class="space-y-5">
+    <div class="space-y-1">
+      <div class="flex flex-wrap items-center gap-3">
+        <h3 class="text-xl font-bold text-heading">Leveling activities</h3>
+        <% if leveling_on %>
+          <span class="badge" style="color: var(--color-success); border-color: var(--color-success)">leveling on</span>
+        <% else %>
+          <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">leveling off</span>
+        <% end %>
+      </div>
+      <p class="text-muted text-sm">
+        The quest/leveling action modals
+        (<code class="font-mono text-2xs">studio/modals/blocks/_change_username</code>,
+        <code class="font-mono text-2xs">studio/modals/blocks/_leveling_activity</code>),
+        migrated from Turf Monster. ONE primitive, <strong>two modes</strong>, decided
+        by <code class="font-mono text-2xs">Studio.feature?(:leveling)</code>:
+        <strong>leveling on</strong> adds the quest pill + the seeds level-up
+        celebration; <strong>leveling off</strong> is the plain action modal (just
+        the input + Save + a Saved state — the McRitchie Studio shape). Each modal is
+        shown <strong>both ways</strong> below (the specimens pass an explicit
+        <code class="font-mono text-2xs">leveling:</code> so both render regardless of
+        this app's flag). The actual save is an <strong>app-supplied callback</strong>:
+        the modal POSTs to <code class="font-mono text-2xs">submit_url</code> and, for
+        an app that needs a wallet step, delegates it opaquely to an app-supplied
+        <code class="font-mono text-2xs">finalize_hook</code> — <strong>no wallet,
+        signing, or on-chain write lives in the engine</strong>. (These demos resolve
+        the save locally.)
+      </p>
+    </div>
+    <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+      <%# Change username — leveling ON: quest pill + seeds celebration on save. %>
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Change username (leveling)",
+            reference: %(the "Change username" modal WITH leveling (studio-engine studio/modals/blocks/_change_username, leveling: true) — quest pill + seeds level-up celebration on save. The on-chain save is an app-supplied callback (submit_url + an opaque finalize_hook); the engine is UI only. Open with $store.dsModals.open('change-username')),
+            open_expr: "$store.dsModals.open('change-username')",
+            glow_when: ds_glow.call("change-username") } do %>
+        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 space-y-2">
+          <div class="flex items-center justify-between gap-2">
+            <span class="block h-2 w-16 rounded" style="background: var(--color-text); opacity: .18"></span>
+            <span class="text-[8px] font-semibold uppercase rounded-full px-1.5 py-0.5" style="color: var(--color-primary); background: color-mix(in srgb, var(--color-primary) 12%, transparent)">Quest 1/4</span>
+          </div>
+          <span class="block h-6 w-full rounded border" style="border-color: var(--color-border-strong)"></span>
+          <span class="block h-5 w-full rounded" style="background: var(--color-cta)"></span>
+        </div>
+      <% end %>
+
+      <%# Change username — leveling OFF: the plain MS-style action + Save. %>
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Change username (plain)",
+            reference: %(the "Change username" modal WITHOUT leveling (studio-engine studio/modals/blocks/_change_username, leveling: false) — the plain McRitchie Studio shape: input + Save, then a Saved state. No quest pill, no seeds. Same primitive, flag off. Open with $store.dsModals.open('change-username-plain')),
+            open_expr: "$store.dsModals.open('change-username-plain')",
+            glow_when: ds_glow.call("change-username-plain") } do %>
+        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 space-y-2">
+          <span class="block h-2 w-16 rounded" style="background: var(--color-text); opacity: .18"></span>
+          <span class="block h-6 w-full rounded border" style="border-color: var(--color-border-strong)"></span>
+          <span class="block h-5 w-full rounded" style="background: var(--color-cta)"></span>
+        </div>
+      <% end %>
+
+      <%# Quest activity — leveling ON: generic quest (newsletter join) + seeds. %>
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Quest activity (leveling)",
+            reference: %(a generic quest activity WITH leveling (studio-engine studio/modals/blocks/_leveling_activity, leveling: true) — here a "Join the Newsletter" quest: quest pill + seeds celebration on complete. Covers join-newsletter / send-message and the rest as ONE parameterized primitive. Open with $store.dsModals.open('quest-activity')),
+            open_expr: "$store.dsModals.open('quest-activity')",
+            glow_when: ds_glow.call("quest-activity") } do %>
+        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 space-y-2">
+          <div class="flex items-center justify-between gap-2">
+            <span class="text-lg leading-none">📬</span>
+            <span class="text-[8px] font-semibold uppercase rounded-full px-1.5 py-0.5" style="color: var(--color-primary); background: color-mix(in srgb, var(--color-primary) 12%, transparent)">Quest 2/4</span>
+          </div>
+          <span class="block h-6 w-full rounded border" style="border-color: var(--color-border-strong)"></span>
+          <span class="block h-5 w-full rounded" style="background: var(--color-cta)"></span>
+        </div>
+      <% end %>
+
+      <%# Quest activity — leveling OFF: the plain action (no quest, no seeds). %>
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Quest activity (plain)",
+            reference: %(the SAME generic activity WITHOUT leveling (studio-engine studio/modals/blocks/_leveling_activity, leveling: false) — a plain "Join the Newsletter" action: input + Subscribe, then Subscribed. No quest pill, no seeds. Open with $store.dsModals.open('quest-activity-plain')),
+            open_expr: "$store.dsModals.open('quest-activity-plain')",
+            glow_when: ds_glow.call("quest-activity-plain") } do %>
+        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 space-y-2">
+          <span class="text-lg leading-none">📬</span>
+          <span class="block h-6 w-full rounded border" style="border-color: var(--color-border-strong)"></span>
+          <span class="block h-5 w-full rounded" style="background: var(--color-cta)"></span>
+        </div>
+      <% end %>
+    </div>
+  </section>
 </section>

data/app/views/style/_tricks.html.erb

@@ -259,6 +259,52 @@
     </div>
   </section>
 
+  <!-- Confetti & pulse -->
+  <section class="space-y-5">
+    <div class="space-y-1">
+      <h3 class="text-xl font-bold text-heading">Confetti &amp; pulse</h3>
+      <p class="text-muted text-sm max-w-2xl">
+        Celebration effects lifted from Turf Monster into the engine. Confetti is
+        <code class="font-mono text-2xs">window.studioConfetti</code> - a zero-dependency,
+        no-CDN effect (canvas-confetti is vendored into the engine and shipped through the
+        asset pipeline). Two callable variants, both honoring
+        <code class="font-mono text-2xs">prefers-reduced-motion</code>. The pulse is the
+        <code class="font-mono text-2xs">.pulse-cta</code> attention beat. Fire the confetti
+        with the buttons below.
+      </p>
+    </div>
+    <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+      <%= render layout: "style/specimen",
+            locals: { klass: "window.studioConfetti.burst(el)",
+                      usage: %(window.studioConfetti.burst(cardEl)\n// radial burst from behind a card/modal, from its center) } do %>
+        <div x-data="{}" class="flex flex-col items-center gap-3 py-2">
+          <div x-ref="burstCard" class="card px-5 py-4 text-sm font-semibold text-heading text-center">Success!</div>
+          <button type="button" class="btn btn-primary btn-sm"
+                  @click="window.studioConfetti && window.studioConfetti.burst($refs.burstCard)">Fire burst</button>
+        </div>
+      <% end %>
+
+      <%= render layout: "style/specimen",
+            locals: { klass: "window.studioConfetti.cannons()",
+                      usage: %(window.studioConfetti.cannons()\n// left + right side-cannons, full-screen celebration) } do %>
+        <div x-data="{}" class="flex flex-col items-center gap-3 py-2">
+          <p class="text-sm font-semibold text-heading text-center">You joined a contest!</p>
+          <button type="button" class="btn btn-success btn-sm"
+                  @click="window.studioConfetti && window.studioConfetti.cannons()">Fire cannons</button>
+        </div>
+      <% end %>
+
+      <%= render layout: "style/specimen",
+            locals: { klass: ".pulse-cta  (knobs: --pulse-cta-color / -speed / -scale)",
+                      usage: %(<button class="btn btn-primary pulse-cta">Change Username</button>\n<button class="btn btn-success pulse-cta" style="--pulse-cta-color: var(--color-success)">Go</button>) } do %>
+        <div class="flex flex-wrap items-center justify-center gap-4">
+          <button type="button" class="btn btn-primary pulse-cta">Change Username</button>
+          <button type="button" class="btn btn-success pulse-cta" style="--pulse-cta-color: var(--color-success)">Go</button>
+        </div>
+      <% end %>
+    </div>
+  </section>
+
   <!-- Leveling (capability-gated: Studio.feature?(:leveling)) -->
   <section class="space-y-5">
     <div class="space-y-1">

data/lib/studio/engine.rb

@@ -4,6 +4,8 @@ module Studio
       app.config.assets.precompile += %w[
         studio/sticky_table_header.css
         studio/sticky_table_header.js
+        studio/canvas_confetti.js
+        studio/studio_confetti.js
       ]
     end
 

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.21.0"
+  VERSION = "0.22.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.22.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -170,7 +170,9 @@ files:
 - README.md
 - app/assets/images/resend-favicon.png
 - app/assets/images/ses-favicon.png
+- app/assets/javascripts/studio/canvas_confetti.js
 - app/assets/javascripts/studio/sticky_table_header.js
+- app/assets/javascripts/studio/studio_confetti.js
 - app/assets/stylesheets/studio/sticky_table_header.css
 - app/assets/tailwind/studio_engine/engine-motion.css
 - app/assets/tailwind/studio_engine/engine.css
@@ -246,6 +248,7 @@ files:
 - app/views/studio/_age_verify_assets.html.erb
 - app/views/studio/_confirm_interstitial.html.erb
 - app/views/studio/_cropper_assets.html.erb
+- app/views/studio/_leveling_activity_assets.html.erb
 - app/views/studio/admin_models/_arenas_table.html.erb
 - app/views/studio/admin_models/_teams_table.html.erb
 - app/views/studio/admin_models/index.html.erb
@@ -266,11 +269,13 @@ files:
 - app/views/studio/modals/auth/_resend_footer.html.erb
 - app/views/studio/modals/blocks/_age_verify.html.erb
 - app/views/studio/modals/blocks/_card_header.html.erb
+- app/views/studio/modals/blocks/_change_username.html.erb
 - app/views/studio/modals/blocks/_cta_redirect.html.erb
 - app/views/studio/modals/blocks/_digit_reel.html.erb
 - app/views/studio/modals/blocks/_entry_confirmed.html.erb
 - app/views/studio/modals/blocks/_error_card.html.erb
 - app/views/studio/modals/blocks/_free_entry_earned.html.erb
+- app/views/studio/modals/blocks/_leveling_activity.html.erb
 - app/views/studio/modals/blocks/_onchain_success.html.erb
 - app/views/studio/modals/blocks/_processing_card.html.erb
 - app/views/studio/modals/blocks/_progress_countdown.html.erb