studio-engine 0.74.2 → 0.74.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6694226dcc9e100149692ef60162478d4927a69280343c5047c0222517f1f68c
-  data.tar.gz: 8e6b5c07f8bb5fa60466049f321c7be0a09168fb750766202a5d122734cb6699
+  metadata.gz: 2719af0f10410f44f1ac53e1a17fe244de4a9c4ecae8eb94715c75a69450839b
+  data.tar.gz: 9c705e4cb7e9816594d2fc13732ea5449f1523e02645a1108bb4b1f1d50d887f
 SHA512:
-  metadata.gz: 6ec39596a087d56cc64f3a211ea349bf6a00b7a21c6eb1d1c70b36136dda3f3ab7f8fe1a1f61b26593661283f12707501727d9f3d5119f01b3fa28995ece7bd7
-  data.tar.gz: 3d65093bf62c9088976d9ea56e756cabd7e01e65aaae06205419e337a0d8b6a1a1b93c60b93631bf724d254f01bcdc5fb0c7360c50525c1f519b35b6b7b49946
+  metadata.gz: 18833874f77e97c16f56c20135ecdb897d8f7d47316c2d122947bfdbd71d23117f825d51fe3a62ff417099c1051d6ea0aead4650715f9212aa68b5520d266333
+  data.tar.gz: 85568864c586c37ef1f17edefb9f23776b1f5f2089c09f331139000e88cd2dd1e47db031d01a456c3a9b267f8aced700b9221c04d0d4e1809c4381f4b0e5f020

data/CHANGELOG.md

@@ -6,6 +6,52 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Fixed
 
+- **A store name that is not a JS identifier half-worked, silently, in seventeen
+  partials — it now raises.** `$store.<%= modal_store %>.close()` splices the local
+  in as a bare NAME, so `modal_store: "my store"` emitted
+  `$store.my store.close()`: a SyntaxError that Alpine mounts as a no-op which still
+  renders every element. `Studio::JsIdentifier.validate!` is the new shared contract
+  (`/\A[A-Za-z_$][A-Za-z0-9_$]*\z/`), called once per partial at the fetch.
+
+  **THIS IS A BEHAVIOUR TIGHTENING, NOT A REPAIR, and it is breaking.** A host that
+  passed a non-identifier store name got a working page with a dead button; it now
+  gets an `ArgumentError` at render. That is the right trade — loud beats silent —
+  but it is a 500 where there was a 200. **Blast radius is zero, measured:** every
+  explicit store name in mcritchie-studio, turf-monster, rolio and this engine is
+  `modals`, `dsModals`, `emailModals` or `profileModals`, and no consumer app passes
+  one at all. **Rollback is one file:** make `validate!` return its argument instead
+  of raising and every partial is back to the old leniency, with no call site to
+  revisit.
+
+  **ESCAPING IS THE WRONG REPAIR HERE, which is why this is a second module rather
+  than a second method on `Studio::JsLiteral`.** `escape_javascript` also escapes
+  `$`, so the legal name `dsModals$2` comes back as `dsModals\$2` and
+  `$store.dsModals\$2.close()` is a different SyntaxError — the same dead card on a
+  value that was never hostile. A pattern rather than an allowlist, deliberately: an
+  allowlist would be a shared gem enumerating its own consumers, and the next app to
+  mount a page-scoped host would be refused by its own dependency.
+
+  **MEASURED, AND TWO OF THE LISTED SITES WERE LEFT ALONE.** Nineteen partials fetch
+  a store-name local. Counted on the tree: 36 splices of a store name in identifier
+  position — 32 in ERB, 4 assembled in Ruby — across 17 files. Rendering a hostile
+  value through all nineteen (rather than reading them) showed 17 emitting at least
+  one DEAD splice, one already refusing, and one unaffected. Seventeen now carry the
+  guard: 16 new, plus `modals/onboarding/_first_name` moved onto the shared one.
+  `modals/_crop_photo` is the unaffected one — its name is a JS string argument
+  resolved with `$store[name]`, a lookup where a space is as legal as a letter, and
+  it was already escaped, so demanding an identifier would break a host for nothing.
+  `blocks/_birthday` has no splice of its own — it hands the name to `Alpine.store()`
+  and forwards it to `blocks/_shell`, which validates — so a second guard there would
+  have been one that survives deletion.
+
+  **NOTHING MOVED FOR A LEGAL NAME.** All nineteen partials rendered before and
+  after, against the default, `dsModals` and `ds_Modals$2`, are byte-identical
+  (186,310 bytes each): a value matching the pattern carries no character ERB
+  escapes, and the validator returns a plain String so ERB's escaping stays armed
+  for the day the pattern widens. `modals/onboarding/_first_name` carried this
+  regex inline as the worked example and now calls the shared one — same pattern,
+  same error, same message.
+
 - **The email banner assembled two attributes INCLUDING THEIR OWN QUOTES in Ruby,
   so ERB escaping never ran on them.** `_layered_banner.html.erb` wrote
   `background="..."` and `bgcolor="..."` as Ruby strings and marked them

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

