studio-engine 0.72.1 → 0.72.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6827dbf6d947e68f03792d54208e63d7132d87291d41c9f25a79a2b375f7c337
-  data.tar.gz: 6208b4449236e9e5a634a99a0f1634a28d53096ee11ab7a53180d41f3e2fc31e
+  metadata.gz: dffda6dc9fdd89e1770f0d456e28cfb9a674679d09bc1226816f3f30ed8cf255
+  data.tar.gz: ef6f36d167f21886920a64cbc687ca0981c49bfb93117050cb74cabf60e8e875
 SHA512:
-  metadata.gz: 214d5859c1c05d13b11c5101ae403121b4874540cca544b201cc5c0d158f6fcef6936e9c9b038ccdc63a5221face3ad2e1f9a12e79406f0cfa741027c7246be8
-  data.tar.gz: 970cee9c4cea2c9fff4210930161e3565fbcd57cb02c4a86f82682e8bf9eca41f6c9ff07986939d37a270d66e4bbbce8c5788e3362e8f6c73936ca9ddf0a4130
+  metadata.gz: 56ce7f21bc05749d76d3a6325f040892ad288f4c82a1bef8e62d64cf0666cd3d88a019a9b9591a375a8d5519ce536d9d6e629ab8dda9f5faaf98b12da6019e8c
+  data.tar.gz: ef82414cc1ed55acf4d35ccafea238e4c2defe39a2ce684ad1fb5e18d8f47dc928b1f07ba015be1fee6b847f357225d2e073b638f03da335270638275bc87f4a

data/CHANGELOG.md

@@ -217,6 +217,45 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Fixed
 
+- **The style guide's two "Sign Wallet" thumbnails no longer crown themselves
+  with a padlock the card stopped drawing, and the guide's lock no longer trails
+  the release that removed it.** solana-studio 0.6.1 replaced the step-up card's
+  padlock with the remembered wallet's own brand mark, falling back to a neutral
+  billfold where no brand is remembered. Both hand-drawn thumbnails in
+  `style/_modals` went on drawing the padlock, so the first thing a designer
+  reads advertised a glyph the design system had retired.
+
+  **THE THUMBNAILS WERE HALF OF IT.** The opened specimen renders the REAL
+  shared partial, but it does so through whatever `Gemfile.lock` resolves — so
+  it is only ever as current as the lock, and the lock sat on 0.6.0 while
+  turf-monster shipped 0.6.1. The guide's opened card was still drawing the
+  padlock too, which `bin/gem-drift-check` had already been failing on
+  (`engine 0.6.0 TRAILS turf-monster 0.6.1`). Correcting the sketches alone
+  would have put a brand mark on the thumbnail and a padlock in the card it
+  opens — moving the contradiction onto one screen rather than removing it. So
+  the lock had to move too, and it has: `accepted` carried the engine to
+  solana-studio 0.7.0 while this change sat in review, which is past the 0.6.1
+  that removed the padlock. This change no longer moves the lock itself — it
+  defers to the line `accepted` already holds — so the sketch and the card it
+  opens agree without it.
+
+  The sketches follow the card: a centered brand tile where a wallet is
+  remembered, the card's own billfold outline in an inset square where none is.
+  They stay SKETCHES rather than real brand marks for a mechanical reason worth
+  recording — every `se-wallet` symbol on the guide is defined inside a
+  `template x-if`, whose content is inert until Alpine clones it, so a `use`
+  placed outside one resolves to nothing and paints an empty box.
+
+  Guarded by `test/views/step_up_specimen_thumbnails_test.rb`, which slices each
+  thumbnail by a `data-test` hook before asserting. That slicing is the point:
+  the rendered guide already carried 17 `se-wallet-` hits from the picker and
+  the card's own CTA, so a page-wide assertion for the mark could not fail, and
+  a page-wide assertion against the padlock could not pass — the drag-board
+  specimen's prose legitimately contains one. The padlock is pinned in BOTH the
+  codepoint and the HTML-entity form. MEASURED: five mutants, five killed —
+  the padlock restored in either form, either header mark removed, and the lock
+  reverted to 0.6.0 each reddens the assertion that owns it.
+
 - **The style guide's page-scoped modal store now resolves animations through
   the LIVE registry, so the guide can no longer disagree with itself.**
   `style/_modals`' `dsModals` carried a hard-coded COPY of the animation table

