studio-engine 0.70.0 → 0.72.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1c217135776ee0fcd67dd4ed2e9a72f1aedf5260ac23cfc23615ab83754133a
-  data.tar.gz: 42878ae8f85ed0c911b99c940e3c5094ca7329fed4bbb727ebfa4466bba99dfb
+  metadata.gz: a53d7cde61dcf497f1dee1542d64ad82714900227b0fb0c98c31df714ab67267
+  data.tar.gz: 16d9816dde34b609d14b57f0c526f60883a79641f485775362e396cf4ac040b1
 SHA512:
-  metadata.gz: d72745a5c54559b745fc0fefe1ac1c45b3921efeccbe5769f3b1da5ceaa1e11463c317984847fc1300fb0387610c33c4f0c7504e279871630f5535db563c935e
-  data.tar.gz: 16be22a876c99c848169a2dcd551593ff4b8c377427acd9d84c04bf732847d261422c79d9b7f30397bf8b04c2d13a894999cc542a95bb1037f9deeaea0c5c32a
+  metadata.gz: 682057c50bc19db2ab91d46d54ddb730d273617c1814b61e7bedea16120187af757ea44fe554cdbf66bc8b26f8356cb40050532b3cca146f7af6c73607632b21
+  data.tar.gz: 59c7b9a8331368526b1561482cd86d117866a4e61ce2e07a499fb48a8c2eb4ecf6a588388347a3bb4c2d6973c9d599bc819c2eb4b6348212f38aaee753c20774

data/CHANGELOG.md

@@ -6,6 +6,96 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Added
 
+- **The first-name card now says WHICH path finished it, and can type its
+  placeholder.** Two adoption hooks on
+  `studio/modals/onboarding/_first_name`, aimed at turf-monster's own 240-line
+  copy of it.
+
+  **WHAT THIS DOES NOT DO.** It unblocks that adoption; it does not complete it,
+  and the copy cannot simply be deleted on this release. `required` is still
+  resolved at RENDER time, while turf drives it as a runtime prop from ONE
+  registered modal id — the post-auth chain opens that id skippable, the entry
+  gate opens the SAME id with `required: true` — so adopting still costs two
+  registered ids (pass a distinct `id:` to keep the field's DOM id unique) or a
+  runtime mode here. And the host still writes the bridge: this card touches no
+  session store and emits no `first-name-saved`, so turf's resume needs a
+  listener that does both when `saved` is true.
+
+  **THE OUTCOME (the blocker).** `finish()` is called by the save AND the skip,
+  and it dispatched the same detail either way — so a host could hear that the
+  step was done and could not hear whether a name had landed. Its `done_event`
+  detail now carries `{ next: [...], saved: true|false }`. turf's entry gate
+  resumes a contest entry the gate interrupted when the name saves; fired after
+  a SKIP that same signal resumes an entry that still has no name.
+
+  It is an extra detail key rather than an opt-in second event because
+  McRitchie Studio's listener wants BOTH paths (it retires the "ask" marker
+  whether the user answered or skipped), so the event that always fires has to
+  be the one carrying the answer — and an opt-in event would leave this one
+  ambiguous for every host that did not pass it, including the next one to add
+  a gate. `next` keeps its key and the event keeps its name, so the existing
+  listener does not move. The flag is written `!!saved`, so an unreported path
+  reports FALSE: a card claiming `saved: true` for a skip would be worse than
+  the ambiguity it replaced.
+
+  **THE TYPED PLACEHOLDER (optional, OFF by default).** A new
+  `placeholder_names:` local takes an array of first names and types one of
+  them into the placeholder a character at a time, so the card demonstrates the
+  answer instead of describing it. Absent or empty, NONE of it is emitted and
+  the static `placeholder` is used exactly as before — the local exists so
+  turf's adoption does not silently delete a flourish it has today, and it
+  comes out in one piece if the operator would rather drop it.
+
+  It carries the three things that make it bearable rather than a nuisance:
+  typing stops the moment the user types and NEVER restarts (a focus counts
+  only when it follows a blur, because the field is focused on mount);
+  `prefers-reduced-motion` gets the whole example statically, with no timer;
+  and there is a 420ms pre-roll so a short name does not finish underneath the
+  modal's own mount spring. The pool travels as an escaped `data-` attribute
+  rather than interpolated into the `x-data`, which is what keeps a name with
+  an apostrophe — or the JSON's own double quotes — from killing the component.
+
+  The default card is asserted **byte-for-byte against the 0.70.0 render**,
+  with the four outcome lines rewound and every other byte required to match;
+  a fifth change has to be added to that list deliberately. Mutation-checked
+  6/6, and the two halves redden disjoint tests: reporting `true` on the skip,
+  dropping `saved` from the detail, and renaming `next` each hit an outcome
+  test, while forcing the typed mode on, un-guarding the refocus, and treating
+  an empty pool as present each hit a placeholder test.
+
+- **The living style guide grows a HOST SECTION seam.** `/admin/style` rendered
+  four hard-coded engine sections (Theme, Modals, Tricks, Tasks) with no way for
+  a consuming app to contribute one of its own. An app now defines
+  **`app/views/style/host/_modals.html.erb`** and the guide grows a fifth
+  section for that app's own modals, between Modals and Tricks, plus its pill in
+  the sticky section nav. Found by the same three-term
+  `lookup_context.exists?("modals", ["style/host"], true)` the modal host uses
+  for `modals/_host_extras` — one convention in this codebase, not two — so
+  defining the file IS the registration: no initializer, no locals, no list to
+  append to.
+
+  **The gem keeps dictating the structure.** `style/_host.html.erb` renders the
+  section element, the `#host-modals` anchor, the heading (`Studio.app_name`),
+  the intro line and the Alpine scope; the app supplies specimens only. An app
+  that ships no such partial gets **nothing** — no pill, no heading, no
+  container — and that is asserted as a whole-document comparison rather than a
+  handful of refutes: the page an app WITH a section gets, minus that section
+  and its pill, must equal the page a base app gets. Five of the six apps
+  mounting this engine will ship no host section, and their page is unchanged.
+
+  **A host specimen drives `$store.modals`, not `dsModals`, and the distinction
+  is the whole point.** The guide's own Modals section needs a page-scoped store
+  because its specimens are the ENGINE's ids, which an app's layout host has no
+  registration for — pushing one there paints an empty card behind the specimen.
+  An app's own ids ARE registered in its layout host, so a host section opens
+  the **real** production card with no mirror, no second registration list and
+  no iframe. The doc comment on `style/_host.html.erb` is the consumer contract
+  and says so outright, because a reader who assumes `dsModals` builds that
+  mirror instead — a second copy of every card, free to drift from the one the
+  app ships, which is the opposite of what a living style guide is for.
+
+  **The seam ships no host section itself.** The first consumer is
+  turf-monster's own `style/host/_modals`, which lands as its own task.
 - **A `required` mode on the shared first-name card.**
   `studio/modals/onboarding/_first_name` grows one local. `required: true`
   renders the card with BOTH skip affordances gone — the "Skip for now" button

