studio-engine 0.45.0 → 0.46.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2291a2d35bfd35a6f54666fd0e3590a9a59275e453cf5ff81ddd2af49717301
-  data.tar.gz: 5ca713c12be81b7353ebd98f281ef89017a02e6fd348e77d6468383e8d85a90d
+  metadata.gz: 026c018bce499134d15e23ca2f9101e05da752380be210e5c6136babbac97a5a
+  data.tar.gz: ff33bee4cbe01664a9f2385716107d0a7319e0b267cc9a1f6c4a47e0555c4c5a
 SHA512:
-  metadata.gz: d8bc026356b0f6e2e1d0b0781719960001dc7fd5bb629b6fd3e7e59a7d3b1ac298f94dc4b88941c709956f49368675089e507ace0851a6f234321f14b5868f07
-  data.tar.gz: cceface91adc12a32ad02246d67a58a93306fd44dce24a12ffd8a54a4350d840f52c8e7537634cddd524d0a5372d5ab4ff216fc6c9760bd725fc4a408ef11f55
+  metadata.gz: 25dedda1d9c8f5c7cc2f485cfcea80e94ce3446952029015d5e53ab1dd41fdbfd014dc1c1251f9c637ab7fbd3605b7aa50e0593e4d4e85b1a81c6349536dd7ea
+  data.tar.gz: 8f71ee45ddf77e12851991857aff2a72bfe3082719b7505c16b8fc7cd08d17c5bf502c07af2393aa315c22146067ef63af1d275d9566d327193d9fa935a94a72

data/CHANGELOG.md

@@ -35,6 +35,83 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Added
 
+- **The standard user profile columns — and the engine's first migration against
+  a host-owned table.** Every other engine migration creates a `studio_*` table
+  the engine owns outright; `users` belongs to the host. That boundary is crossed
+  deliberately, on the operator's call, because the alternative was three
+  hand-written migrations kept identical by discipline alone — and column drift
+  across apps is the exact thing a standard prevents.
+
+  | Column | Type | Why |
+  |---|---|---|
+  | `first_name` | string | The shared onboarding ask. MS and TM already had it; MI did not. |
+  | `birth_day` / `birth_month` / `birth_year` | integer | Age needs the year plus month/day for the boundary case; "whose birthday is today" needs month + day and no year at all. |
+  | `ip_locations` | jsonb, default `[]` | The distinct places an account has been seen from. |
+
+  Three integers rather than one date is the point: **no single date-of-birth
+  column is stored.** turf-monster's `AgePolicy` composes a `Date` from the trio.
+  turf already had `birth_year` as an integer, so it matches exactly.
+
+  **Every add is `if_not_exists: true`, and the migration no-ops when the app has
+  no `users` table.** Both matter: the apps disagree today (MS and TM already have
+  `first_name`, turf already has `birth_year`), and an unguarded add would mean
+  the engine breaking consumers that did nothing wrong. Migrations are
+  install-copied (`bin/rails studio_engine:install:migrations`), so each app still
+  adopts deliberately.
+
+  `Studio::IpLocations` owns the analytics shape so it cannot drift: string keys
+  and ISO-8601 times (it round-trips through jsonb), dedupe on the **place**
+  rather than the address — two sign-ins from Austin are one entry however many
+  IPs they arrive from — a 50-entry cap, and loopback/private ranges skipped so
+  dev sessions don't crowd out real ones. `Studio.record_ip_location!(user, ip:,
+  country:, region:, city:)` writes only when the place is **new**: this sits on
+  the request path, and refreshing a counter per hit would be a database write
+  per page view. The host resolves the location — turf already has Geocoder wired
+  in `ApplicationController#detect_geo_state` — and an app that has not run the
+  migration records nothing rather than raising.
+
+  `ip_locations` holds IP-derived location data, which is personal data in most
+  jurisdictions. The cap bounds it, and no app writes to it until it opts in.
+
+- **First-name capture as a shared onboarding step.** Every Studio app addresses
+  people by name in email, and all three were going to write the same modal and
+  the same controller. Ported out of turf-monster, where it shipped first:
+
+  | Piece | What it is |
+  |---|---|
+  | `studio/modals/onboarding/_first_name` | The step's UI. Every endpoint and label is a local with a default, so a host mounting it elsewhere does not fork the partial. Previewable at `/admin/style#modals`. |
+  | `Studio::OnboardingController` | The two writes — `#first_name` and `#skip_first_name`, JSON only. |
+  | `Studio.first_name_outstanding?(user, session)` | The one rule every app agrees on: blank field, not skipped this session. |
+  | `Studio.onboarding_steps_resolver` | How a host declares what comes NEXT. |
+
+  **The engine owns ONE STEP; the host owns the SEQUENCE.** turf walks
+  welcome → first name → age → wallet, which means nothing in a hub app. The
+  partial never opens another modal — it reports the remaining steps upward and
+  closes — and the controller's `next` array is whatever the host's resolver
+  returns. The default is empty, which is the right answer for an app whose only
+  ask is the name: opt in, and it works with no further configuration.
+
+  Skipping is **session-scoped on purpose**. It means "not now", not "never" —
+  the column stays blank, so a later session may ask again. That is the whole
+  reason it is not a users column.
+
+  **The endpoints are OPT-IN (`config.draw_onboarding_routes = true`), and they
+  have to be** — the same hard constraint as `/admin/emails`. turf-monster owns
+  `onboarding_first_name_path` and `onboarding_skip_first_name_path` TODAY, and
+  drawing them there raises `Invalid route name, already in use` while that app's
+  routes load, taking down its entire route set. Consumer CI runs each consumer's
+  default branch, so this cannot be fixed from inside the engine. Each app's
+  adoption task flips the flag as it deletes its local copy.
+
+  Two consumer notes:
+
+  - **turf-monster** deletes `OnboardingController`, its two routes, and points
+    its `OnboardingFlow` at `Studio.first_name_outstanding?`. Net deletion.
+  - **mcritchie-industries** has **no `users.first_name` column**. The rule
+    tolerates that — an app that has not run the migration is simply never asked,
+    rather than raising on every signed-in request — so the gem can land there
+    before the migration does.
+
 - **`Studio::NewsletterMailer` — a sendable "you're on the list" email.**
   Namespaced under `Studio::` on purpose: a host that defines its own top-level
   `UserMailer` (McRitchie Studio does) SHADOWS the engine's outright, so an