@@ -10,7 +10,8 @@
                      apps omit this; the /admin/style demo passes an expression
                      (e.g. close) so the specimen self-terminates after min_duration
                      instead of spinning forever. %>
-<% saving_store = local_assigns.fetch(:store, "modals") %>
+<%# IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier. %>
+<% saving_store = Studio::JsIdentifier.validate!(local_assigns.fetch(:store, "modals"), local: :store) %>
 <div>
   <%= render "studio/modals/blocks/processing_card",
         title_key: "$store.#{saving_store}.current()?.props?.title || 'Saving…'",

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

@@ -46,7 +46,9 @@
   rest of it onto the page as visible text. That shipped once.)
 %>
 <%
-  scoped_store = local_assigns.fetch(:store)
+  # IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier.
+  scoped_store = Studio::JsIdentifier.validate!(
+                 local_assigns.fetch(:store), local: :store)
   card_class   = local_assigns.fetch(:card_class,
                    "bg-surface rounded-xl border border-subtle shadow-2xl p-6 max-w-sm w-full")
 %>

data/app/views/studio/modals/auth/_resend_footer.html.erb

@@ -12,7 +12,9 @@
     modal_store — Alpine store name backing close(). Default "modals".
 %>
 <%
-  modal_store = local_assigns.fetch(:modal_store, "modals")
+  # IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier.
+  modal_store = Studio::JsIdentifier.validate!(
+                local_assigns.fetch(:modal_store, "modals"), local: :modal_store)
 %>
 <button @click="resendMagicLink()" :disabled="props.submitting === 'magic-link' || (props.resendCooldown || 0) > 0"
         class="block mx-auto text-sm text-primary hover:text-primary-300 underline underline-offset-2 disabled:opacity-50 disabled:no-underline">

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

@@ -62,7 +62,9 @@
   birthday_modal_id = local_assigns.fetch(:birthday_modal_id, "birthday")
   back_label        = local_assigns.fetch(:back_label, "Update your Birthday")
   title             = local_assigns[:title]
-  modal_store       = local_assigns.fetch(:modal_store, "modals")
+  # IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier.
+  modal_store       = Studio::JsIdentifier.validate!(
+                      local_assigns.fetch(:modal_store, "modals"), local: :modal_store)
 %>
 <div x-data="{
        now: Date.now(),

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

@@ -80,6 +80,13 @@
   fine_print  = local_assigns.fetch(:fine_print,
                   validates ? "We use your date of birth only to confirm eligibility."
                             : "We use your date of birth only to know when to wish you a happy birthday.")