data/README.md

@@ -449,6 +449,48 @@ than assuming drop-in equivalence:
   the replacement lands after the 220ms slide-out (previously an immediate
   top-of-stack assignment).
 
+### Style guide — your app's own section
+
+`/admin/style` is the engine's living style guide, and every section on it is
+the engine's: Theme, Modals, Tricks, Tasks. An app grows a **fifth section, its
+own**, by defining one partial:
+
+```erb
+<%# app/views/style/host/_modals.html.erb %>
+<div class="card p-4 space-y-3">
+  <p class="label-upper">Wallet setup</p>
+  <button type="button" class="btn btn-primary btn-sm"
+          @click="$store.modals.open('wallet-setup', { returnUrl: window.location.href })">
+    Open
+  </button>
+</div>
+```
+
+That is the whole registration — the same optional-partial convention as
+`modals/_host_extras`, resolved by the same three-term `lookup_context.exists?`.
+An app that ships no such file gets no section, no heading, and no nav pill; its
+page is byte-for-byte what it was.
+
+**The gem keeps dictating the structure.** It renders the section element, the
+`#host-modals` anchor, the heading (your `Studio.app_name`), the intro line, and
+the sticky nav pill, and it places the section between Modals and Tricks. Your
+partial supplies specimens only — no `<section>`, no `<h2>`, nothing to register
+in a nav.
+
+**Drive `$store.modals`, not `dsModals`.** The guide's own Modals section stands
+up a page-scoped store because its specimens are the *engine's* ids, and pushing
+an id your layout host has never registered opens that host onto an empty card.
+Your own ids are already registered there, so
+`$store.modals.open(id, props)` renders the **real** card, in production chrome,
+with production behavior. There is nothing to mirror and no second registration
+list to keep in sync — building one is the mistake this note exists to prevent.
+This assumes your layout mounts the shared host. Not every consuming app does
+(see "Page-scoped hosts" above); where none is mounted `$store.modals` is
+undefined, so mount `studio/modals/host` before writing a trigger.
+
+Full contract, including what the partial may assume: the doc comment at the top
+of `app/views/style/_host.html.erb`.
+
 ### User nav slots
 
 `components/_user_nav.html.erb` renders the right-side navbar user section.

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

