studio-engine 0.74.11 → 0.75.0

data/app/controllers/concerns/studio/session_drift.rb

@@ -0,0 +1,99 @@
+module Studio
+  # The server half of the session-drift primitive (docs/SESSION_DRIFT.md).
+  #
+  # Every page carries a STAMP: the session's state, its fingerprint, when it was
+  # issued and when it lapses, where to rehydrate it, and the identities the host
+  # has bound it to. The browser store (app/assets/javascripts/studio/session.js)
+  # reads the stamp, watches for drift, and rehydrates through
+  # Studio::SessionStatesController when the host draws that route.
+  #
+  # Included BY Studio::ErrorHandling, so every consumer that includes that
+  # concern has the stamp on every page with no wiring of its own. It adds
+  # helper methods only; it registers no filter and changes no response.
+  #
+  # THE HOST'S TWO HOOKS
+  #
+  #   studio_session_identities — { source name => bound identity }. Baseline {}.
+  #     A host that binds its session to an identity the engine knows nothing
+  #     about (an external account, a device) overrides this, and a browser
+  #     identity source registered under the same name observes it. The engine
+  #     compares the two strings and never interprets them.
+  #
+  #   client_session_payload (Studio::ErrorHandling) — the host's own page payload.
+  #     The rehydrate endpoint returns it as `context` beside the stamp, so a host
+  #     store hydrated from it can be refreshed from the same response.
+  module SessionDrift
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :studio_session_state, :studio_session_stamp, :studio_session_page_stamp,
+                    :studio_session_identities, :studio_session_rehydrate_url
+    end
+
+    private
+
+    # The request's Studio::SessionState, built from the viewer alone: the state
+    # and the fingerprint depend on nothing else.
+    def studio_session_state
+      @studio_session_state ||= Studio::SessionState.new(current_user)
+    end
+
+    # The stamp for this request. Raises like any other controller code; the
+    # rehydrate endpoint relies on that so a failure reaches the error handler.
+    def studio_session_stamp
+      studio_session_state.to_stamp(
+        rehydrate_url: studio_session_rehydrate_url,
+        expires_at:    studio_session_expires_at,
+        identities:    studio_session_identities
+      )
+    end
+
+    # The stamp as the PAGE renders it. A page must never fail because its
+    # session decoration did, so in production a failure is logged to ErrorLog
+    # and the page renders without a stamp — the browser store then stays
+    # dormant, which is exactly how every page behaved before this existed.
+    # Development and test re-raise, mirroring handle_unexpected_error, so a
+    # broken stamp fails a consumer's suite instead of hiding in it.
+    def studio_session_page_stamp
+      studio_session_stamp
+    rescue StandardError => e
+      raise if defined?(::Rails) && ::Rails.respond_to?(:env) && (::Rails.env.development? || ::Rails.env.test?)
+
+      begin
+        ErrorLog.capture!(e)
+      rescue StandardError
+        nil
+      end
+      nil
+    end
+
+    # Host hook — see the module comment. Baseline: no bound identities.
+    def studio_session_identities
+      {}
+    end
+
+    # Where the browser store rehydrates, or nil when the host has not drawn the
+    # route (Studio.draw_session_routes). Without it the store still detects
+    # drift; it just cannot repair the page in place.
+    def studio_session_rehydrate_url
+      return nil unless Studio.draw_session_routes
+      return nil unless respond_to?(:studio_session_state_path, true)
+
+      studio_session_state_path
+    end
+
+    # When this session lapses, if the session store says. Rails' cookie store
+    # re-issues the cookie on every response, so a session with `expire_after`
+    # lapses that long after THIS response — which is what the stamp records.
+    # nil (the Rails default: a browser-session cookie) means no expiry source.
+    def studio_session_expires_at
+      return nil unless request.respond_to?(:session_options)
+
+      expire_after = request.session_options[:expire_after]
+      return nil unless expire_after.is_a?(Numeric) || expire_after.is_a?(ActiveSupport::Duration)
+      return nil unless expire_after.to_i.positive?
+
+      Time.now + expire_after.to_i
+    end
+  end
+end