+  # NOT VALIDATED HERE, deliberately. This partial never splices the store name into
+  # identifier position: it reaches birthdayModal as a JS STRING (escaped below) and
+  # the factory looks it up with Alpine.store(name), where any character is legal.
+  # The identifier contract is owed by blocks/_shell, which this card renders one
+  # line further down and which validates it — so a hostile value still raises,
+  # once, at the site that actually splices it. A second guard here would be a
+  # redundant one: it would survive being deleted.
   modal_store = local_assigns.fetch(:modal_store, "modals")
   demo        = local_assigns.fetch(:demo, false)
   demo_underage     = local_assigns.fetch(:demo_underage, false)

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

@@ -42,7 +42,9 @@
     label       — aria-label. Default "Close".
 %>
 <%
-  modal_store = local_assigns.fetch(:modal_store, "modals")
+  # IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier.
+  modal_store = Studio::JsIdentifier.validate!(
+                local_assigns.fetch(:modal_store, "modals"), local: :modal_store)
   label       = local_assigns.fetch(:label, "Close")
 %>
 <button type="button" @click="$store.<%= modal_store %>.close()"

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

@@ -25,7 +25,9 @@
   href_key         = local_assigns.fetch(:href_key)
   label_html       = local_assigns.fetch(:label_html, "Continue")
   duration_seconds = local_assigns.fetch(:duration_seconds, 5)
-  modal_store      = local_assigns.fetch(:modal_store, "modals")
+  # IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier.
+  modal_store      = Studio::JsIdentifier.validate!(
+                     local_assigns.fetch(:modal_store, "modals"), local: :modal_store)
 %>
 <div x-data="{
        _redirectTimer: null,

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

@@ -60,7 +60,9 @@
                        that does nothing.
 %>
 <%
-  modal_store      = local_assigns.fetch(:modal_store, "modals")
+  # IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier.
+  modal_store      = Studio::JsIdentifier.validate!(
+                     local_assigns.fetch(:modal_store, "modals"), local: :modal_store)
   props_expr       = local_assigns.fetch(:props_expr,
                        "(function () { var c = $store.#{modal_store}.current(); return (c && c.props) || {}; })()")
   above_seeds        = local_assigns[:above_seeds]

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

@@ -19,7 +19,9 @@
     close_label  — dismiss link text. Default "Close".
 %>
 <%
-  modal_store  = local_assigns.fetch(:modal_store, "modals")
+  # IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier.
+  modal_store  = Studio::JsIdentifier.validate!(
+                 local_assigns.fetch(:modal_store, "modals"), local: :modal_store)
   icon_emoji   = local_assigns.fetch(:icon_emoji, "🎉")
   title_key    = local_assigns.fetch(:title_key, "props.level ? ('Level ' + props.level) : 'Free Entry Earned'")
   subtitle     = local_assigns.fetch(:subtitle, "You leveled up and earned a reward. Keep earning more with each level.")

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

@@ -91,7 +91,9 @@
   free_entry_label   = local_assigns.fetch(:free_entry_label, "Free Entry Earned 🎟️")
   seeds_per_level    = local_assigns.fetch(:seeds_per_level, 100)
   leveling           = local_assigns.fetch(:leveling, Studio.feature?(:leveling))
-  modal_store        = local_assigns.fetch(:modal_store, "modals")
+  # IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier.
+  modal_store        = Studio::JsIdentifier.validate!(
+                       local_assigns.fetch(:modal_store, "modals"), local: :modal_store)
   demo               = local_assigns.fetch(:demo, false)
   # consent_label — render a consent checkbox that gates the action (newsletter
   # join). next_label / next_open — an optional "Next Quest" button in the

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

@@ -27,7 +27,9 @@
   cta_label_key    = local_assigns.fetch(:cta_label_key)
   cta_href_key     = local_assigns.fetch(:cta_href_key)
   cluster_param    = local_assigns.fetch(:cluster_param, "")