data/Gemfile

@@ -75,11 +75,29 @@ end
 # nothing — which is precisely why it went four releases unnoticed.)
 #
 # SO THE FIX IS A GATE, NOT A PIN. bin/gem-drift-check fails when this engine's
-# lock TRAILS a consumer's, and consumer-ci.yml runs it — the only lane holding
-# two repos' lockfiles at once. Direction is one-way: engine behind fails, engine
-# ahead or level passes, a consumer bundling no solana-studio is a skip. Keeping
-# up is now enforced rather than remembered, which is what lets the floor stay a
-# floor. Guarded by test/lib/gem_drift_check_test.rb.
+# lock resolves an OLDER solana-studio than a consumer's, and consumer-ci.yml
+# runs it — the only lane holding two repos' lockfiles at once. Direction is
+# one-way: engine behind fails, engine ahead or level passes, a consumer
+# bundling no solana-studio is a skip. Guarded by
+# test/lib/gem_drift_check_test.rb.
+#
+# READ THE CONSUMER AS A MESSENGER, not as the target. The invariant is that
+# this engine resolves the LATEST RELEASED solana-studio. A consumer's lock is
+# compared only because it is the one newer-release fact on disk — the gate is
+# stdlib-only and makes no network call, deliberately, so it cannot ask the
+# registry directly. A consumer being ahead is EVIDENCE of a release this engine
+# missed, never itself the thing to catch up to.
+#
+# AND THE GATE ALONE WAS NOT ENOUGH. Enforcement only reddens; a human still had
+# to do the bump. Measured 2026-09-07: that human was late five times in ONE DAY
+# — by 3h, 2h20m, 14h15m and 1h10m — and the worst case was not the longest but
+# the fastest, a lock that went stale 36 minutes after the previous fix was
+# committed. While it is stale EVERY open engine PR is red, over a line no PR
+# author owns. So .github/dependabot.yml now opens the bump PR daily (scoped to
+# solana-studio ALONE, so this repo never inherits the third-party graveyard),
+# and .github/workflows/engine-lock-automerge.yml merges it when — and only
+# when — all four of bin/lock-bump-mergeable's conditions hold. A breaking bump
+# still stops, stays open and red, and still waits for a human.
 group :development, :test do
   gem "solana-studio", ">= 0.5.3"
 end

data/README.md

@@ -305,6 +305,18 @@ the one credential that skips attestation) and `props.submitting`. It receives
 one local, `modal_store`: the engine's real host is `"modals"`, the living style
 guide's page-scoped host is `"dsModals"`.
 
+**Name a store like a JavaScript identifier.** Partials splice this local in as a
+bare name — `$store.<name>.current()` — rather than as a string, so a value
+carrying a quote, a dot or a space is not a mangled store name: it is a
+SyntaxError in the whole `x-data`, and Alpine mounts a component that renders
+every element and does nothing. Escaping is not the repair (an escaped identifier
+is a different SyntaxError); a name that matches `/\A[A-Za-z_$][A-Za-z0-9_$]*\z/`
+is. `studio/modals/onboarding/_first_name` enforces exactly that and raises
+`ArgumentError` on anything else — the first partial to do so, not yet the fleet.
+Note the shape decides the repair, not the name of the local: `blocks/_birthday`
+and `blocks/_leveling_activity` pass `modal_store` in *string* position and
+correctly `escape_javascript` it instead.
+
 It also keeps two blocks the gem renders **by name** across the gem boundary:
 `studio/modals/blocks/wallet_brand_sprite` and `studio/modals/blocks/card_header`.
 Renaming either is a cross-repo change.

data/app/controllers/studio/onboarding_controller.rb

@@ -45,6 +45,17 @@ module Studio
     def first_name
       value = params[:first_name].to_s.strip.gsub(/\s+/, " ")
 