data/app/controllers/studio/onboarding_controller.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Studio
+  # The first-name onboarding step's two writes — capture a name, or record that
+  # the account skipped it. Ported from turf-monster (2026-08), where this ran as
+  # a local OnboardingController, because the same ask is wanted in every Studio
+  # app: McRitchie Studio, McRitchie Industries, and turf-monster all address
+  # people by name in email, and all three were going to write this controller.
+  #
+  # What the ENGINE owns here is ONE STEP. What each HOST still owns is the
+  # SEQUENCE around it — turf walks welcome → first name → age → wallet; a hub app
+  # may ask nothing else. Hosts declare that through
+  # Studio.onboarding_steps_resolver, whose value this returns as `next` so the
+  # client keeps walking without a second round trip.
+  #
+  # A plain host-inherited controller (same shape as StyleController and
+  # Studio::EmailsController): it renders no layout of its own, answers JSON only,
+  # and picks up the host's authentication from ApplicationController.
+  #
+  # Routes are OPT-IN via Studio.draw_onboarding_routes — turf-monster owns these
+  # helper names until its adoption task deletes the local pair.
+  class OnboardingController < ::ApplicationController
+    # Both actions are for the freshly signed-in user, so authentication is the
+    # host's default require_authentication — no skip_before_action here.
+
+    MAX_FIRST_NAME = 40
+
+    # POST /onboarding/first_name
+    #
+    # Writes users.first_name, and backfills `name` when it is blank so the
+    # display-name chain has something better than an email prefix to show.
+    def first_name
+      value = params[:first_name].to_s.strip.gsub(/\s+/, " ").first(MAX_FIRST_NAME)
+
+      if value.blank?
+        return render json: { ok: false, error: "Enter your first name, or skip for now." },
+                      status: :unprocessable_entity
+      end
+
+      rescue_and_log(target: current_user) do
+        # update_columns, not update!: this runs seconds after signup, on an
+        # account that may be mid-onboarding, and a validation failure elsewhere
+        # on the record (a grandfathered reserved username, say) must not block a
+        # first name. It also steps around any host before_save that DERIVES
+        # first_name FROM name — turf's set_name_parts does exactly that, and
+        # writing through it would discard the value we were just handed.
+        attrs = { first_name: value }
+        attrs[:name] = value if current_user.name.blank?
+        current_user.update_columns(attrs)
+
+        render json: { ok: true, first_name: value, next: remaining_steps }
+      end
+    end
+
+    # POST /onboarding/skip_first_name
+    #
+    # Session-scoped, deliberately: skipping means "not now", not "never". A later
+    # session can ask again (the field is still blank), which is the whole reason
+    # this is not a users column.
+    def skip_first_name
+      session[Studio::FIRST_NAME_SKIP_SESSION_KEY] = true
+      render json: { ok: true, next: remaining_steps }
+    end
+
+    private
+
+    # What is left AFTER this write. The host's resolver decides; the engine's
+    # default is "nothing further", which is the right answer for an app whose
+    # only onboarding ask is the name.
+    def remaining_steps
+      resolver = Studio.onboarding_steps_resolver
+      return [] unless resolver.respond_to?(:call)
+
+      Array(resolver.call(current_user, session)).map(&:to_s)
+    end
+  end
+end