-  modal_store      = local_assigns.fetch(:modal_store, "modals")
+  # IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier.
+  modal_store      = Studio::JsIdentifier.validate!(
+                     local_assigns.fetch(:modal_store, "modals"), local: :modal_store)
 %>
 <div>
   <%= render "studio/modals/blocks/card_header",

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

@@ -13,7 +13,9 @@
 <%
   shell_title       = local_assigns[:title]
   shell_dismissible = local_assigns.fetch(:dismissible, true)
-  modal_store       = local_assigns.fetch(:modal_store, "modals")
+  # IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier.
+  modal_store       = Studio::JsIdentifier.validate!(
+                      local_assigns.fetch(:modal_store, "modals"), local: :modal_store)
 %>
 <div>
   <% if shell_title || shell_dismissible %>

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

@@ -104,8 +104,8 @@
       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.
+      Repair: refuse a value that is not a JS identifier, which one call to
+      Studio::JsIdentifier.validate! does at the source, covering all three sites.
 
   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
@@ -116,7 +116,9 @@
 
   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.
+  correctly. The shape decides the repair, never the name of the local. And where
+  a store name reaches ONLY a string — blocks/_birthday hands it to Alpine.store(),
+  a lookup by string — no identifier is owed and none is demanded.
 %>
 <%
   submit_path = local_assigns.fetch(:submit_path, "/onboarding/first_name")
@@ -163,37 +165,21 @@
   typed_placeholder = !placeholder_names.nil?
   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.
+  # repair breaks it: escape_javascript backslash-escapes the apostrophe, and an
+  # escaped apostrophe 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
+  # THE REGEX AND THE ARGUMENT USED TO LIVE HERE, INLINE. This card was the first
+  # site to need them, so it carried the worked example; the engine has sixteen more
+  # splices of a store name in identifier position, and the contract now lives in ONE
+  # place. Studio::JsIdentifier holds the pattern, why it is a pattern and not an
+  # allowlist, and why it raises rather than falling back to the default. Behaviour
+  # here is unchanged: same pattern, same ArgumentError, same message.
+  modal_store = Studio::JsIdentifier.validate!(
+                  local_assigns.fetch(:modal_store, "modals"), local: :modal_store)
   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

data/app/views/studio/modals/templates/_action.html.erb

@@ -7,7 +7,8 @@
     icon_color :primary / :success / :warning to card_header.
 
     Local: modal_store — Alpine store name backing close(). Default "modals". %>
-<% modal_store = local_assigns.fetch(:modal_store, "modals") %>
+<%# IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier. %>
+<% modal_store = Studio::JsIdentifier.validate!(local_assigns.fetch(:modal_store, "modals"), local: :modal_store) %>
 <div x-data>
   <%= render "studio/modals/blocks/card_header",
         size: :lg,

data/app/views/studio/modals/templates/_form.html.erb

@@ -4,7 +4,8 @@
     + close ×. Ported from turf-monster.
 
     Local: modal_store — Alpine store name backing close(). Default "modals". %>
-<% modal_store = local_assigns.fetch(:modal_store, "modals") %>
+<%# IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier. %>
+<% modal_store = Studio::JsIdentifier.validate!(local_assigns.fetch(:modal_store, "modals"), local: :modal_store) %>
 <div x-data="{ value: '' }">
   <%= render layout: "studio/modals/blocks/shell", locals: { title: "Form Template", modal_store: modal_store } do %>
     <p class="text-sm text-muted mb-4">

data/app/views/studio/modals/templates/_status.html.erb

@@ -6,7 +6,8 @@
     at 1.6s so a viewer can step through both states.
 
     Local: modal_store — Alpine store name backing close(). Default "modals". %>