data/app/controllers/studio/session_states_controller.rb

@@ -0,0 +1,43 @@
+module Studio
+  # GET /session/state — the rehydrate endpoint of the session-drift primitive
+  # (docs/SESSION_DRIFT.md). Drawn only when the host sets
+  # Studio.draw_session_routes; the browser store learns the URL from the page
+  # stamp and never guesses it.
+  #
+  # It answers "what is this browser's session NOW?" with three things:
+  #
+  #   session — the same stamp a page render carries (Studio::SessionDrift), so
+  #             the store compares like with like;
+  #   context — the host's client_session_payload, so a host store hydrated from
+  #             that payload refreshes from the same response;
+  #   csrf    — a fresh authenticity token. Signing in or out resets the Rails
+  #             session, which invalidates every token a stale page holds; the
+  #             store swaps it into the csrf-token meta. That repairs requests
+  #             that read the meta (Turbo, fetch with X-CSRF-Token). It does NOT
+  #             rewrite the hidden authenticity_token input of a form already on
+  #             the page, so a data-turbo="false" form rendered before the reset
+  #             still posts the old token.
+  #
+  # ANONYMOUS IS AN ANSWER, NOT A FAILURE. The action skips the host's
+  # require_authentication: a signed-out browser gets a 200 describing an
+  # anonymous session. A host filter that REVOKES a session (verify_session_token
+  # answers JSON with a 401) is still honoured, and the store reads that 401 as a
+  # revocation.
+  #
+  # Read-only: no writes, and Cache-Control: no-store so no proxy or browser cache
+  # ever answers for a different session.
+  class SessionStatesController < ::ApplicationController
+    skip_before_action :require_authentication, raise: false
+
+    def show
+      rescue_and_log(target: current_user) do
+        response.headers["Cache-Control"] = "no-store"
+        render json: {
+          session: studio_session_stamp,
+          context: respond_to?(:client_session_payload, true) ? client_session_payload : nil,
+          csrf:    form_authenticity_token
+        }
+      end
+    end
+  end
+end

data/app/models/session_context.rb

@@ -23,6 +23,38 @@ class SessionContext
 
   attr_reader :user
 
+  # ---- Session state (docs/SESSION_DRIFT.md) --------------------------------
+  # The generic session-state primitive, delegated to Studio::SessionState, which
+  # reads the viewer and nothing else. This block only exposes it here; the
+  # legacy payload below (#to_h) is unchanged and carries none of it.
+  STATES        = Studio::SessionState::STATES
+  SERVER_STATES = Studio::SessionState::SERVER_STATES
+
+  def session_state
+    @session_state ||= Studio::SessionState.new(user)
+  end
+
+  def state
+    session_state.state
+  end
+
+  def anonymous?
+    session_state.anonymous?
+  end
+
+  def authenticated?
+    session_state.authenticated?
+  end
+
+  def fingerprint(identities = {})
+    session_state.fingerprint(identities)
+  end
+
+  def to_stamp(**options)
+    session_state.to_stamp(**options)
+  end
+  # ---- end session state ----------------------------------------------------
+
   def initialize(user:, onchain_session:)
     @user = user
     @onchain_session = onchain_session

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

@@ -54,8 +54,10 @@
   .toast-blur-glow {
     background: rgba(0, 0, 0, 0.06);
   }