data/app/services/studio/email_preview_target.rb

@@ -211,14 +211,6 @@ module Studio
             name: "Alex McRitchie", email: "alex@#{sample_domain}")
       end
 
-      # Deliberately NAMELESS, and always present. This is the only recipient that
-      # exercises the name-free fallback header — the case a magic link hits every
-      # time it reaches someone with no account yet, and the one nobody thinks to
-      # check because whoever is previewing has a name on file.
-      def sample_member
-        new(id: "sample-member", label: "No name on file", admin: false,
-            name: nil, email: "someone@#{sample_domain}")
-      end
     end
   end
 end

data/app/views/studio/modals/onboarding/_first_name.html.erb

@@ -0,0 +1,138 @@
+<%#
+  First-name capture — the shared onboarding step.
+
+  Asks a freshly signed-in account for a first name, once, and lets them skip.
+  Ported from turf-monster's post-auth onboarding chain (2026-08) because the
+  same beat is wanted in McRitchie Studio: the field exists in every Studio app
+  (`users.first_name`), and the ask is identical everywhere. What is NOT shared —
+  and deliberately stays in the host — is the ORDER of the chain around it: turf
+  walks welcome → first name → age → wallet, which means nothing in a hub app.
+  This partial owns ONE step; the host owns the sequence.
+
+  Locals (all optional, defaults via local_assigns.fetch):
+    submit_path — POST target for the name (default "/onboarding/first_name")
+    skip_path   — POST target for the skip  (default "/onboarding/skip_first_name")
+    heading     — (default "What should we call you?")
+    subtext     — the one-line why (default speaks about emails)
+    placeholder — (default "Alex")
+    max_length  — (default 40; the server stays the real bound)
+    progress    — [current, total] to render the segmented pill, or nil for none
+    modal_store — Alpine store name (default "modals"; the living style guide
+                  mounts its own page-scoped host and passes "dsModals")
+    done_event  — window event dispatched with { next: [...] } when this step is
+                  finished, saved or skipped (default "onboarding-step-done").
+                  The HOST decides what happens next; this partial never knows.
+
+  CONTRACT WITH THE SERVER. Both endpoints answer JSON `{ ok: true, next: [...] }`
+  — `next` being whatever steps the host says remain. A non-ok response must carry
+  `{ error: "…" }`, which is rendered inline. The step reports `next` upward and
+  closes; it never opens another modal itself.
+
+  CRITICAL (Alpine): this partial is cloned from a <template x-if> by the modal
+  host, so it must have ONE root element, and the x-data below is a
+  DOUBLE-QUOTED attribute — a single " anywhere inside it (a code comment
+  included) closes it early and the whole component mounts as a silent no-op that
+  still renders markup. Keep every inner string SINGLE-quoted.
+%>
+<%
+  submit_path = local_assigns.fetch(:submit_path, "/onboarding/first_name")
+  skip_path   = local_assigns.fetch(:skip_path, "/onboarding/skip_first_name")
+  heading     = local_assigns.fetch(:heading, "What should we call you?")
+  subtext     = local_assigns.fetch(:subtext,
+                  "Just your first name — we use it to address you in emails.")
+  placeholder = local_assigns.fetch(:placeholder, "Alex")
+  max_length  = local_assigns.fetch(:max_length, 40)
+  progress    = local_assigns.fetch(:progress, nil)
+  modal_store = local_assigns.fetch(:modal_store, "modals")
+  done_event  = local_assigns.fetch(:done_event, "onboarding-step-done")
+  field_id    = local_assigns.fetch(:id, "onboarding-first-name")
+%>
+<div x-data="{
+       get props() { var c = $store.<%= modal_store %>.current(); return (c && c.props) || {}; },
+       firstName: '',
+       submitting: false,
+       error: '',
+       async save() {
+         if (this.submitting) return;
+         var value = (this.firstName || '').trim();
+         if (!value) { this.error = 'Enter your first name, or skip for now.'; return; }
+         this.submitting = true; this.error = '';
+         var data = await this.post('<%= submit_path %>', { first_name: value });
+         this.submitting = false;
+         if (!data || !data.ok) {
+           this.error = (data && data.error) || 'Could not save that — try again.';
+           return;
+         }
+         this.finish(data.next || []);
+       },
+       async skip() {
+         if (this.submitting) return;
+         this.submitting = true; this.error = '';
+         var data = await this.post('<%= skip_path %>', {});
+         this.submitting = false;
+         this.finish((data && data.next) || []);
+       },
+       async post(url, body) {
+         var meta = document.querySelector('meta[name=csrf-token]');
+         try {
+           var res = await fetch(url, {
+             method: 'POST',
+             headers: {
+               'Content-Type': 'application/json',
+               'Accept': 'application/json',
+               'X-CSRF-Token': meta ? meta.content : ''
+             },
+             body: JSON.stringify(body)
+           });
+           return await res.json();
+         } catch (e) { return null; }
+       },
+       finish(next) {
+         window.dispatchEvent(new CustomEvent('<%= done_event %>', { detail: { next: next } }));
+         $store.<%= modal_store %>.close();
+       }
+     }"
+     class="relative">
+
+  <div class="relative mb-3 -mt-2">
+    <h3 class="text-heading font-bold text-lg leading-tight text-center pt-1"><%= heading %></h3>
+    <%# The × SKIPS rather than merely closing: this lands seconds after signup,
+        and a close that silently abandons the chain is how a host ends up with a
+        step nobody can answer again. %>
+    <button @click="skip()"
+            class="absolute top-0 right-0 -mr-2 text-secondary hover:text-heading text-xl leading-none"
+            aria-label="Skip">&times;</button>
+  </div>
+  <% if progress %>
+    <%= render "studio/modals/blocks/progress_pill", current: progress.first, total: progress.last %>
+  <% end %>
+  <p class="text-xs text-body mb-4 text-center"><%= subtext %></p>
+
+  <form @submit.prevent="save()" novalidate>
+    <div class="mb-3">
+      <label class="block text-xs text-secondary mb-1 font-medium" for="<%= field_id %>">First name</label>
+      <%# Focused on open. The HTML autofocus attribute is not enough for a modal
+          mounted from a <template x-if> after the document parsed, so Alpine does
+          it; preventScroll keeps the mount animation from being yanked. %>
+      <input id="<%= field_id %>" type="text" x-model="firstName"
+             maxlength="<%= max_length %>" autocomplete="given-name" enterkeyhint="done"
+             placeholder="<%= placeholder %>"
+             :disabled="submitting"
+             x-init="$nextTick(() => $el.focus({ preventScroll: true }))"
+             class="input-field">
+    </div>
+    <template x-if="error">
+      <p class="text-red-400 text-xs mb-3" x-text="error"></p>
+    </template>
+    <button type="submit" :disabled="submitting"
+            class="btn btn-primary btn-lg w-full gap-2 disabled:cursor-wait">
+      <span x-show="submitting" class="cta-spinner" aria-hidden="true"></span>
+      <span x-text="submitting ? 'Saving…' : 'Save and continue'"></span>
+    </button>
+  </form>
+
+  <button type="button" @click="skip()" :disabled="submitting"
+          class="mt-3 w-full text-center text-sm text-secondary hover:text-heading disabled:opacity-50">
+    Skip for now
+  </button>
+</div>

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