+      # THE SAME SENTENCE AS THE CARD'S EMPTY-FIELD ERROR, and deliberately NOT
+      # parameterised the way that one now is. `required` is a RENDER-TIME local of
+      # studio/modals/onboarding/_first_name; the server is never told which mode
+      # the card was drawn in, so this branch has no `required` to follow, and
+      # rewording it unconditionally would move McRitchie Studio's copy to say
+      # something only turf's gate needs.
+      #
+      # It is also UNREACHABLE FROM THE CARD: save() returns on a blank value
+      # before it posts, so what arrives here is a direct POST or a host driving
+      # these endpoints with its own form. If that ever becomes a mode-sensitive
+      # surface, the caller says which mode it is in — this string does not guess.
       if value.blank?
         return refuse("Enter your first name, or skip for now.")
       end

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

@@ -10,8 +10,11 @@
   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")
+    submit_path — POST target for the name (default "/onboarding/first_name").
+                  Interpolated into the x-data, so it is JS-escaped on the way in
+                  — see THE TWO SHAPES below.
+    skip_path   — POST target for the skip  (default "/onboarding/skip_first_name").
+                  JS-escaped, same as submit_path.
     required    — hide the SKIP affordances (default false, which keeps today's
                   skippable card). The × then merely CLOSES and is labelled
                   Close, and the "Skip for now" button is not rendered. For a
@@ -24,6 +27,11 @@
                   follows `required`, because a card that cannot be skipped is
                   talking to a different audience — a host that passes its own
                   subtext still wins)
+    empty_error — the inline error shown when the field is submitted EMPTY. Like
+                  subtext, its default follows `required`: a card that renders no
+                  skip must not answer an empty field by offering one. Rendered
+                  INSIDE the x-data, so it is escaped for a JS single-quoted
+                  string on the way in — see CRITICAL below.
     placeholder — (default "Alex")
     placeholder_names — OPTIONAL, and OFF unless passed: an array of first names,
                   one of which is TYPED into the placeholder a character at a
@@ -43,9 +51,13 @@
                   than store a name nobody typed)
     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")
+                  mounts its own page-scoped host and passes "dsModals"). It lands
+                  in IDENTIFIER position, not string position, so it is VALIDATED
+                  rather than escaped and a value that is not a JS identifier
+                  raises ArgumentError at render — see THE TWO SHAPES below.
     done_event  — window event dispatched when this step is finished, saved or
-                  skipped (default "onboarding-step-done"). Its detail carries
+                  skipped (default "onboarding-step-done"). JS-escaped, same as
+                  submit_path. Its detail carries
                   `{ next: [...], saved: true|false }` — see THE OUTCOME below.
                   The HOST decides what happens next; this partial never knows.
 
@@ -73,6 +85,38 @@
   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.
+
+  THE TWO SHAPES — read this before adding a local to the x-data. Five locals are
+  interpolated into that attribute and they do NOT take the same repair. Getting
+  this wrong does not raise; it mounts a card that renders every element and does
+  nothing, which is why it is written down here rather than left to be noticed.
+
+    STRING position — empty_error, submit_path, skip_path, done_event — each sits
+      inside a JS SINGLE-quoted literal. A bare apostrophe closes the literal, the
+      expression becomes a SyntaxError, and the card is that silent no-op. Repair:
+      escape_javascript, in the INTERPOLATED form. The wrapper is load-bearing:
+      escape_javascript(SafeBuffer) answers true to html_safe, so ERB would skip
+      its own attribute-escaping half and a raw double quote could still close the
+      attribute. Wrapping the value in a plain interpolation first strips the safe
+      marking, so both escapers run.
+
+    IDENTIFIER position — modal_store — is spliced in as a bare NAME, at three
+      sites: the props getter, finish's close, and the Ruby-built dismiss_action
+      emitted into the x's click handler. Escaping is the WRONG repair here: an
+      escaped identifier is a different SyntaxError and the same dead card.
+      Repair: refuse a value that is not a JS identifier, which the Ruby block
+      below does once, at the source, so all three sites are covered.
+
+  A PATTERN, NOT AN ALLOWLIST, and the reason is worth keeping: an allowlist would
+  be this engine enumerating its own consumers, so the next app to mount a
+  page-scoped host would be refused by its own dependency until a gem release
+  admitted the name. The contract is narrower and stateless — it is spliced into
+  member-access position, so it must be an identifier, and which one is the host's
+  business.
+
+  NOTE THE SAME LOCAL TAKES THE OTHER REPAIR ELSEWHERE. blocks/_birthday and
+  blocks/_leveling_activity pass modal_store in STRING position and escape it,
+  correctly. The shape decides the repair, never the name of the local.
 %>
 <%
   submit_path = local_assigns.fetch(:submit_path, "/onboarding/first_name")