@@ -25,6 +25,18 @@
                   talking to a different audience — a host that passes its own
                   subtext still wins)
     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
+                  time, so the card demonstrates the answer instead of
+                  describing it. Absent (or empty) NONE of it is emitted and the
+                  static `placeholder` above is used exactly as before. Passed,
+                  `placeholder` goes unused: the field carries no static
+                  placeholder, because a value Alpine blanks a moment after
+                  paint reads as a flicker rather than a hint. Honours
+                  prefers-reduced-motion by showing the whole example
+                  statically, with no timer. The typing stops FOR GOOD the
+                  moment the user types — it never restarts, not even when they
+                  leave the field and come back.
     max_length  — (default Studio::FULL_NAME_MAX_LENGTH; the server stays the
                   real bound, and it REFUSES past that rather than truncating,
                   so a host raising this makes the endpoint answer 422 rather
@@ -32,10 +44,25 @@
     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").
+    done_event  — window event dispatched when this step is finished, saved or
+                  skipped (default "onboarding-step-done"). Its detail carries
+                  `{ next: [...], saved: true|false }` — see THE OUTCOME below.
                   The HOST decides what happens next; this partial never knows.
 
+  THE OUTCOME RIDES THE DETAIL, NOT A SECOND EVENT. `saved` says which path
+  finished the step, because to a host the two are not interchangeable:
+  turf-monster's entry gate resumes a contest entry the gate interrupted once
+  the name lands, and resuming after a SKIP resumes an entry that still has no
+  name. It is an extra detail key rather than an opt-in `saved_event` local for
+  two reasons. McRitchie Studio's listener wants BOTH paths — it retires the
+  "ask" marker whether the user answered or skipped — so the event that always
+  fires has to be the one carrying the answer, and a second event would leave
+  this one ambiguous for every host that did not opt in, including the next one
+  to add a gate. `next` keeps its key and its meaning, so an existing listener
+  does not move. And the flag is written `!!saved`: an unreported path reports
+  FALSE, because a card that claimed `saved: true` for a skip would be worse
+  than the ambiguity it replaced.
+
   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
@@ -59,6 +86,12 @@
                     end
   subtext     = local_assigns.fetch(:subtext, default_subtext)
   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
+  # whole typing machine for a pool it can never sample from.
+  placeholder_names = local_assigns.fetch(:placeholder_names, nil)
+  placeholder_names = nil if placeholder_names.nil? || placeholder_names.empty?
+  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")
@@ -77,6 +110,68 @@
        firstName: '',
        submitting: false,
        error: '',
+<% if typed_placeholder %>
+       // --- the typed placeholder (opt-in: placeholder_names) ---------------
+       // Types ONE sampled name into the field's PLACEHOLDER, character by
+       // character. The field itself stays genuinely empty — nothing is ever
+       // submitted that the user did not type.
+       //
+       // NO fake caret. A blinking block after the text is the obvious way to
+       // sell a typewriter and it is wrong here: the field is focused on mount,
+       // so the browser is already drawing a real caret at position 0, and a
+       // second one two characters away reads as a rendering bug.
+       placeholderText: '',
+       _phPhrase: '',
+       _phTimer: null,
+       _phDelay: null,
+       _phBlurred: false,
+       startPlaceholder(names) {
+         if (!names || !names.length) return;
+         this._phPhrase = names[Math.floor(Math.random() * names.length)];
+         // Reduced motion: show the whole example, statically, no timer. The
+         // hint is the point; the animation is decoration.
+         if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+           this.placeholderText = this._phPhrase;
+           return;
+         }
+         var self = this, i = 0;
+         this.placeholderText = '';
+         // WAIT FOR THE CARD TO LAND. The modal mounts with a 320ms spring and
+         // x-init fires at the START of it, so typing that begins immediately
+         // runs entirely underneath the entrance. A SHORT name is the common
+         // case and the worst one: a two-letter name finishes before the card
+         // has finished appearing, so the field simply arrives with a name
+         // already in it and the effect is invisible.
+         this._phDelay = setTimeout(function () {
+           self._phDelay = null;
+           self._phTimer = setInterval(function () {
+             i += 1;
+             self.placeholderText = self._phPhrase.slice(0, i);
+             if (i >= self._phPhrase.length) self.stopPlaceholder();
+           }, 110);
+         }, 420);
+       },
+       // Stop the timer, leaving whatever is on screen. Also kills the pre-roll,
+       // or dismissing DURING the delay lets the animation start after the user
+       // has already begun typing.
+       stopPlaceholder() {
+         if (this._phTimer) { clearInterval(this._phTimer); this._phTimer = null; }
+         if (this._phDelay) { clearTimeout(this._phDelay); this._phDelay = null; }
+       },
+       // The user is writing their own name — get out of the way. Clearing
+       // rather than completing is deliberate: a half-typed name frozen under
+       // their cursor looks broken. Nothing restarts it afterwards.
+       dismissPlaceholder() {
+         this.stopPlaceholder();
+         this.placeholderText = '';
+       },
+       // The mount focus is NOT engagement. This card focuses the field the
+       // moment it mounts, so treating ANY focus as the user choosing the field
+       // would kill the animation before it drew a character. Only a focus that
+       // FOLLOWS a blur is the user deliberately coming back.
+       markPlaceholderBlurred() { this._phBlurred = true; },
+       refocusPlaceholder() { if (this._phBlurred) this.dismissPlaceholder(); },
+<% end %>
        async save() {
          if (this.submitting) return;
          var value = (this.firstName || '').trim();
@@ -88,14 +183,14 @@
            this.error = (data && data.error) || 'Could not save that — try again.';
            return;
          }
