studio-engine 0.21.0 → 0.23.0

data/app/views/studio/board/_board.html.erb

@@ -0,0 +1,151 @@
+<%#
+  studio/board — the shared kanban / depth-chart board shell. An ADDITIVE engine
+  primitive (Phase D): the SortableJS drag-reorder, optimistic cross-column move →
+  revert → toast, and count/live wiring that the three near-identical McRitchie
+  Studio boards (tasks / news / content) and the depth chart each hand-rolled,
+  lifted into one place. Renders a horizontal row of columns, each a drop zone the
+  vendored SortableJS + window.studioBoard factory (studio/_board_assets, rendered
+  once at layout level — a <script> inside this component template would never run)
+  wires.
+
+  UI ONLY and NEUTRAL: no model, no routes, no domain. The app supplies its columns,
+  its card partial, and its endpoints. Custom behavior attaches by LISTENING to the
+  DOM events the factory dispatches on window — `studio:board-moved`,
+  `studio:board-reordered`, `studio:card-added` (detail `{ record, from, to }`) —
+  never by patching the factory. Heavier per-app animation defers OPAQUELY to a
+  `fx:` module (window[<name>]) and to `on_move_hook:` / `on_drop_hook:` fns.
+
+  The identity contract every card + zone must satisfy is emitted by
+  studio/board/_column (the `.kanban-dropzone`) and studio/board/_card_shell (the
+  `.kanban-card`) — an app may hand-roll a bespoke card as long as it matches.
+
+  locals:
+    columns:          (req) [{ key:, label:, cards:, count:, badge_class:,
+                      collapsible:, hidden:, header_extra: }]. `cards` are records
+                      passed to `card_partial`; `count` defaults to cards.size.
+    card_partial:     (req) partial rendered per card (e.g. "tasks/task_card").
+    card_as:          local the record binds to in card_partial. Default :card.
+    card_locals:      per-card extra locals — a Proc ->(record){ Hash } or a Hash.
+    reorder_url:      POST endpoint the drag-reorder saves the new order to.
+    reorder_payload:  :slugs | :ids — the key the ordered id list POSTs under.
+                      Default :slugs.
+    move_url:         PATCH template for a cross-column move, ":id" → the card's id
+                      (e.g. "/tasks/:id.json"). nil disallows moves (reorder only).
+    move_param:       { resource:, attr: } → PATCH body { resource => { attr => zone } }.
+                      nil disallows moves.
+    group:            SortableJS group — a shared string allows cross-column drags;
+                      false keeps drags within a zone (the depth-chart shape).
+                      Default "studio-board".
+    id_attr:          card id data-attr + dom-id suffix. Default "slug".
+    zone_attr:        column/zone data-attr. Default "stage".
+    handle:           drag-handle selector (nil = whole card draggable).
+    filter:           SortableJS filter (undraggable els). Default ".kanban-empty".
+    zone_selector:    the drop-zone selector. Default ".kanban-dropzone".
+    draggable:        the card selector. Default ".kanban-card".
+    empty_selector:   the empty-state selector (revert anchor + count toggle).
+                      Default ".kanban-empty"; nil for a board with no empty state.
+    live_channel:     Turbo Stream channel for live updates (nil = static board).
+    optimistic:       revert + red-ring flash a failed move. Default true.
+    toasts:           show the toast host (false = window.alert on error). Default true.
+    empty_label:      empty-zone text. Default "Drop here".
+    header_slot:      raw HTML rendered above the columns (pass html_safe content).
+    above_board_slot: raw HTML rendered between the header and the columns.
+    fx:               window[<name>] module the factory defers add/exit anims to.
+    on_move_hook:     window[<name>] opaque fn, called with { record, from, to }.
+    on_drop_hook:     window[<name>] opaque fn, called with { ids, zone }.
+    demo:             style-guide preview — drag works locally, no network POST.
+%>
+<%
+  columns          = local_assigns.fetch(:columns)
+  card_partial     = local_assigns.fetch(:card_partial)
+  card_as          = local_assigns.fetch(:card_as, :card)
+  card_locals      = local_assigns.fetch(:card_locals, nil)
+  reorder_url      = local_assigns.fetch(:reorder_url, "")
+  reorder_payload  = local_assigns.fetch(:reorder_payload, :slugs).to_s
+  move_url         = local_assigns.fetch(:move_url, nil)
+  move_param       = local_assigns.fetch(:move_param, nil)
+  group            = local_assigns.fetch(:group, "studio-board")
+  id_attr          = local_assigns.fetch(:id_attr, "slug").to_s
+  zone_attr        = local_assigns.fetch(:zone_attr, "stage").to_s
+  handle           = local_assigns.fetch(:handle, nil)
+  sort_filter      = local_assigns.fetch(:filter, ".kanban-empty")
+  zone_selector    = local_assigns.fetch(:zone_selector, ".kanban-dropzone")
+  draggable_sel    = local_assigns.fetch(:draggable, ".kanban-card")
+  empty_selector   = local_assigns.fetch(:empty_selector, ".kanban-empty")
+  dom_id_prefix    = local_assigns.fetch(:dom_id_prefix, "card-")
+  live_channel     = local_assigns.fetch(:live_channel, nil)
+  optimistic       = local_assigns.fetch(:optimistic, true)
+  toasts           = local_assigns.fetch(:toasts, true)
+  empty_label      = local_assigns.fetch(:empty_label, "Drop here")
+  header_slot      = local_assigns.fetch(:header_slot, nil)
+  above_board_slot = local_assigns.fetch(:above_board_slot, nil)
+  fx               = local_assigns.fetch(:fx, nil)
+  on_move_hook     = local_assigns.fetch(:on_move_hook, nil)
+  on_drop_hook     = local_assigns.fetch(:on_drop_hook, nil)
+  demo             = local_assigns.fetch(:demo, false)
+
+  board_opts = {
+    zoneSelector:   zone_selector,
+    draggable:      draggable_sel,
+    emptySelector:  empty_selector,
+    group:          (group == false ? false : group.to_s),
+    handle:         handle,
+    filter:         sort_filter,
+    idAttr:         id_attr,
+    zoneAttr:       zone_attr,
+    domIdPrefix:    dom_id_prefix,
+    moveUrl:        move_url,
+    moveParam:      (move_param ? { resource: move_param[:resource].to_s, attr: move_param[:attr].to_s } : nil),
+    reorderUrl:     reorder_url,
+    reorderPayload: reorder_payload,
+    optimistic:     !!optimistic,
+    toasts:         !!toasts,
+    live:           live_channel.present?,
+    demo:           !!demo,
+    fx:             fx,
+    onMoveHook:     on_move_hook,
+    onDropHook:     on_drop_hook,
+    labels:         columns.each_with_object({}) { |c, h| h[c[:key].to_s] = (c[:label] || c[:key]).to_s if c[:key] }
+  }
+%>
+<section class="studio-board" data-test="studio-board" x-data="studioBoard(<%= board_opts.to_json %>)">
+  <% if live_channel.present? %><%= turbo_stream_from live_channel %><% end %>
+
+  <% if header_slot %><div class="studio-board-header mb-4"><%= header_slot %></div><% end %>
+  <% if above_board_slot %><%= above_board_slot %><% end %>
+
+  <div class="flex flex-col gap-4 overflow-x-visible pb-4 sm:flex-row sm:overflow-x-auto">
+    <% columns.each do |column| %>
+      <%= render "studio/board/column",
+            column: column,
+            zone_attr: zone_attr,
+            dom_id_prefix: dom_id_prefix,
+            zone_selector_class: zone_selector.delete_prefix("."),
+            empty_selector_class: (empty_selector || "kanban-empty").delete_prefix("."),
+            empty_label: empty_label,
+            card_partial: card_partial,
+            card_as: card_as,
+            card_locals: card_locals %>
+    <% end %>
+  </div>
+
+  <% if toasts %>
+    <div class="studio-board-toasts fixed top-4 right-4 z-50 space-y-2" data-test="studio-board-toasts">
+      <template x-for="toast in toasts" :key="toast.id">
+        <div x-show="toast.visible"
+             x-transition:enter="transition ease-out duration-300"
+             x-transition:enter-start="opacity-0 translate-x-8"
+             x-transition:enter-end="opacity-100 translate-x-0"
+             x-transition:leave="transition ease-in duration-200"
+             x-transition:leave-start="opacity-100 translate-x-0"
+             x-transition:leave-end="opacity-0 translate-x-8"
+             class="bg-surface border rounded-lg px-4 py-2.5 text-sm font-medium shadow-lg backdrop-blur-sm"
+             :style="toast.type === 'success'
+                       ? 'border-color: var(--color-success); color: var(--color-success)'
+                       : 'border-color: var(--color-danger); color: var(--color-danger)'">
+          <span x-text="toast.message"></span>
+        </div>
+      </template>
+    </div>
+  <% end %>
+</section>