@@ -309,6 +309,14 @@
           <div><%= render "style/modals/auth" %></div>
         </template>
 
+        <%# --- Onboarding --- %>
+        <%# The REAL engine partial, mounted on the page-scoped host: what the
+            style page shows is exactly what a consumer renders, not a copy. %>
+        <template x-if="$store.dsModals.current().id === 'onboarding-first-name'">
+          <div><%= render "studio/modals/onboarding/first_name",
+                     modal_store: "dsModals", done_event: "ds-onboarding-step-done" %></div>
+        </template>
+
         <%# --- Eligibility + entry --- %>
         <template x-if="$store.dsModals.current().id === 'age-verify'">
           <div><%= render "style/modals/age_verify" %></div>
@@ -463,6 +471,43 @@
   </template>
 
   <%# ===================================================================== %>
+  <%# 0. ONBOARDING — the post-auth chain's shared step %>
+  <%# ===================================================================== %>
+  <section class="space-y-5">
+    <div class="space-y-1">
+      <h3 class="text-xl font-bold text-heading">Onboarding</h3>
+      <p class="text-muted text-sm">
+        The step every Studio app asks a brand-new account, ported from Turf
+        Monster
+        (<code class="font-mono text-2xs">studio/modals/onboarding/_first_name</code>).
+        It is <strong>one step, not a flow</strong>: the host owns the SEQUENCE
+        around it — Turf walks <strong>welcome &rarr; first name &rarr; age gate
+        &rarr; wallet setup</strong>, while a hub app may ask nothing else — so
+        this partial never opens another modal. It reports what remains on its
+        <code class="font-mono text-2xs">done_event</code> and closes, and the host
+        decides what comes next. Every endpoint and label is a local with a
+        default, so mounting it under different routes needs no fork.
+        <strong>Both</strong> the &times; and the "Skip for now" link SKIP (a close
+        that silently abandons the chain is how a host ends up with a step nobody
+        can answer again), and the field focuses itself on open.
+      </p>
+    </div>
+    <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "First name",
+            reference: %(the shared onboarding first-name step (studio-engine studio/modals/onboarding/_first_name) — open with $store.dsModals.open('onboarding-first-name'). Posts to submit_path/skip_path (defaults /onboarding/first_name and /onboarding/skip_first_name) and dispatches its done_event with the steps the SERVER says remain),
+            open_expr: "$store.dsModals.open('onboarding-first-name')",
+            glow_when: ds_glow.call("onboarding-first-name")
+          } do %>
+        <p class="text-muted text-2xs">
+          Saving or skipping dispatches
+          <code class="font-mono">ds-onboarding-step-done</code> here rather than
+          the app-level event, so the specimen cannot drive a real chain.
+        </p>
+      <% end %>
+    </div>
+  </section>
+
   <%# 1. AUTH suite %>
   <%# ===================================================================== %>
   <section class="space-y-5">