-         this.finish(data.next || []);
+         this.finish(data.next || [], true);
        },
        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) || []);
+         this.finish((data && data.next) || [], false);
        },
        async post(url, body) {
          var meta = document.querySelector('meta[name=csrf-token]');
@@ -112,11 +207,18 @@
            return await res.json();
          } catch (e) { return null; }
        },
-       finish(next) {
-         window.dispatchEvent(new CustomEvent('<%= done_event %>', { detail: { next: next } }));
+       finish(next, saved) {
+<% if typed_placeholder %>
+         this.stopPlaceholder();
+<% end %>
+         window.dispatchEvent(new CustomEvent('<%= done_event %>', { detail: { next: next, saved: !!saved } }));
          $store.<%= modal_store %>.close();
        }
      }"
+<% if typed_placeholder %>
+     data-placeholder-names="<%= placeholder_names.to_json %>"
+     x-init="startPlaceholder(JSON.parse($el.dataset.placeholderNames || '[]'))"
+<% end %>
      class="relative">
 
   <div class="relative mb-3 -mt-2">
@@ -144,9 +246,22 @@
       <%# 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. %>
+      <%# The placeholder is STATIC unless the host passed placeholder_names, in
+          which case it is bound and typed. The three extra handlers are the
+          difference between a hint and a nuisance: real typing dismisses it, a
+          blur is recorded, and a focus AFTER that blur — the user deliberately
+          returning — dismisses it too. A bare focus must not, because the
+          x-init on this input fires one immediately. %>
       <input id="<%= field_id %>" type="text" x-model="firstName"
              maxlength="<%= max_length %>" autocomplete="given-name" enterkeyhint="done"
+<% if typed_placeholder %>
+             :placeholder="placeholderText"
+             @input="dismissPlaceholder()"
+             @blur="markPlaceholderBlurred()"
+             @focus="refocusPlaceholder()"
+<% else %>
              placeholder="<%= placeholder %>"
+<% end %>
              :disabled="submitting"
              x-init="$nextTick(() => $el.focus({ preventScroll: true }))"
              class="input-field">

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