+  /* Slash form only: the theme's -rgb vars are space lists, so the legacy
+     comma form is invalid and painted no halo (legacy_rgba_var_guard_test.rb). */
   .dark .toast-blur-glow {
-    background: rgba(var(--color-primary-500-rgb), 0.12);
+    background: rgb(var(--color-primary-500-rgb) / 0.12);
   }
   .toast-wrapper {
     position: relative;

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

@@ -10,6 +10,9 @@
 <meta name="apple-mobile-web-app-capable" content="yes">
 <%= csrf_meta_tags %>
 <%= csp_meta_tag %>
+<%# The session-drift stamp + browser store. Renders nothing unless the controller
+    includes Studio::ErrorHandling. See studio/_session_stamp. %>
+<%= render "studio/session_stamp" %>
 <%= render "layouts/studio/smooth_load" %>
 <link rel="icon" type="image/png" href="/favicon.png">
 

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

@@ -0,0 +1,32 @@
+<%# The session-drift stamp (docs/SESSION_DRIFT.md), rendered by
+    layouts/studio/_head on every page.
+
+    It emits two things: a meta tag named studio-session carrying the stamp as
+    JSON, and the browser store that reads it (studio/session.js, which publishes
+    window.StudioSession). The store is NOT deferred: it has to register its
+    alpine:init listener before the deferred Alpine script runs.
+
+    A META TAG, NOT A JSON SCRIPT TAG, AND THAT IS LOAD-BEARING. Turbo merges the
+    head on every navigation. Script elements are copied in and never removed, so
+    a JSON script tag would pile up one copy per visit and the first copy, the
+    stale one, is the one a lookup by selector returns. Meta tags are replaced, so
+    the head always holds exactly the stamp of the page on screen.
+
+    GUARDED ON THE HELPER. studio_session_page_stamp comes from
+    Studio::SessionDrift, which Studio::ErrorHandling includes. A head rendered
+    anywhere else (the e2e lab, a bare view in a unit test, a host controller that
+    does not include the concern) emits nothing here, byte-identical to the head
+    before this partial existed.
+
+    THE SCRIPT DOES NOT DEPEND ON THE STAMP. A nil stamp (a production failure,
+    logged to ErrorLog) omits the meta tag and still loads the store, which then
+    stays dormant. The script is Turbo-tracked like every engine asset, and Turbo
+    fully reloads when two pages' tracked scripts differ, so a page whose stamp
+    failed must not also drop the script and turn the next click into a reload. %>
+<% if respond_to?(:studio_session_page_stamp) %>
+<% studio_session_stamp_value = studio_session_page_stamp %>
+<% if studio_session_stamp_value %>
+<%= tag.meta(name: "studio-session", content: studio_session_stamp_value.to_json) %>
+<% end %>
+<%= javascript_include_tag "studio/session", "data-turbo-track": "reload" %>
+<% end %>

data/app/views/studio/modals/_host.html.erb

@@ -838,8 +838,13 @@
          :class="$store.modals.cardClasses()">
       <%# Consumer-provided content registrations. Each block typically
           contains a <template x-if="$store.modals.current().id === 'X'">
-          render "modals/X" </template>. %>
-      <%= yield if block_given? %>
+          render "modals/X" </template>.
+          NOT `yield if block_given?`. In a partial block_given? is always true,
+          and a caller-less yield returns the layout's content, so a host
+          rendered from a layout with no block (an app whose modals all live in
+          _host_extras) put the whole page body inside the card. See
+          Studio::PartialBlock. %>
+      <%= Studio::PartialBlock.content(self, yield) %>
 
       <%# APP-WIDE modal registrations — the second seam. The block above is
           per-CALLSITE: an app rendering this host from two layouts (a live one

data/app/views/studio/modals/_scoped_host.html.erb

@@ -364,8 +364,11 @@
        @keydown.escape.window="$store.<%= scoped_store %>.current() && $store.<%= scoped_store %>.current().props.dismissible !== false && $store.<%= scoped_store %>.close()"
        @click.self="$store.<%= scoped_store %>.current() && $store.<%= scoped_store %>.current().props.dismissible !== false && $store.<%= scoped_store %>.close()">
     <div class="<%= card_class %> max-h-[85dvh] overflow-y-auto" :class="$store.<%= scoped_store %>.cardClasses()">
-      <%# Consumer-provided registrations — one <template x-if> per modal id. %>
-      <%= yield if block_given? %>
+      <%# Consumer-provided registrations — one <template x-if> per modal id.
+          Not `yield if block_given?`: a partial's block_given? is always true,
+          and a caller-less yield returns the layout's whole page body. See
+          Studio::PartialBlock. %>
+      <%= Studio::PartialBlock.content(self, yield) %>
     </div>
   </div>
 </template>

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

@@ -21,10 +21,16 @@
                     for processing / loading states.
     size:           :md (default) OR :lg (celebration end-state, text-3xl title).
 
-  Block: if given, the block's content replaces the subtitle area. Explicit
-  subtitle locals are checked BEFORE block_given? — a partial's block_given? can
-  read TRUE off the layout yield even with no block passed (see the engine's
-  Rails-partial block_given? note), so lead with the locals.
+  Block: if given, the block's content replaces the subtitle area. The subtitle
+  locals outrank it.
+
+  NEVER TEST THE BLOCK WITH block_given?. In a Rails partial it is always true,
+  and a yield with no caller block returns the LAYOUT's content. This branch
+  used to read `elsif block_given?`, so a header rendered from the layout with
+  no subtitle yielded the whole page body into the modal: every signed-in
+  turf-monster page for a user allowed to rename carried two copies of itself
+  (modal-header-yields-whole-page, 2026-09-16). Studio::PartialBlock
+  (lib/studio/partial_block.rb) tells a real block from that fallback.
 %>
 <%
   icon_color = local_assigns[:icon_color] || 'primary'
@@ -77,7 +83,7 @@
     <p class="<%= sub_cls %>" x-text="<%= subtitle_key %>"></p>
   <% elsif local_assigns[:subtitle] %>
     <p class="<%= sub_cls %>"><%= subtitle %></p>
-  <% elsif block_given? %>
-    <p class="<%= sub_cls %>"><%= yield %></p>
+  <% elsif (caller_block = Studio::PartialBlock.content(self, yield)) %>
+    <p class="<%= sub_cls %>"><%= caller_block %></p>
   <% end %>
 </div>

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

@@ -73,6 +73,11 @@
   large_title   = !!local_assigns[:large_title]
   use_drain     = has_redirect && !!local_assigns[:cta_drain]
   slot_position = local_assigns.fetch(:slot_position, :below_cta).to_sym
+  # The caller's block, captured ONCE, or nil when there is none. Never
+  # block_given?: in a partial it is always true, and a caller-less yield
+  # returns the layout's content, so a card rendered from a layout with no
+  # block re-emitted the whole page body under its CTA. See Studio::PartialBlock.
+  caller_block  = Studio::PartialBlock.content(self, yield)
 
   data_attr = "{
     _remaining: #{redirect_secs},
@@ -179,7 +184,7 @@
         <a :href="'https://explorer.solana.com/tx/' + (<%= tx_signature_key %>) + (typeof clusterParam !== 'undefined' ? clusterParam : '')"
            target="_blank" rel="noopener"
            class="inline-flex items-center gap-2 px-3 py-1.5 rounded-lg border border-subtle hover:border-primary/50 transition group"
-           style="background: rgba(var(--color-primary-500-rgb), 0.06);">
+           style="background: rgb(var(--color-primary-500-rgb) / 0.06);">
           <svg width="14" height="11" viewBox="0 0 397 311" fill="none">
             <defs>
               <linearGradient id="studio-solana-grad" x1="361" y1="-9" x2="153" y2="389" gradientUnits="userSpaceOnUse">
@@ -231,8 +236,8 @@
       card has always run its kickoff timer and seeds bar above the button for
       that reason, and this is what lets the engine's card do the same instead of
       the app forking one to keep the order. %>
-  <% if block_given? && slot_position == :above_cta %>
-    <div class="mb-4"><%= yield %></div>
+  <% if caller_block && slot_position == :above_cta %>
+    <div class="mb-4"><%= caller_block %></div>
   <% end %>
 
   <%# Primary CTA — three flavors:
@@ -288,9 +293,9 @@
   <% end %>
 
   <%# ...or below it, which stays the DEFAULT: every existing caller renders here
-      and none of them asked to move. A partial can only yield once, so exactly
-      one of these two branches runs. %>
-  <% if block_given? && slot_position != :above_cta %>
-    <div class="mt-3"><%= yield %></div>
+      and none of them asked to move. The block is captured once at the top, and
+      exactly one of these two branches renders it. %>
+  <% if caller_block && slot_position != :above_cta %>
+    <div class="mt-3"><%= caller_block %></div>
   <% end %>
 </div>

data/lib/studio/engine.rb

@@ -47,6 +47,7 @@ module Studio
         studio/canvas_confetti.js
         studio/studio_confetti.js
         studio/sortable.js
+        studio/session.js
         studio/montserrat-latin.woff2
         studio/montserrat-latin-ext.woff2
       ]

data/lib/studio/partial_block.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Studio
+  # The content of the block a CALLER passed to a partial, or nil when it passed
+  # none. The engine's slot-taking partials ask this, never `block_given?`.
+  #
+  # WHY block_given? IS THE WRONG QUESTION IN A PARTIAL. ActionView compiles a
+  # template into a method and ALWAYS invokes that method with a block:
+  # PartialRenderer passes `{ |*name| view._layout_for(*name, &block) }` whether
+  # or not the render that reached the partial carried one. So `block_given?` is
+  # true in every partial. A `yield` with no caller block then falls through to
+  # `_layout_for`'s other branch, the LAYOUT's content. While the page's own
+  # template renders, that is empty. Once the layout renders, it is THE WHOLE
+  # PAGE BODY.
+  #
+  # MEASURED 2026-09-16 (modal-header-yields-whole-page). turf-monster renders
+  # the modal host from its layout. The username modal's plain "Saved" card
+  # reached blocks/_card_header with a nil subtitle, and the header's
+  # `elsif block_given?` yielded the entire page a second time inside a
+  # <template>: two copies of the page body on /, /contests and /account for
+  # every signed-in user allowed to rename. Nothing painted, nothing raised, and
+  # every request returned 200.
+  #
+  # HOW THIS ANSWERS IT. Rails gives a template no way to ask whether its caller
+  # passed a block, so the partial yields and hands the result in:
+  #
+  #   caller_block = Studio::PartialBlock.content(self, yield)
+  #
+  # A caller-less yield can only return the layout's content or nothing, so a
+  # yield equal to `content_for(:layout)` is that fallback, not a block. A blank
+  # yield also reads as no block: an empty slot wrapper is never what a caller
+  # meant.
+  #
+  # THIS FIXES THE PREDICATE; THE BLOCK CONTRACT IS UNCHANGED. A caller that
+  # passes a non-blank block renders exactly as before, so no consumer edits a
+  # call site. A NEW slot should still prefer a named local that names a partial
+  # (solana-studio's wallet picker does), which needs no predicate at all.
+  module PartialBlock
+    module_function
+
+    # view    — the partial's view context (`self` inside the template).
+    # yielded — the partial's own `yield`, evaluated where the partial calls this.
+    def content(view, yielded)
+      return nil if yielded.blank?
+      return nil if yielded == view.content_for(:layout)
+
+      yielded
+    end
+  end
+end

data/lib/studio/session_fingerprint.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Studio
+  # The session fingerprint: a short, opaque answer to "which signed-in session
+  # rendered this page?" It is stamped on every page (Studio::SessionState#to_stamp)
+  # and returned by the rehydrate endpoint, so two tabs, or one tab before and
+  # after it went to the background, can tell whether they still describe the
+  # same session WITHOUT exposing anything that identifies it.
+  #
+  # WHAT FEEDS IT, and why each part is there:
+  #
+  #   * the user's id — a different account is a different session;
+  #   * the user's session_token, when the host has that column
+  #     (docs/USER_CONTRACT.md). Studio::ErrorHandling binds it into the cookie
+  #     and a host rotates it to log a user out everywhere, so a rotation changes
+  #     the fingerprint and a page rendered before it can see it was revoked;
+  #   * the identities the host has bound the session to (Studio::SessionState#to_stamp's
+  #     `identities:`). A host can re-bind a session to a different identity
+  #     without the account or its token changing. Folding the bindings in means
+  #     that re-bind changes the fingerprint too, so every other tab learns about
+  #     it the same way it learns about a sign-out.
+  #
+  # All of it is keyed through an HMAC, so the fingerprint never carries the token
+  # (a bearer secret bound into the cookie) or the id in a readable form, and it
+  # cannot be recomputed by anyone without the app's secret.
+  #
+  # "anonymous" is deliberately a plain constant, not a digest. There is no
+  # identity to protect, and every signed-out tab SHOULD agree with every other
+  # signed-out tab: anonymous is a first-class state, not a missing value.
+  #
+  # Pure Ruby (no ActiveRecord), so it unit-tests without a database.
+  module SessionFingerprint
+    ANONYMOUS = "anonymous"
+
+    # 32 hex characters = 128 bits of the HMAC: two sessions never collide by
+    # accident, and it is still short enough to read in a log line.
+    LENGTH = 32
+
+    # The key_generator purpose. Changing it changes every fingerprint in the
+    # fleet at once, which reads to every open tab as "your session changed".
+    KEY_PURPOSE = "studio/session-fingerprint"
+
+    class MissingSecret < StandardError; end
+
+    module_function
+
+    # The fingerprint for a user (or nil) and the identities bound to the
+    # session. `secret:` exists for unit tests; everything else resolves it.
+    def for(user, identities: {}, secret: nil)
+      bindings = bindings(identities)
+      return ANONYMOUS if user.nil? && bindings.empty?
+
+      digest(material(user, bindings), secret: secret || resolve_secret)
+    end
+
+    def digest(material, secret:)
+      raise MissingSecret, "a session fingerprint needs a secret" if secret.nil? || secret.to_s.empty?
+
+      OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, material.to_s)[0, LENGTH]
+    end
+
+    # JSON, not a joined string: a host's identity names and values are
+    # arbitrary text, and no separator is safe against arbitrary text. A host
+    # with no session_token column still gets a per-account fingerprint; it simply
+    # cannot express "revoked" through it.
+    #
+    # Every part is a String (or nil) before it is encoded. Handing JSON an
+    # arbitrary object would route it through ActiveSupport's as_json, which walks
+    # instance variables — a test double or a decorated user could recurse there.
+    def material(user, bindings = [])
+      id = user.respond_to?(:id) ? user.id : user
+      token = user.respond_to?(:session_token) ? user.session_token : nil
+      JSON.generate(["studio-session", id&.to_s, token&.to_s, bindings])
+    end
+
+    # Sorted pairs, so the same bindings produce the same fingerprint whatever
+    # order the host built its hash in. A blank value is not a binding.
+    def bindings(identities)
+      (identities || {})
+        .map { |name, value| [name.to_s, value.to_s] }
+        .reject { |_, value| value.empty? }
+        .sort
+    end
+
+    # The explicit Studio.session_fingerprint_secret, else a key derived from the
+    # host app's secret_key_base. Every process of one app derives the SAME key,
+    # which is the property that matters: a fingerprint that differed per dyno
+    # would report drift on every request that landed on another one.
+    #
+    # `::Rails.respond_to?(:application)`, not `defined?(Rails)`: a gem can define
+    # a bare Rails namespace without an application behind it.
+    def resolve_secret
+      explicit = Studio.respond_to?(:session_fingerprint_secret) ? Studio.session_fingerprint_secret : nil
+      return explicit unless explicit.nil? || explicit.to_s.empty?
+
+      if defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application &&
+         ::Rails.application.respond_to?(:key_generator)
+        return ::Rails.application.key_generator.generate_key(KEY_PURPOSE, 32)
+      end
+
+      raise MissingSecret,
+            "Studio::SessionFingerprint has no secret: set Studio.session_fingerprint_secret, " \
+            "or boot inside a Rails application (it derives one from secret_key_base)."
+    end
+  end
+end