data/db/migrate/20260813220000_add_standard_user_profile_columns.rb

@@ -0,0 +1,51 @@
+# The standard Studio user profile columns — the small set every Studio app
+# carries whether or not it uses them today, so an app never has to invent its
+# own spelling for the same fact.
+#
+# THIS IS THE ENGINE'S FIRST MIGRATION AGAINST A HOST TABLE. Every other engine
+# migration creates a `studio_*` table the engine owns outright; `users` belongs
+# to the host. That boundary is crossed deliberately, on the operator's call
+# (2026-08-13), because the alternative is three hand-written migrations in
+# mcritchie-studio, turf-monster and mcritchie-industries that must be kept
+# identical by discipline alone — and column drift across apps is exactly what a
+# standard is supposed to prevent. One definition, one place.
+#
+# Two properties make that safe:
+#
+#   1. EVERY add is `if_not_exists: true`. The apps disagree TODAY — McRitchie
+#      Studio and turf-monster already have `first_name`, and turf already has
+#      `birth_year` (as an integer, matching below). An unguarded add would raise
+#      on those apps, which is the failure mode that makes engine migrations
+#      against host tables frightening in the first place.
+#   2. It no-ops on an app with no `users` table at all, rather than raising.
+#      The engine's own dummy is such an app.
+#
+# Migrations are install-copied (`bin/rails studio_engine:install:migrations`),
+# not auto-run, so each app still adopts this deliberately.
+#
+# ON THE BIRTH COLUMNS: three integers, not one date. Splitting them keeps the
+# two questions apps actually ask cheap and separable — age (needs the year, and
+# the month/day for the boundary case) and "whose birthday is today" (needs
+# month + day, and no year at all). turf-monster's AgePolicy composes a Date from
+# the trio. Storing no single date-of-birth column is the point.
+#
+# ON ip_locations: a jsonb ARRAY of the distinct places an account has signed in
+# from, appended to when a NEW location appears. Shape, dedupe and the growth cap
+# belong to Studio::IpLocations — the column is just where it lands. It holds
+# IP-derived location data, which is personal data in most jurisdictions; the
+# 50-entry cap there bounds it, and no app writes to it until it opts in.
+class AddStandardUserProfileColumns < ActiveRecord::Migration[7.2]
+  def change
+    # An app that has no users table (the engine's dummy, and any future
+    # consumer that names its accounts something else) is simply skipped.
+    return unless table_exists?(:users)
+
+    add_column :users, :first_name, :string, if_not_exists: true
+
+    add_column :users, :birth_day,   :integer, if_not_exists: true
+    add_column :users, :birth_month, :integer, if_not_exists: true
+    add_column :users, :birth_year,  :integer, if_not_exists: true
+
+    add_column :users, :ip_locations, :jsonb, default: [], null: false, if_not_exists: true
+  end
+end