@@ -0,0 +1,111 @@
+<%#  The HOST section of the living style guide (admin/style).
+
+     THE ONE SEAM a consuming app has for growing its own specimens onto this
+     page. Every other section on this page is the gem's. This one is the app's,
+     and the gem still dictates its structure: the section element, the anchor,
+     the heading, the intro line, and the nav pill above are all rendered HERE,
+     from the engine. The app supplies content only.
+
+     "Host" means the CONSUMING APP, the same sense it carries in the modal
+     host's own seam (modals/_host_extras). It does NOT mean the modal-host
+     shell, which is studio/modals/_host - a different file and a different
+     meaning of the word.
+
+
+     THE CONTRACT - what a consuming app writes
+     ------------------------------------------
+     Define ONE partial in the app:
+
+         app/views/style/host/_modals.html.erb
+
+     That is the whole registration. There is no initializer, no locals, no
+     list to append to, and nothing to render from the app's own layout. The
+     guide finds the partial by CONVENTION, exactly the way the modal host
+     finds modals/_host_extras:
+
+         lookup_context.exists?("modals", ["style/host"], true)
+
+     - the same three-term form: name, prefixes, partial. That call lives in
+     style/index.html.erb, which owns it because the sticky section nav needs
+     the same answer the render does. An app that ships no such partial gets no
+     pill, no heading, no container, and no bytes: the guide is unchanged.
+
+     WHY THIS PATH. A directory (style/host/) rather than a flat name in the
+     gem's own style/ prefix, because the gem already ships style/_modals,
+     style/_theme, style/_tricks and style/_tasks - an app file dropped beside
+     them shadows a section by name, and the failure is silent. Nothing of the
+     gem's lives under style/host/, so an app cannot collide with the engine
+     there. Naming the partial for the SECTION it contributes (modals) rather
+     than for the seam leaves room for a later style/host/_tricks without
+     renaming what is already shipped.
+
+
+     WHAT THE PARTIAL MAY ASSUME
+     ---------------------------
+     - It renders INSIDE this section element, already anchored, spaced and
+       headed. So it supplies cards and prose only: no section tag of its own,
+       no h2, no scroll-margin, no nav entry.
+     - The engine component layer (engine.css) and motion layer
+       (engine-motion.css) are loaded, so card, btn, badge, label-upper, the
+       role tokens and the motion/effect primitives all style for real.
+     - Alpine is running and this section carries an x-data scope, so a
+       specimen can use x-on / at-click bindings directly. A plain onclick
+       calling Alpine.store works too.
+     - NOT that a shared modal host exists. Only an app whose layout renders
+       studio/modals/host has Alpine.store("modals") at all: mcritchie-studio
+       and turf-monster mount it; acquisition-studio, mcritchie-industries and
+       moms-app render none (the same split README's "Page-scoped hosts" and
+       studio/emails/index.html.erb already name). On an app with no shared
+       host $store.modals is UNDEFINED and a trigger throws on click, so mount
+       studio/modals/host in the layout first - or give the page its own host
+       with studio/modals/scoped_host and drive that instead.
+
+
+     WHICH STORE IT DRIVES - read this before writing a trigger
+     ----------------------------------------------------------
+     Drive the app's REAL store:
+
+         $store.modals.open(id, props)
+
+     NOT dsModals. dsModals is the page-scoped host that the gem's own Modals
+     section above stands up, and copying it here is the one wrong turn this
+     seam invites.
+
+     The gem's section needs dsModals for a reason that does NOT apply to an
+     app's own modals. Its specimens are the ENGINE's ids, and an app's layout
+     host registers only that app's ids under an unconditional template x-if on
+     the current modal. Pushing a NOVEL id onto the app's store would open that
+     host onto a card it has no registration for, painting an EMPTY panel behind
+     the specimen. So the gem's section owns a private store and registers all
+     of its specimen content itself.
+
+     An app's own modal ids are already registered in that app's layout host.
+     Push one onto $store.modals and the real host renders the real card - the
+     production card, in production chrome, with production behaviour. There is
+     nothing to mirror, no second registration list to keep in sync, and no
+     iframe. Turf Monster's /admin/modals gallery has driven the real store from
+     a plain button this way since it was built; this seam is that same move,
+     given a home on the guide.
+
+     A reader who assumes dsModals will build a mirror instead: a second copy of
+     every card, free to drift from the one the app actually ships, which is the
+     opposite of what a living style guide is for. %>
+<section id="host-modals" class="space-y-8" x-data="{}"
+         style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
+  <div class="space-y-1">
+    <h2 class="text-2xl font-bold text-heading"><%= Studio.app_name %></h2>
+    <p class="text-muted text-sm max-w-2xl">
+      This app&rsquo;s own modals, contributed by
+      <code class="font-mono text-2xs bg-inset px-1.5 py-0.5 rounded">app/views/style/host/_modals.html.erb</code>.
+      Every section above belongs to the engine and is inherited; everything
+      here belongs to <%= Studio.app_name %> and ships with it. These specimens
+      drive the app&rsquo;s <strong>real</strong>
+      <code class="font-mono text-2xs bg-inset px-1.5 py-0.5 rounded">$store.modals</code>
+      host, so the card that opens here is the card that opens in production.
+    </p>
+  </div>
+
+  <%# The app's content. Reached only when it resolves - style/index.html.erb
+      owns that guard, because the section nav needs the same answer. %>
+  <%= render "style/host/modals" %>
+</section>

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