@@ -85,6 +129,31 @@
                       "Just your first name — we use it to address you in emails."
                     end
   subtext     = local_assigns.fetch(:subtext, default_subtext)
+  # The inline error for an EMPTY field, resolved here for the same reason
+  # default_subtext is: `required` is known at render time, and a card that
+  # renders no skip button must not answer an empty field by offering one. It was
+  # a hard-coded literal until now, which is why a gated card told the user to
+  # skip for now and pointed at a button that is not on the page.
+  default_empty_error = if required
+                          "Enter your first name to continue."
+                        else
+                          "Enter your first name, or skip for now."
+                        end
+  empty_error = local_assigns.fetch(:empty_error, default_empty_error)
+  # ESCAPED FOR THE x-data, which is the hazard this local introduces: it is the
+  # first HOST-SUPPLIED PROSE to go inside that attribute, and prose has
+  # apostrophes. Interpolated raw, an error reading "We'll need a name" would
+  # close the JS single-quoted string, make the whole expression a SyntaxError,
+  # and mount the component as a SILENT NO-OP that still renders every element
+  # below. escape_javascript covers the apostrophe, the double quote, the
+  # backslash and the newline; the interpolation around it first strips any
+  # html_safe marking, because a safe string would skip ERB's own attribute
+  # escaping and could smuggle a raw double quote in — the exact failure the
+  # CRITICAL note above describes.
+  #
+  # INERT ON BOTH DEFAULTS. Neither default string contains a character either
+  # escaper touches, so the shipped card is byte-for-byte what it was.
+  empty_error_js = escape_javascript("#{empty_error}")
   placeholder = local_assigns.fetch(:placeholder, "Alex")
   # OFF unless a host passes a non-empty array. Normalised to nil so that an
   # empty list behaves exactly like an absent local rather than emitting the
@@ -95,7 +164,58 @@
   max_length  = local_assigns.fetch(:max_length, Studio::FULL_NAME_MAX_LENGTH)
   progress    = local_assigns.fetch(:progress, nil)
   modal_store = local_assigns.fetch(:modal_store, "modals")
+  # VALIDATED, NOT ESCAPED — and that distinction is the whole point of this local.
+  # Every other value inside the x-data is a JS STRING and is repaired by escaping.
+  # This one is spliced in as a bare NAME (`$store.<name>.current()`), so the same
+  # repair breaks it: escape_javascript turns `a'b` into `a\'b`, and
+  # `$store.a\'b.current()` is not a rescued identifier, it is a different
+  # SyntaxError — the same silently dead card, reached a longer way.
+  #
+  # A PATTERN RATHER THAN AN ALLOWLIST, deliberately. An allowlist would be this
+  # engine enumerating its own CONSUMERS — "modals" and the style guide's
+  # "dsModals" today — so the next app to mount a page-scoped host would be refused
+  # by its own dependency until a gem release admitted the name. That is backwards
+  # for a shared primitive. The real contract is narrower and stateless: this is
+  # spliced into member-access position, so it must be a JS identifier, and WHICH
+  # identifier is none of the engine's business.
+  #
+  # ASCII IdentifierName, which is what member access after a dot accepts. It
+  # admits every store name a host would plausibly write and rejects every
+  # character that could leave identifier position — quote, apostrophe, backslash,
+  # dot, space, semicolon, angle bracket.
+  #
+  # IT RAISES RATHER THAN FALLING BACK TO THE DEFAULT. A silent fallback is the
+  # worse of the two repairs: the card would mount, look perfect, and talk to a
+  # store that is not the host's — which is the SILENT-brick failure class this
+  # guard exists to leave behind. A host sees this the first time it renders.
+  unless modal_store.to_s.match?(/\A[A-Za-z_$][A-Za-z0-9_$]*\z/)
+    raise ArgumentError,
+          "modal_store must be a JS identifier (it is spliced into $store.<name>); " \
+          "got #{modal_store.inspect}. Escaping it would not help — an escaped " \
+          "identifier is a different SyntaxError, and the card would mount dead."
+  end
   done_event  = local_assigns.fetch(:done_event, "onboarding-step-done")