data/lib/studio/ip_locations.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Studio
+  # The shape, dedupe rule and growth cap for `users.ip_locations` — the jsonb
+  # array recording the distinct places an account has been seen from.
+  #
+  # Deliberately PURE: it takes the existing array and returns a new one. No
+  # ActiveRecord, no clock beyond what the caller passes, no geo lookup. That
+  # keeps the analytics shape identical in every app while leaving the RESOLUTION
+  # to the host — turf-monster already resolves IP → state/country through
+  # Geocoder in ApplicationController#detect_geo_state and can hand the result
+  # straight here; an app with no geo lookup at all still gets a useful record of
+  # the distinct IPs.
+  #
+  # An entry:
+  #
+  #   { "ip" => "203.0.113.7", "country" => "US", "region" => "TX",
+  #     "city" => "Austin", "first_seen_at" => "2026-08-13T21:00:00Z",
+  #     "last_seen_at" => "2026-08-14T09:30:00Z", "count" => 4 }
+  #
+  # String keys throughout, ISO-8601 times: this round-trips through jsonb, and a
+  # symbol-keyed hash written today would come back string-keyed tomorrow.
+  module IpLocations
+    # Distinct locations kept per user, most-recently-seen first. A cap is not
+    # optional for a column that grows on sign-in: an account that travels, or
+    # sits behind a rotating consumer IP, would otherwise grow this row without
+    # bound and drag every SELECT that loads the user along with it.
+    MAX_ENTRIES = 50
+
+    # Loopback and private ranges. A dev session signs in from 127.0.0.1 all day
+    # and a container from 10.x; recording those buys nothing and would crowd the
+    # real entries out of the cap.
+    SKIPPED_IP = /\A(127\.|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|169\.254\.|::1\z|fe80:|f[cd])/i
+
+    module_function
+
+    # Returns the array to store. Appends a new entry when this location has not
+    # been seen before; otherwise refreshes the existing one in place.
+    def push(entries, ip:, country: nil, region: nil, city: nil, at: nil)
+      at  = normalize_time(at)
+      ip  = ip.to_s.strip
+      key = location_key(ip: ip, country: country, region: region, city: city)
+      return normalize(entries) if key.nil?
+
+      existing = normalize(entries)
+      match    = existing.find { |e| e["key"] == key }
+
+      if match
+        match["last_seen_at"] = at
+        match["count"]        = match["count"].to_i + 1
+        # The IP within a location legitimately changes (a reassigned lease); the
+        # LOCATION is what we deduped on, so keep the freshest address for it.
+        match["ip"] = ip if ip.present?
+      else
+        existing << {
+          "key" => key, "ip" => ip.presence, "country" => presence(country),
+          "region" => presence(region), "city" => presence(city),
+          "first_seen_at" => at, "last_seen_at" => at, "count" => 1
+        }
+      end
+
+      existing.sort_by { |e| e["last_seen_at"].to_s }.reverse.first(MAX_ENTRIES)
+    end
+
+    # Has this account been seen here before? The question a caller asks to avoid
+    # a write on every single request.
+    def seen?(entries, ip: nil, country: nil, region: nil, city: nil)
+      key = location_key(ip: ip.to_s.strip, country: country, region: region, city: city)
+      return false if key.nil?
+
+      normalize(entries).any? { |e| e["key"] == key }
+    end
+
+    # What the location is, for deduping. Geo when we have any of it — two
+    # sign-ins from Austin are ONE location even from different addresses, which
+    # is the whole point of tracking places rather than addresses. Falls back to
+    # the IP when the lookup gave us nothing, so an app with no geo still records
+    # something useful. nil (record nothing) when there is neither.
+    def location_key(ip:, country: nil, region: nil, city: nil)
+      geo = [country, region, city].map { |v| presence(v) }
+      return "geo:" + geo.map(&:to_s).join("|").downcase if geo.any?
+      return nil if ip.blank? || ip.match?(SKIPPED_IP)
+
+      "ip:#{ip.downcase}"
+    end
+
+    def normalize(entries)
+      Array(entries).filter_map do |entry|
+        next unless entry.respond_to?(:to_h)
+
+        row = entry.to_h.transform_keys(&:to_s)
+        next if row.empty?
+
+        # Backfill for rows written before these fields existed, so an upgrade in
+        # place neither duplicates locations it already holds nor treats them as
+        # the stalest thing in the column.
+        row["key"] ||= location_key(ip: row["ip"].to_s, country: row["country"],
+                                    region: row["region"], city: row["city"])
+        # A stored row is evidence of at least one sighting.
+        row["count"] = 1 if row["count"].to_i < 1
+        row["last_seen_at"] ||= row["first_seen_at"]
+        row
+      end
+    end
+
+    def normalize_time(value)
+      return value if value.is_a?(String) && value.present?
+      return Time.now.utc.iso8601 if value.nil?
+
+      value.respond_to?(:utc) ? value.utc.iso8601 : value.to_s
+    end
+
+    def presence(value)
+      str = value.to_s.strip
+      str.empty? ? nil : str
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.45.0"
+  VERSION = "0.46.0"
 end