@@ -3,22 +3,48 @@
      application.html.erb, inheriting that app's navbar and theme, so every
      specimen restyles per app and in dark or light automatically.
 
-     Four sections, reached by the sticky section nav below and rendered as
-     sibling partials: Theme is the landing section (the color foundation - it
+     Four ENGINE sections, reached by the sticky section nav below and rendered
+     as sibling partials: Theme is the landing section (the color foundation - it
      owns the role tokens/swatches, the folded-in /admin/theme editor, and the
      live preview), then Modals (the shared host + engine card blocks), Tricks
      (the button/surface/motion/effect/leveling primitives, framed as a board of
      copy-paste-for-an-agent snippets), and Tasks (the shared board primitive).
 
+     A FIFTH section is the host app's own, and appears only on an app that asks
+     for it: define app/views/style/host/_modals.html.erb in the consuming app
+     and the guide grows a section (and a nav pill) for that app's own modals,
+     between Modals and Tricks. The gem still renders the section chrome; the app
+     supplies the specimens. Full contract, including which modal store a host
+     specimen drives and why it is not the one the Modals section uses:
+     app/views/style/_host.html.erb.
+
      Specimens use ONLY the engine's own classes (engine.css component layer plus
      engine-motion.css motion/effect/leveling layer), so a consumer that bundles
      engine.css and imports engine-motion.css styles them for real. The primitive
      CSS is NOT inlined here - the consumer's Tailwind build provides it. Page
      chrome uses the engine's own .card / .label-upper / theme tokens. %>
 <%
+  # THE HOST SECTION SEAM. A consuming app grows its OWN modal specimens onto
+  # this page by defining app/views/style/host/_modals.html.erb. Found by the
+  # same three-term lookup_context.exists?(name, prefixes, partial) the modal
+  # host uses for modals/_host_extras (studio/modals/_host.html.erb) - one
+  # convention in this codebase, not two.
+  #
+  # Resolved ONCE, here, because two places need the same answer: the sticky
+  # section nav below and the render further down. An app that ships no such
+  # partial gets no pill, no heading and no container - the page is what it was.
+  # The section chrome and the consumer contract live in style/_host.html.erb.
+  host_modals = lookup_context.exists?("modals", ["style/host"], true)
+
   sections = [
     ["theme",  "Theme"],
-    ["modals", "Modals"],
+    ["modals", "Modals"]
+  ]
+  # Adjacent to Modals, not appended: this page groups by SUBJECT, and a host's
+  # own modals are the same subject as the engine's. Labelled with the app's own
+  # name, so the pill says whose section it is.
+  sections << ["host-modals", Studio.app_name] if host_modals
+  sections += [
     ["tricks", "Tricks"],
     ["tasks",  "Tasks"]
   ]
@@ -54,6 +80,9 @@
   <div class="space-y-16 pt-10">
     <%= render "style/theme" %>
     <%= render "style/modals" %>
+    <% if host_modals %>
+      <%= render "style/host" %>
+    <% end %>
     <%= render "style/tricks" %>
     <%= render "style/tasks" %>
   </div>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.70.0"
+  VERSION = "0.72.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.70.0
+  version: 0.72.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -509,6 +509,7 @@ files:
 - app/views/studio/profiles/_save_controls.html.erb
 - app/views/studio/profiles/edit.html.erb
 - app/views/studio/profiles/show.html.erb
+- app/views/style/_host.html.erb
 - app/views/style/_modal_specimen.html.erb
 - app/views/style/_modals.html.erb
 - app/views/style/_specimen.html.erb