data/app/views/studio/board/_card_shell.html.erb

@@ -0,0 +1,47 @@
+<%#
+  studio/board/card_shell — OPTIONAL chrome that emits the board CARD half of the
+  identity contract, so a card partial can `render layout: "studio/board/card_shell"`
+  around its own body instead of hand-rolling the wrapper. It emits:
+
+    id="<dom_id_prefix><id>"      (default id="card-<id>")
+    data-<id_attr>="<id>"         (default data-slug — window.studioBoard reads this)
+    data-<zone_attr>="<zone>"     (default data-stage — the card's current column)
+    class="kanban-card <extra>"   (the SortableJS draggable + live-observe hook)
+
+  Apps may SKIP this and hand-roll a bespoke card, as long as it satisfies the same
+  contract (that is the point of the primitive — the contract, not this exact
+  markup). UI only; no domain, no persistence.
+
+  Checks local_assigns (never block_given?) for its locals, but always yields the
+  caller block — it is only ever used as a `render layout:` wrapper.
+
+  locals:
+    id:            (req) the card id value (a slug / record id).
+    zone:          (req) the card's current column/zone key.
+    id_attr:       data-attr name for the id. Default "slug".
+    zone_attr:     data-attr name for the zone. Default "stage".
+    dom_id_prefix: dom-id prefix. Default "card-".
+    card_class:    the required base class. Default "kanban-card".
+    class:         extra classes appended after card_class.
+    style:         inline style string.
+    attrs:         Hash of extra root attributes ({ "x-data" => "…", "data-foo" => 1 }),
+                   values are HTML-escaped — the rebase seam for a card that carries
+                   its own Alpine/data-* on the root.
+%>
+<%
+  id            = local_assigns.fetch(:id)
+  zone          = local_assigns.fetch(:zone)
+  id_attr       = local_assigns.fetch(:id_attr, "slug")
+  zone_attr     = local_assigns.fetch(:zone_attr, "stage")
+  dom_id_prefix = local_assigns.fetch(:dom_id_prefix, "card-")
+  card_class    = local_assigns.fetch(:card_class, "kanban-card")
+  extra_class   = local_assigns.fetch(:class, nil)
+  inline_style  = local_assigns.fetch(:style, nil)
+  root_attrs    = local_assigns.fetch(:attrs, {}) || {}
+%>
+<div id="<%= dom_id_prefix %><%= id %>"
+     class="<%= [card_class, extra_class].compact.join(" ") %>"
+     data-<%= id_attr %>="<%= id %>"
+     data-<%= zone_attr %>="<%= zone %>"
+     <% root_attrs.each do |name, value| %><%= name %>="<%= value %>" <% end %>
+     <% if inline_style %>style="<%= inline_style %>"<% end %>><%= yield %></div>

data/app/views/studio/board/_column.html.erb

@@ -0,0 +1,80 @@
+<%#
+  studio/board/column — ONE board column: the header (label + count), the drop
+  zone (the SortableJS target), its cards, and the empty state. Emits the ZONE half
+  of the board identity contract:
+
+    id="dropzone-<key>"           (window.studioBoard.updateCounts reads this)
+    class="kanban-dropzone …"     (the SortableJS + live-observe target)
+    data-<zone_attr>="<key>"      (the column key a dropped card moves TO)
+
+  Cards emit the other half (see studio/board/_card_shell). Rendered by
+  studio/board/_board; not usually rendered directly.
+
+  locals:
+    column:               (req) { key:, label:, cards:, count:, badge_class:,
+                          collapsible:, hidden:, header_extra: }. `cards` are the
+                          records passed to the card partial; `count` defaults to
+                          cards.size; `badge_class` picks a components/_badge scheme
+                          for the count (else a plain neutral count chip).
+    zone_attr:            data-attr name for the zone. Default "stage".
+    dom_id_prefix:        card dom-id prefix, forwarded to the cards. Default "card-".
+    zone_selector_class:  the drop-zone class. Default "kanban-dropzone".
+    empty_selector_class: the empty-state class. Default "kanban-empty".
+    empty_label:          empty-zone text. Default "Drop here".
+    card_partial:         (req) partial rendered per card.
+    card_as:              local the record binds to in card_partial. Default :card.
+    card_locals:          per-card extra locals — a Proc ->(record){ Hash } or Hash.
+%>
+<%
+  column               = local_assigns.fetch(:column)
+  zone_attr            = local_assigns.fetch(:zone_attr, "stage")
+  dom_id_prefix        = local_assigns.fetch(:dom_id_prefix, "card-")
+  zone_selector_class  = local_assigns.fetch(:zone_selector_class, "kanban-dropzone")
+  empty_selector_class = local_assigns.fetch(:empty_selector_class, "kanban-empty")
+  empty_label          = local_assigns.fetch(:empty_label, "Drop here")
+  card_partial         = local_assigns.fetch(:card_partial)
+  card_as              = local_assigns.fetch(:card_as, :card)
+  card_locals          = local_assigns.fetch(:card_locals, nil)
+
+  key          = column[:key].to_s
+  label        = column[:label] || key
+  cards        = column[:cards] || []
+  count        = column.fetch(:count) { cards.size }
+  badge_class  = column[:badge_class]
+  collapsible  = column[:collapsible]
+  hidden       = column[:hidden]
+  header_extra = column[:header_extra]
+
+  # Merge the per-card hook (Proc or Hash) with the record binding.
+  resolve_locals = lambda do |record|
+    extra = card_locals.respond_to?(:call) ? card_locals.call(record) : (card_locals || {})
+    { card_as => record }.merge(extra || {})
+  end
+%>
+<div class="studio-board-column w-full flex-none sm:flex-1 sm:min-w-[190px]"
+     data-board-column="<%= key %>"
+     <% if collapsible %>data-board-collapsible="true"<% end %>
+     <% if hidden %>x-cloak style="display:none"<% end %>>
+  <div class="mb-3 px-1 flex items-center gap-2">
+    <h3 class="text-sm font-bold text-heading uppercase tracking-wider"><%= label %></h3>
+    <% if badge_class %>
+      <%= render "components/badge", text: count.to_s, scheme: badge_class, data_board_count: key %>
+    <% else %>
+      <span class="stage-count inline-flex items-center justify-center min-w-[20px] h-5 px-1.5 rounded-full text-xs font-bold bg-surface-alt text-secondary border border-subtle"
+            data-board-count="<%= key %>"><%= count %></span>
+    <% end %>
+    <% if header_extra %><%= header_extra %><% end %>
+  </div>
+
+  <div id="dropzone-<%= key %>"
+       data-<%= zone_attr %>="<%= key %>"
+       class="<%= zone_selector_class %> rounded-xl border-2 border-dashed border-subtle min-h-40 p-2 space-y-2 transition-colors duration-150 sm:min-h-[calc(100vh-220px)]">
+    <% cards.each do |record| %>
+      <%= render partial: card_partial, locals: resolve_locals.call(record) %>
+    <% end %>
+    <div class="<%= empty_selector_class %> flex items-center justify-center h-24 text-muted text-sm"
+         <% if cards.any? %>style="display: none"<% end %>>
+      <%= empty_label %>
+    </div>
+  </div>
+</div>

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>