data/lib/studio.rb

@@ -1,5 +1,6 @@
 require "studio/version"
 require "studio/log_rotation"
+require "studio/ip_locations"
 require "studio/engine"
 require "studio/color_scale"
 require "studio/environment_banner"
@@ -141,6 +142,90 @@ module Studio
   # resolution are always on, so an app sends branded email either way.
   mattr_accessor :draw_admin_emails_routes, default: false
 
+  # Draw the shared first-name onboarding endpoints
+  # (Studio::OnboardingController#first_name / #skip_first_name). OFF by default,
+  # and for the same hard reason as draw_admin_emails_routes above:
+  # turf-monster ALREADY owns `post "/onboarding/first_name"` with the helper
+  # names onboarding_first_name_path and onboarding_skip_first_name_path, so
+  # drawing these unconditionally raises `Invalid route name, already in use`
+  # while that app's routes.rb loads — which takes down its ENTIRE route set, not
+  # just this page. Consumer CI runs each consumer's main, so a default-on flag
+  # cannot be fixed from inside the engine. Each app's adoption task turns it on
+  # as it deletes its local copy:
+  #
+  #   config.draw_onboarding_routes = true
+  #
+  # Gates only the ENDPOINTS. The modal partial
+  # (studio/modals/onboarding/_first_name) and its /admin/style specimen are
+  # always available, so a host can preview the step before it wires the writes.
+  mattr_accessor :draw_onboarding_routes, default: false
+
+  # What the onboarding endpoints report back as still-remaining after a write,
+  # so the client can keep walking its chain without a second round trip.
+  #
+  # The engine owns ONE STEP (the first-name ask); the HOST owns the SEQUENCE
+  # around it. turf-monster walks welcome → first name → age → wallet, which
+  # means nothing in a hub app, so this resolver is how a host says what comes
+  # next. It takes (user, session) and returns an array of step names; the
+  # default — no further steps — is correct for an app whose only ask is the name.
+  #
+  #   config.onboarding_steps_resolver = ->(user, session) {
+  #     OnboardingFlow.new(user, session).remaining.map(&:to_s)
+  #   }
+  mattr_accessor :onboarding_steps_resolver, default: ->(_user, _session) { [] }
+
+  # Session key recording "asked, and they said not now". Session-scoped
+  # DELIBERATELY: skipping means not now, not never — the field stays blank, so a
+  # later session may ask again. That is the whole reason this is not a column.
+  FIRST_NAME_SKIP_SESSION_KEY = :onboarding_skipped_first_name
+
+  # The shared rule for "does this account still owe us a first name?" — the one
+  # piece of onboarding logic every app agrees on. Hosts compose it into their own
+  # flow rather than re-deriving it (turf's OnboardingFlow calls straight through).
+  #
+  # Tolerates a host whose users table has no first_name column: an app that has
+  # not run the migration yet is simply never asked, instead of raising on every
+  # signed-in request.
+  def self.first_name_outstanding?(user, session = {})
+    return false if user.blank?
+    return false unless user.respond_to?(:first_name)
+    return false if session.present? && session[FIRST_NAME_SKIP_SESSION_KEY]
+
+    user.first_name.blank?
+  end
+
+  # Record a place this account has been seen from, if it is a place we have not
+  # seen it from before. Returns true when something was actually written.
+  #
+  # NEW LOCATIONS ONLY, and that is the design rather than a shortcut: this is
+  # called from the request path, so refreshing a counter on every hit would mean
+  # a database write per request for no analytic gain. The first sign-in from a
+  # place writes; the next thousand do not. A host wanting last-seen/count
+  # refresh can call Studio::IpLocations.push directly on its own cadence.
+  #
+  # The host resolves the location — turf-monster already has Geocoder wired in
+  # ApplicationController#detect_geo_state — and passes whatever it got. Pass
+  # only an IP and the IP is what gets deduped on.
+  #
+  # Tolerates an app that has not run the migration (no ip_locations column):
+  # it records nothing rather than raising on a request path.
+  def self.record_ip_location!(user, ip:, country: nil, region: nil, city: nil, at: nil)
+    return false if user.blank?
+    return false unless user.respond_to?(:ip_locations)
+
+    current = user.ip_locations
+    return false if IpLocations.seen?(current, ip: ip, country: country, region: region, city: city)
+
+    updated = IpLocations.push(current, ip: ip, country: country, region: region,
+                                        city: city, at: at)
+    return false if updated == IpLocations.normalize(current)
+
+    # update_columns, not update!: analytics must never block a request, and a
+    # validation failure elsewhere on the record is not this write's business.
+    user.update_columns(ip_locations: updated)
+    true
+  end
+
   # Optional admin Act As / impersonation session conventions. Consumers that
   # include Studio::Impersonation get current_user layered over true_user with
   # these session keys, but still own authorization, audit logging, and routes.