-<% modal_store = local_assigns.fetch(:modal_store, "modals") %>
+<%# IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier. %>
+<% modal_store = Studio::JsIdentifier.validate!(local_assigns.fetch(:modal_store, "modals"), local: :modal_store) %>
 <div x-data="{
        state: 'loading',
        start() {

data/app/views/studio/modals/templates/_success.html.erb

@@ -5,7 +5,8 @@
     use studio/modals/blocks/_onchain_success instead. Ported from turf-monster.
 
     Local: modal_store — Alpine store name backing close(). Default "modals". %>
-<% modal_store = local_assigns.fetch(:modal_store, "modals") %>
+<%# IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier. %>
+<% modal_store = Studio::JsIdentifier.validate!(local_assigns.fetch(:modal_store, "modals"), local: :modal_store) %>
 <div x-data>
   <%= render "studio/modals/blocks/card_header",
         size: :lg,

data/app/views/studio/modals/templates/_wizard.html.erb

@@ -8,7 +8,8 @@
     primary CTA pulling forward; Back as a subtle link, hidden on step 1.
 
     Local: modal_store — Alpine store name backing close(). Default "modals". %>
-<% modal_store = local_assigns.fetch(:modal_store, "modals") %>
+<%# IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier. %>
+<% modal_store = Studio::JsIdentifier.validate!(local_assigns.fetch(:modal_store, "modals"), local: :modal_store) %>
 <div x-data="{ step: 1, total: 3 }">
   <div class="relative mb-3 -mt-2">
     <h3 class="text-heading font-bold text-lg leading-tight text-center pt-1">Wizard Template</h3>

data/lib/studio/js_identifier.rb

@@ -0,0 +1,88 @@
+module Studio
+  # ONE home for the CONTRACT a host-supplied value must meet when a partial
+  # splices it into JS **identifier position** — a bare NAME rather than a string:
+  #
+  #     <button @click="$store.<%= modal_store %>.close()">
+  #
+  # THE SIBLING OF Studio::JsLiteral, AND ITS OPPOSITE. Both exist for the same
+  # silent failure: a host value that makes an Alpine expression a SyntaxError, so
+  # the component mounts as a NO-OP that still renders every element. Perfect
+  # markup, dead card, nothing raised and nothing logged. The two differ on the
+  # only question that matters — WHAT THE VALUE IS:
+  #
+  #   STRING position  — the value is DATA inside a JS literal. Any character is
+  #     legal; the repair is to ESCAPE it (Studio::JsLiteral.in_attribute).
+  #   IDENTIFIER position — the value is a NAME. Most characters are not legal at
+  #     all; the repair is to REFUSE it, which is this module.
+  #
+  # ESCAPING IS ACTIVELY WRONG HERE, which is why this is a second module rather
+  # than a second method on the first. escape_javascript also escapes `$`, so a
+  # perfectly legal store name like `dsModals$2` comes back as `dsModals\$2` and
+  # `$store.dsModals\$2.close()` is a SyntaxError — the same dead card, reached a
+  # longer way, on a value that was never hostile. And for a value that IS hostile,
+  # `$store.a\'b.close()` is not a rescued identifier either. There is no escaping
+  # of identifier position; there is only validity.
+  #
+  # A PATTERN, NOT AN ALLOWLIST, and the reason outlives this engine. An allowlist
+  # would be a shared primitive 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.
+  # The real contract is narrower and stateless: the value is spliced into
+  # member-access position, so it must be an identifier, and WHICH identifier is
+  # none of the engine's business.
+  #
+  # IT RAISES RATHER THAN FALLING BACK TO A 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 — the same SILENT class this guard exists to leave behind,
+  # only now with a working-looking page in front of it. A host meets this the first
+  # time it renders, in development, with the local named.
+  #
+  # WHAT IT DOES NOT COVER. A value in string position that is ALSO a store name
+  # (blocks/_birthday's `store: '<%= j modal_store %>'`, which reaches
+  # `Alpine.store(name)` — a lookup by string, where any character is legal) needs no
+  # identifier. Validate where the value reaches a SPLICE, not everywhere the word
+  # "store" appears; test/views/js_identifier_locals_test.rb carries the census.
+  module JsIdentifier
+    # ASCII IdentifierName — what member access after a dot accepts. It admits every
+    # store name a host would plausibly write (`modals`, `dsModals`, `ds_Modals$2`)
+    # and rejects every character that could leave identifier position: quote,
+    # apostrophe, backslash, dot, space, semicolon, angle bracket, and the empty
+    # string.
+    #
+    # DELIBERATELY NOT THE FULL ECMAScript GRAMMAR, which admits most of Unicode.
+    # Widening it is a decision, not a bug fix — and it would have to be taken
+    # together with the marking note on #validate! below, because the value's safety
+    # under ERB is what the narrow set buys.
+    PATTERN = /\A[A-Za-z_$][A-Za-z0-9_$]*\z/
+
+    module_function
+
+    # Return +value+ as a String, or raise ArgumentError naming +local+.
+    #
+    #     modal_store = Studio::JsIdentifier.validate!(
+    #                     local_assigns.fetch(:modal_store, "modals"), local: :modal_store)
+    #
+    # +local+ is REQUIRED and has no default on purpose. Fifteen of the engine's
+    # call sites name this local `modal_store` and two name it `store`; a default
+    # that is right fifteen times out of seventeen is exactly how the other two
+    # would hand a host the wrong local to go and fix.
+    #
+    # RETURNS A PLAIN STRING, NOT AN html_safe ONE, and that is load-bearing rather
+    # than an omission. A value that satisfies PATTERN contains no character ERB
+    # escapes, so ERB's pass over it is a byte-for-byte no-op and the identifier
+    # reaches the browser exactly as the host wrote it — the marking would buy
+    # nothing today. What it would cost is the day PATTERN is widened: ERB's
+    # escaping is the second layer that would still be standing, and a value marked
+    # safe here skips it. So the pattern is the only thing holding the line, and it
+    # is holding it alone by choice, in one place.
+    def validate!(value, local:)
+      name = "#{value}"
+      return name if name.match?(PATTERN)
+
+      raise ArgumentError,
+            "#{local} must be a JS identifier (it is spliced into $store.<name>); " \
+            "got #{value.inspect}. Escaping it would not help — an escaped " \
+            "identifier is a different SyntaxError, and the card would mount dead."
+    end
+  end
+end

data/lib/studio/js_literal.rb

@@ -80,8 +80,9 @@ module Studio
   # NAME — `$store.<%= modal_store %>.close()` — must be VALIDATED, never escaped:
   # escape_javascript also escapes `$`, so a legitimate store name like `dsModals$2`
   # comes back mangled and the card dies anyway. The SHAPE of the splice decides the
-  # repair, never the name of the local. studio/modals/onboarding/_first_name
-  # carries the worked example of both.
+  # repair, never the name of the local. That repair is Studio::JsIdentifier, this
+  # module's sibling and its opposite; studio/modals/onboarding/_first_name carries
+  # the worked example of both in one partial.
   module JsLiteral
     extend ActionView::Helpers::JavaScriptHelper
 

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.74.2"
+  VERSION = "0.74.3"
 end

data/lib/studio.rb

@@ -9,6 +9,7 @@ require "studio/environment_banner"
 require "studio/theme_resolver"
 require "studio/ui_primitives"
 require "studio/js_literal"
+require "studio/js_identifier"
 require "studio/sidebar_sections"
 require "studio/profile_sections"
 require "studio/profile_image"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.74.2
+  version: 0.74.3
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-08 00:00:00.000000000 Z
+date: 2026-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -568,6 +568,7 @@ files:
 - lib/studio/geo/lookup.rb
 - lib/studio/image_cache.rb
 - lib/studio/ip_locations.rb
+- lib/studio/js_identifier.rb
 - lib/studio/js_literal.rb
 - lib/studio/link_resolution.rb
 - lib/studio/link_token.rb