data/lib/studio/session_state.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Studio
+  # The session's state, as a page is stamped with it (docs/SESSION_DRIFT.md).
+  #
+  # It answers one question: which session rendered this page, and is anyone
+  # signed in? `state` is :anonymous or :authenticated, `fingerprint`
+  # (Studio::SessionFingerprint) names the session without exposing it, and
+  # `to_stamp` is the JSON every page carries so the browser store
+  # (app/assets/javascripts/studio/session.js) can notice when the session
+  # changes underneath a page.
+  #
+  # It reads the viewer and nothing else. What an identity IS stays outside: a
+  # host that binds the session to something beyond the account passes it in as
+  # `identities:`, keyed by the name of the browser identity source that observes
+  # it, and this class only ever compares strings.
+  #
+  # Built per request by Studio::SessionDrift#studio_session_state, and exposed on
+  # SessionContext through delegators. Pure Ruby, so it unit-tests without Rails.
+  class SessionState
+    # The session lifecycle, in the order a page can move through it:
+    #   anonymous      — nobody is signed in. A first-class state, not an error:
+    #                    a pre-auth page is a real page with a real session.
+    #   authenticated  — somebody is signed in and the page still describes them.
+    #   stale          — the page learned its stamp is out of date (another tab
+    #                    changed the session, it expired, the server probe
+    #                    disagreed) and a rehydrate is due.
+    #   changed        — an identity source observes a different identity than the
+    #                    one the session is bound to.
+    #   rehydrated     — the page pulled the server's current session in place and
+    #                    is signed in (possibly as someone new).
+    #   signed_out     — the page was signed in and the server now reports nobody.
+    STATES = %i[anonymous authenticated stale changed rehydrated signed_out].freeze
+
+    # The only states a server render can report. The other four exist only in a
+    # browser that is comparing an old page against a newer truth.
+    SERVER_STATES = %i[anonymous authenticated].freeze
+
+    # Bumped only when a stamp field changes meaning. Additive fields do not bump it.
+    STAMP_VERSION = 1
+
+    attr_reader :user
+
+    def initialize(user)
+      @user = user
+    end
+
+    def state
+      user ? :authenticated : :anonymous
+    end
+
+    def anonymous?
+      state == :anonymous
+    end
+
+    def authenticated?
+      state == :authenticated
+    end
+
+    # The session's fingerprint. The stamp passes its own normalized identities,
+    # so a page render and the rehydrate endpoint always agree for one session.
+    def fingerprint(identities = {})
+      Studio::SessionFingerprint.for(user, identities: identities)
+    end
+
+    # The JSON-ready stamp a page carries and the rehydrate endpoint returns.
+    #
+    #   rehydrate_url — where the browser store refetches this stamp; nil when the
+    #                   host does not draw the route, which leaves the store able to
+    #                   DETECT drift but not repair it in place.
+    #   expires_at    — when this session lapses, if the host's session store says
+    #                   so (a Time, or nil). The store's expiry source fires then.
+    #   identities    — { source name => bound identity string } for host-declared
+    #                   identity sources. Keys and values are stringified; a blank
+    #                   value is dropped rather than sent as "" so an unbound source
+    #                   stays unbound.
+    #   issued_at     — when the server built this stamp. Tabs compare it to decide
+    #                   whose truth is newer.
+    #
+    # Keys are camelCase because the browser reads them; times are epoch
+    # milliseconds so no client has to parse a date string.
+    def to_stamp(rehydrate_url: nil, expires_at: nil, identities: {}, issued_at: Time.now)
+      bound = normalize_identities(identities)
+      {
+        v:            STAMP_VERSION,
+        state:        state.to_s,
+        fingerprint:  fingerprint(bound),
+        issuedAt:     epoch_ms(issued_at),
+        expiresAt:    expires_at && epoch_ms(expires_at),
+        rehydrateUrl: rehydrate_url.to_s.empty? ? nil : rehydrate_url.to_s,
+        identities:   bound
+      }
+    end
+
+    private
+
+    def epoch_ms(time)
+      (time.to_r * 1000).to_i
+    end
+
+    def normalize_identities(identities)
+      (identities || {}).each_with_object({}) do |(name, value), out|
+        next if value.nil? || value.to_s.empty?
+
+        out[name.to_s] = value.to_s
+      end
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.74.11"
+  VERSION = "0.75.0"
 end