@@ -584,6 +669,20 @@ module Studio
                as: :admin_email_logo, constraints: { key: /[a-z0-9_]+/ }
       end
 
+      # The shared first-name onboarding step's two writes. OPT-IN — see
+      # Studio.draw_onboarding_routes above: turf-monster owns these exact helper
+      # names today, and drawing them there before its adoption task deletes the
+      # local pair kills every route in that app.
+      #
+      # The paths match the partial's defaults, so a host that opts in and has no
+      # other onboarding of its own needs no further wiring.
+      if Studio.draw_onboarding_routes
+        post "onboarding/first_name",      to: "studio/onboarding#first_name",
+             as: :onboarding_first_name
+        post "onboarding/skip_first_name", to: "studio/onboarding#skip_first_name",
+             as: :onboarding_skip_first_name
+      end
+
       # DEPRECATED, kept for ONE release. Not a redirect: consumer-ci.yml runs
       # each consumer's DEFAULT-BRANCH suite against this engine, and both
       # mcritchie-studio and turf-monster have tests on `main` that GET this page

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.45.0
+  version: 0.46.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -203,6 +203,7 @@ files:
 - app/controllers/studio/local_emails_controller.rb
 - app/controllers/studio/local_reviews_controller.rb
 - app/controllers/studio/models_controller.rb
+- app/controllers/studio/onboarding_controller.rb
 - app/controllers/style_controller.rb
 - app/controllers/theme_settings_controller.rb
 - app/helpers/studio/admin_models_table_helper.rb
@@ -321,6 +322,7 @@ files:
 - app/views/studio/modals/blocks/_solana_tx_link.html.erb
 - app/views/studio/modals/blocks/_success_card.html.erb
 - app/views/studio/modals/blocks/_wallet_brand_sprite.html.erb
+- app/views/studio/modals/onboarding/_first_name.html.erb
 - app/views/studio/modals/shared/_age_attestation.html.erb
 - app/views/studio/modals/shared/_email_field.html.erb
 - app/views/studio/modals/templates/_action.html.erb
@@ -356,6 +358,7 @@ files:
 - db/migrate/20260812210000_add_copy_to_studio_email_settings.rb
 - db/migrate/20260812220000_add_subject_to_studio_email_settings.rb
 - db/migrate/20260813010000_add_body_cta_footer_to_studio_email_settings.rb
+- db/migrate/20260813220000_add_standard_user_profile_columns.rb
 - lib/studio-engine.rb
 - lib/studio.rb
 - lib/studio/cable.rb
@@ -365,6 +368,7 @@ files:
 - lib/studio/engine.rb
 - lib/studio/environment_banner.rb
 - lib/studio/image_cache.rb
+- lib/studio/ip_locations.rb
 - lib/studio/link_resolution.rb
 - lib/studio/link_token.rb
 - lib/studio/log_rotation.rb