+  # THE SAME HAZARD empty_error_js CARRIES, on the three remaining locals that land
+  # inside a JS SINGLE-quoted literal in the x-data below. A bare apostrophe in any
+  # of them closes its literal, the whole expression becomes a SyntaxError, and
+  # Alpine mounts the component as a SILENT NO-OP that still renders every element
+  # — perfect-looking markup, dead card.
+  #
+  # THE INTERPOLATED FORM IS LOAD-BEARING, not a style choice:
+  # escape_javascript(SafeBuffer).html_safe? is TRUE, so ERB would skip its own
+  # attribute-escaping half and a raw double quote could still close the
+  # double-quoted x-data. Wrapping in "#{}" first strips the html_safe marking, so
+  # both escapers run: escape_javascript for the JS literal, ERB for the attribute.
+  #
+  # INERT ON EVERY DEFAULT. Two paths, an event name and a store name carry no
+  # character either escaper touches, so the shipped card is byte-for-byte what it
+  # was — the golden-fixture pin in the view test says so. This is latent cover: no
+  # host supplies these as prose today, but empty_error established that prose does
+  # belong in this attribute, and the next local to carry an apostrophe will look
+  # like an ordinary change to whoever writes it.
+  submit_path_js = escape_javascript("#{submit_path}")
+  skip_path_js   = escape_javascript("#{skip_path}")
+  done_event_js  = escape_javascript("#{done_event}")
   field_id    = local_assigns.fetch(:id, "onboarding-first-name")
   # The × mirrors the skip affordance it sits beside: it SKIPS while the step is
   # skippable, and merely CLOSES once it is required. Resolved here rather than in
@@ -175,9 +295,9 @@
        async save() {
          if (this.submitting) return;
          var value = (this.firstName || '').trim();
-         if (!value) { this.error = 'Enter your first name, or skip for now.'; return; }
+         if (!value) { this.error = '<%= empty_error_js %>'; return; }
          this.submitting = true; this.error = '';
-         var data = await this.post('<%= submit_path %>', { first_name: value });
+         var data = await this.post('<%= submit_path_js %>', { first_name: value });
          this.submitting = false;
          if (!data || !data.ok) {
            this.error = (data && data.error) || 'Could not save that — try again.';
@@ -188,7 +308,7 @@
        async skip() {
          if (this.submitting) return;
          this.submitting = true; this.error = '';
-         var data = await this.post('<%= skip_path %>', {});
+         var data = await this.post('<%= skip_path_js %>', {});
          this.submitting = false;
          this.finish((data && data.next) || [], false);
        },
@@ -211,7 +331,7 @@
 <% if typed_placeholder %>
          this.stopPlaceholder();
 <% end %>
-         window.dispatchEvent(new CustomEvent('<%= done_event %>', { detail: { next: next, saved: !!saved } }));
+         window.dispatchEvent(new CustomEvent('<%= done_event_js %>', { detail: { next: next, saved: !!saved } }));
          $store.<%= modal_store %>.close();
        }
      }"

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

@@ -1291,9 +1291,22 @@
             on a 20px row, which is not a difference anyone can see at thumbnail
             size — and these two cards are the pair most likely to be mistaken for
             duplicates, because they share a modal id AND a title. So the sketch
-            now shows the actual distinction: this card KNOWS which wallet. %>
-        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 text-center space-y-2">
-          <div class="text-2xl leading-none">🔐</div>
+            now shows the actual distinction: this card KNOWS which wallet.
+
+            THE HEADER IS THE WALLET'S OWN MARK, not a padlock. This crowned a
+            padlock until 2026-09-07, which the card had already stopped drawing —
+            a thumbnail showing a glyph the card never paints is the style guide
+            misreporting the design system. The card now heads itself with the
+            remembered wallet's brand mark, so the sketch heads itself with a
+            brand tile, the same idiom the Connect-wallet thumbnail above uses.
+
+            A REAL SPRITE CANNOT BE USED HERE, and it is worth saying why so the
+            next reader does not try. Every se-wallet symbol on this page is
+            defined inside a template x-if, whose content is inert until Alpine
+            clones it, so a use outside one resolves to nothing and paints an
+            empty box. Thumbnails are sketches for that reason, not only taste. %>
+        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 text-center space-y-2" data-test="step-up-thumb-brand">
+          <span class="block w-7 h-7 mx-auto rounded-lg" style="background: var(--color-primary)"></span>
           <span class="block h-2 w-24 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
           <span class="flex items-center gap-1.5 h-7 w-full rounded-lg border px-1.5" style="border-color: var(--color-border-strong)">
             <span class="w-4 h-4 rounded shrink-0" style="background: var(--color-primary)"></span>
@@ -1311,9 +1324,21 @@
             disabled: web3_card_off, openable: web3_gem } do %>
         <%# An EMPTY slot: dashed outline, no brand tile, a "?" where the wallet's
             name would be. Reads at a glance as "we do not know which wallet",
-            which is the whole difference between this card and the one before it. %>
-        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 text-center space-y-2">
-          <div class="text-2xl leading-none">🔐</div>
+            which is the whole difference between this card and the one before it.
+
+            THE HEADER IS THE NEUTRAL BILLFOLD the card falls back to when no
+            brand is remembered — the same rounded, inset-filled square drawn with
+            the card's own billfold outline. It replaced a padlock on 2026-09-07,
+            for the reason given on the card above this one. Drawing the billfold
+            rather than tinting a tile keeps the two headers as different as the
+            two cards are: one names a wallet, this one cannot. %>
+        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 text-center space-y-2" data-test="step-up-thumb-no-brand">
+          <span class="inline-flex w-7 h-7 rounded-lg bg-inset items-center justify-center" aria-hidden="true">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" class="w-4 h-4 text-secondary">
+              <rect x="3" y="6.5" width="18" height="11" rx="2.5" />
+              <circle cx="16.6" cy="12" r="1.3" fill="currentColor" stroke="none" />
+            </svg>
+          </span>
           <span class="block h-2 w-24 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
           <span class="flex items-center justify-center h-7 w-full rounded-lg border border-dashed" style="border-color: var(--color-border-strong)">
             <span class="text-xs font-bold text-muted leading-none">?</span>

data/lib/studio/theme_resolver.rb

@@ -32,6 +32,13 @@ module Studio
       primary     = colors[:primary] || "#8E82FE"
       border_rgb  = ColorScale.lighten(dark_base, 0.30)
       danger      = colors[:danger] || "#EF4444"
+      surfaces    = dark_surfaces(dark_base)
+
+      secondary_ink = contrast_ink(dark_base, direction: :lighten, start: 0.70, target: 4.5, against: surfaces)
+      muted_ink     = ladder_clamp(
+        contrast_ink(dark_base, direction: :lighten, start: 0.55, target: 4.5, against: surfaces),
+        secondary_ink, direction: :lighten
+      )
 
       {
         "--color-page"           => dark_base,
@@ -48,10 +55,15 @@ module Studio
         # until the ink clears its target on every emitted dark surface
         # (clamped at pure white for pathological bases). Note the blend
         # DESATURATES toward gray; only strongly-tinted bases keep a cast.
-        "--color-text-secondary" => contrast_ink(dark_base, direction: :lighten, start: 0.70, target: 4.5,
-                                                 against: dark_surfaces(dark_base)),
-        "--color-text-muted"     => contrast_ink(dark_base, direction: :lighten, start: 0.55, target: 3.0,
-                                                 against: dark_surfaces(dark_base)),
+        "--color-text-secondary" => secondary_ink,
+        # MUTED IS NORMAL-SIZE TEXT, so its target is AA 4.5:1 — not 3.0.
+        # 3.0 is WCAG's LARGE-text allowance (>=18.66px, or 14px bold) and this
+        # ink does not land on large text: the engine's own `.label-upper`
+        # utility is `text-xs text-muted` (12px), and consumers render it at
+        # 11px. Measured on the default theme before this change: muted was
+        # #9896A4 at 3.84:1 on --color-surface (dark) and #818283 at 3.46:1 on
+        # --color-surface-alt (light) — both below AA, in BOTH themes.
+        "--color-text-muted"     => muted_ink,
         "--color-border"         => ColorScale.with_opacity(border_rgb, 0.2),
         "--color-border-strong"  => ColorScale.with_opacity(border_rgb, 0.4),
         "--color-shadow"         => "transparent",
@@ -95,6 +107,31 @@ module Studio
         ColorScale.darken(light_base, 0.08) ]
     end
 
+    # Keep the ink ladder monotonic: muted is the QUIETEST text ink and must
+    # never come out louder than secondary.
+    #
+    # This became reachable the moment muted's target rose to 4.5 and the two
+    # inks started sharing one threshold. They are found by the same stepped
+    # search from DIFFERENT starts (muted 0.40/0.55, secondary 0.55/0.70), so
+    # their grids are offset and the one that starts lower can overshoot PAST
+    # the one that starts higher. Measured on the default light base #f8fafc:
+    # the true minimum blend clearing 4.5 is 0.59, secondary lands exactly
+    # there, and muted — stepping 0.40, 0.42, ... — skips 0.59 and lands on
+    # 0.60, i.e. DARKER than secondary. The ladder inverted while every
+    # contrast assertion stayed green, because nothing compared the two.
+    #
+    # Ordering is a design decision, so make it structurally rather than let a
+    # 0.02 grid decide it. `direction` says which way "louder" runs: lightened
+    # ink on a dark base is louder as luminance RISES; darkened ink on a light
+    # base is louder as luminance FALLS.
+    def ladder_clamp(muted, secondary, direction:)
+      muted_l     = ColorScale.relative_luminance(muted)
+      secondary_l = ColorScale.relative_luminance(secondary)
+      louder = direction == :lighten ? muted_l > secondary_l : muted_l < secondary_l
+
+      louder ? secondary : muted
+    end
+
     # Bounded, clamped search: raise the blend amount from `start` until the
     # ink clears `target` contrast against every background in `against`.
     # Clamps at 1.0 (pure white/black), so a pathological base degrades to the
@@ -133,6 +170,13 @@ module Studio
       light_base = colors[:light] || "#f8fafc"
       primary    = colors[:primary] || "#8E82FE"
       danger     = colors[:danger] || "#EF4444"
+      surfaces   = light_surfaces(light_base)
+
+      secondary_ink = contrast_ink(light_base, direction: :darken, start: 0.55, target: 4.5, against: surfaces)
+      muted_ink     = ladder_clamp(
+        contrast_ink(light_base, direction: :darken, start: 0.40, target: 4.5, against: surfaces),
+        secondary_ink, direction: :darken
+      )
 
       {
         "--color-page"           => light_base,
@@ -144,10 +188,9 @@ module Studio
         # Same bounded search as dark mode: the old fixed grays measured as
         # low as 2.05:1 (muted on --color-inset) — below the very defect this
         # derivation exists to prevent. Ink darkens away from the light base.
-        "--color-text-secondary" => contrast_ink(light_base, direction: :darken, start: 0.55, target: 4.5,
-                                                 against: light_surfaces(light_base)),
-        "--color-text-muted"     => contrast_ink(light_base, direction: :darken, start: 0.40, target: 3.0,
-                                                 against: light_surfaces(light_base)),
+        "--color-text-secondary" => secondary_ink,
+        # See the dark-mode note: muted is normal-size text and owes AA 4.5:1.
+        "--color-text-muted"     => muted_ink,
         "--color-border"         => ColorScale.darken(light_base, 0.08),
         "--color-border-strong"  => ColorScale.darken(light_base, 0.15),
         "--color-shadow"         => "rgba(0,0,0,0.05)",

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.72.1"
+  VERSION = "0.72.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.72.1
+  version: 0.72.2
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 2026-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails