studio-engine 0.127.0 → 0.129.0

data/lib/studio/icons/lucide/log-out.svg

@@ -0,0 +1,17 @@
+<!-- @license lucide-static v1.68.0 - ISC -->
+<svg
+  class="lucide lucide-log-out"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="m16 17 5-5-5-5" />
+  <path d="M21 12H9" />
+  <path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4" />
+</svg>

data/lib/studio/icons/lucide/message-circle.svg

@@ -0,0 +1,15 @@
+<!-- @license lucide-static v1.68.0 - ISC -->
+<svg
+  class="lucide lucide-message-circle"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M2.992 16.342a2 2 0 0 1 .094 1.167l-1.065 3.29a1 1 0 0 0 1.236 1.168l3.413-.998a2 2 0 0 1 1.099.092 10 10 0 1 0-4.777-4.719" />
+</svg>

data/lib/studio/icons/lucide/package.svg

@@ -0,0 +1,18 @@
+<!-- @license lucide-static v1.68.0 - ISC -->
+<svg
+  class="lucide lucide-package"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M11 21.73a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73z" />
+  <path d="M12 22V12" />
+  <polyline points="3.29 7 12 12 20.71 7" />
+  <path d="m7.5 4.27 9 5.15" />
+</svg>

data/lib/studio/icons/lucide/palette.svg

@@ -0,0 +1,19 @@
+<!-- @license lucide-static v1.68.0 - ISC -->
+<svg
+  class="lucide lucide-palette"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M12 22a1 1 0 0 1 0-20 10 9 0 0 1 10 9 5 5 0 0 1-5 5h-2.25a1.75 1.75 0 0 0-1.4 2.8l.3.4a1.75 1.75 0 0 1-1.4 2.8z" />
+  <circle cx="13.5" cy="6.5" r=".5" fill="currentColor" />
+  <circle cx="17.5" cy="10.5" r=".5" fill="currentColor" />
+  <circle cx="6.5" cy="12.5" r=".5" fill="currentColor" />
+  <circle cx="8.5" cy="7.5" r=".5" fill="currentColor" />
+</svg>

data/lib/studio/icons/lucide/plug.svg

@@ -0,0 +1,18 @@
+<!-- @license lucide-static v1.68.0 - ISC -->
+<svg
+  class="lucide lucide-plug"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M12 22v-5" />
+  <path d="M15 8V2" />
+  <path d="M17 8a1 1 0 0 1 1 1v4a4 4 0 0 1-4 4h-4a4 4 0 0 1-4-4V9a1 1 0 0 1 1-1z" />
+  <path d="M9 8V2" />
+</svg>

data/lib/studio/icons/lucide/rocket.svg

@@ -0,0 +1,18 @@
+<!-- @license lucide-static v1.68.0 - ISC -->
+<svg
+  class="lucide lucide-rocket"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M12 15v5s3.03-.55 4-2c1.08-1.62 0-5 0-5" />
+  <path d="M4.5 16.5c-1.5 1.26-2 5-2 5s3.74-.5 5-2c.71-.84.7-2.13-.09-2.91a2.18 2.18 0 0 0-2.91-.09" />
+  <path d="M9 12a22 22 0 0 1 2-3.95A12.88 12.88 0 0 1 22 2c0 2.72-.78 7.5-6 11a22.4 22.4 0 0 1-4 2z" />
+  <path d="M9 12H4s.55-3.03 2-4c1.62-1.08 5 .05 5 .05" />
+</svg>

data/lib/studio/icons/lucide/user.svg

@@ -0,0 +1,16 @@
+<!-- @license lucide-static v1.68.0 - ISC -->
+<svg
+  class="lucide lucide-user"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2" />
+  <circle cx="12" cy="7" r="4" />
+</svg>

data/lib/studio/icons.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "erb"
+
+# The engine's one line-icon set: Lucide, vendored under lib/studio/icons/lucide (see the
+# README beside it for the license and how to add one). Pure Ruby, so the unit suite reads
+# it without booting the dummy app. Views call StudioIconHelper#studio_icon.
+#
+# A NAME IS LOOKED UP, NEVER BUILT INTO A PATH. Only a name in the directory listing
+# reaches File.read, so a host passing a bad name gets nil and cannot read another file.
+module Studio
+  module Icons
+    DIR = File.expand_path("icons/lucide", __dir__)
+    # Lucide draws at 2 on a 24 box. At 18px that reads heavy beside 13.5px text, so the
+    # set renders thinner, as the sidebar's approved mockup did (2 x 18/24 is 1.5).
+    STROKE_WIDTH = 1.6
+
+    module_function
+
+    def names
+      @names ||= Dir.children(DIR).filter_map { |file| file.delete_suffix(".svg") if file.end_with?(".svg") }.sort.freeze
+    end
+
+    def known?(name)
+      names.include?(name.to_s)
+    end
+
+    # The whole <svg>, or nil for a name the set does not hold. Decorative: the row or
+    # button beside it carries the words.
+    def svg(name, size: 18, css_class: nil)
+      return nil unless known?(name)
+
+      px = Integer(size)
+      attributes = [
+        %(xmlns="http://www.w3.org/2000/svg"),
+        %(width="#{px}" height="#{px}"),
+        %(viewBox="0 0 24 24"),
+        %(fill="none" stroke="currentColor" stroke-width="#{STROKE_WIDTH}"),
+        %(stroke-linecap="round" stroke-linejoin="round"),
+        %(aria-hidden="true" focusable="false"),
+        (%(class="#{ERB::Util.html_escape(css_class)}") if css_class.to_s != "")
+      ].compact.join(" ")
+      "<svg #{attributes}>#{shapes(name.to_s)}</svg>"
+    end
+
+    # The drawing inside the file's <svg>, read once per name.
+    def shapes(name)
+      @shapes ||= {}
+      @shapes[name] ||= File.read(File.join(DIR, "#{name}.svg"))[%r{<svg[^>]*>(.*)</svg>}m, 1].to_s.gsub(/\s*\n\s*/, "").freeze
+    end
+  end
+end

data/lib/studio/loader.rb

@@ -27,6 +27,13 @@ module Studio
   module Loader
     class InvalidConfig < ArgumentError; end
 
+    # The one pace of a page load, for every app (docs/LOADER.md). A visit under the delay
+    # shows no overlay and waits for nothing. An overlay that shows stays the minimum.
+    # studio/loader falls back to the same two numbers; test/views/loader_render_test.rb
+    # holds them level.
+    OVERLAY_DELAY_MS = 350
+    OVERLAY_MIN_SHOW_MS = 750
+
     SETTING = "Studio.loader"
     GENERIC_STYLES = %i[breathe liquid orbit steel].freeze
     ART_STYLES = { weld_bead: "outline", sparkle: "spark" }.freeze

data/lib/studio/sidebar_sections.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "uri"
+
 # Resolves Studio.sidebar_sections — the host's declared link-sidebar data —
 # for a given view context. Pure Ruby (no Rails dependency) so the unit suite
 # exercises the resolution rules without booting the dummy app.
@@ -8,7 +10,7 @@
 # context) for dynamic data: route helpers, logged_in? walls, model-backed
 # link lists. Each section normalizes to symbol keys:
 #
-#   { title: "Site", admin: true, links: [
+#   { title: "Site", admin: true, header: true, links: [
 #     { label: "Dashboard", href: "/admin", emoji: "📊",
 #       hover_emoji: "🔬", desc: "Users + logs", target: "_blank" } ] }
 #
@@ -16,8 +18,13 @@
 # trigger and panel stay invisible to everyone else even when the host
 # declares nothing but admin links.
 #
-# A section's title is its group's accessible name; the panel shows no label word. A
-# link's desc is optional and shows only on hover or keyboard focus.
+# A section's title is its group's accessible name. By default the panel shows no label
+# word; a section with header: true also shows its title above its rows. A link's desc is
+# optional and shows only on hover or keyboard focus.
+#
+# Under Studio.sidebar_style = :glass a link may also carry icon: "rocket", a Studio::Icons
+# name: the row draws that line icon in place of its emoji, with no hover swap. The emoji
+# stays the fallback for a name the set does not hold.
 #
 # THE ENGINE PREPENDS ONE SECTION OF ITS OWN — "You", linking to /profile. The
 # engine ships that page, so it ships the way in rather than asking five apps to
@@ -25,8 +32,49 @@
 # gates it carries.
 module Studio
   module SidebarSections
+    STYLES = %i[default glass].freeze
+
     module_function
 
+    # The value Studio.sidebar_style= stores, or ArgumentError. A misspelt style would
+    # otherwise draw the default panel with no word about why.
+    def style!(value)
+      style = value.respond_to?(:to_sym) ? value.to_sym : value
+      return style if STYLES.include?(style)
+
+      raise ArgumentError, "Studio.sidebar_style must be one of #{STYLES.join(', ')}, got #{value.inspect}"
+    end
+
+    # The href of the row for the page at `path`, or nil. One row at most: the longest
+    # match wins, so /build/requests lights App Requests and not Build. A row also owns
+    # the pages beneath it (/books/2026 lights Books). "/" only ever matches itself. An absolute href counts only on `host`, so a satellite's /docs
+    # never lights here.
+    def current_href(sections, path, host: nil)
+      return nil if path.to_s.empty?
+
+      here = path.to_s[/\A[^?#]*/].chomp("/")
+      best = Array(sections).flat_map { |section| Array(section[:links]) }.filter_map do |link|
+        target = link_path(link[:href], host)
+        next if target.nil?
+        next unless target == here || (!target.empty? && here.start_with?("#{target}/"))
+
+        [target.length, link[:href]]
+      end.max_by(&:first)
+      best&.last
+    end
+
+    # An href's local path without its trailing slash, or nil when it leads elsewhere or
+    # to nothing here (another host, a bare #anchor, a mailto:).
+    def link_path(href, host)
+      uri = URI.parse(href.to_s)
+      return nil if uri.path.to_s.empty? || uri.opaque
+      return nil if uri.host && uri.host != host
+
+      uri.path.chomp("/")
+    rescue URI::Error
+      nil
+    end
+
     def resolve(declared, view)
       sections = declared.respond_to?(:call) ? declared.call(view) : declared
       admin = view.respond_to?(:admin?) && view.admin?
@@ -60,7 +108,7 @@ module Studio
       return [] unless profile_link?(view)
 
       [{ title: "You", links: [
-        { label: "Profile", href: view.profile_path, emoji: "👤" }
+        { label: "Profile", href: view.profile_path, emoji: "👤", icon: "user" }
       ] }]
     end
 

data/lib/studio/site_footer.rb

@@ -386,15 +386,36 @@ module Studio
     # means the app has no chat, and `allowed` (a callable taking the viewer, nil
     # when signed out) can hide it, e.g. admins only while testing. A hook that
     # raises hides the entry and logs; the footer is on every page, and a link
-    # meant for a few must not show because its gate broke.
+    # meant for a few must not show because its gate broke. So does a path that
+    # raises: without the path there is no link, and the page still renders.
     def chat_row(view, path:, label: nil, allowed: nil)
-      href = path.respond_to?(:call) ? path.call(view) : path
+      href = chat_href(view, path)
       return nil if text(href).nil?
       return nil unless chat_allowed?(view, allowed)
 
       [text(label) || "Chat", href]
     end
 
+    def chat_href(view, path)
+      path.respond_to?(:call) ? path.call(view) : path
+    rescue StandardError => error
+      SiteFooter.reporter.call("[studio.site_footer] site_footer_chat_path raised #{error.class}: the Chat link is hidden")
+      capture_once(error)
+      nil
+    end
+
+    # ErrorLog is a row per call, and the footer is on every page: one per error class.
+    def capture_once(error)
+      key = "site_footer_chat_path #{error.class}"
+      return if SiteFooter.reported.key?(key) || SiteFooter.reported.size >= REPORTED_LIMIT
+      return unless defined?(::ErrorLog) && ::ErrorLog.respond_to?(:capture!)
+
+      SiteFooter.reported[key] = true
+      ::ErrorLog.capture!(error)
+    rescue StandardError
+      nil # reporting is best-effort: the footer still renders
+    end
+
     def chat_allowed?(view, allowed)
       return true if allowed.nil?
 

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.127.0"
+  VERSION = "0.129.0"
 end

data/lib/studio.rb

@@ -33,6 +33,7 @@ require "studio/js_identifier"
 require "studio/hold_button"
 require "studio/partial_block"
 require "studio/sidebar_sections"
+require "studio/icons"
 require "studio/site_footer"
 require "studio/marketing_kit"
 require "studio/booking"
@@ -177,6 +178,22 @@ module Studio
     @@page_transition_direction = direction
   end
 
+  # One of :slide or :unfold. The ONE style this app's pages play, on every page change and
+  # every full load. Alex McRitchie's ruling, 2026-11-04: one app, one way, nothing random. The
+  # default is :slide, the plainer of the two, so a host that sets only a direction gets one
+  # steady move and never a draw. It does nothing without a direction, and nil means the default.
+  PAGE_TRANSITION_STYLES = %i[slide unfold].freeze
+  mattr_reader :page_transition_style, default: :slide
+
+  def self.page_transition_style=(value)
+    style = value.presence&.to_sym || :slide
+    unless PAGE_TRANSITION_STYLES.include?(style)
+      raise ArgumentError, "Studio.page_transition_style must be one of " \
+                           "#{PAGE_TRANSITION_STYLES.join(', ')} (got #{value.inspect})"
+    end
+    @@page_transition_style = style
+  end
+
   # Minimum ms the nav spinner stays visible once shown (_head.html.erb).
   # Apps wrapping multi-second operations in the spinner (e.g. Solana RPC)
   # keep the high default to avoid flicker; smooth-load apps typically drop
@@ -259,6 +276,37 @@ module Studio
   #   end
   mattr_accessor :sidebar_sections, default: []
 
+  # Whether the link sidebar draws its own Geo row for an admin. Default true. False
+  # takes the row out of this panel only: components/_geo_signpost stays, so a host
+  # that moves Geo elsewhere renders the partial on that page.
+  mattr_accessor :sidebar_geo_signpost, default: true
+
+  # How the link sidebar's panel looks. :default is the full-height drawer every app has
+  # today. :glass floats an inset, translucent panel over the page, with line icons
+  # (a link's icon:), a marked current page and no separate blurred edge. It is opt-in,
+  # so an app moves only when it asks. engine.css, THE GLASS SIDEBAR, holds the look.
+  mattr_reader :sidebar_style, default: :default
+
+  def self.sidebar_style=(value)
+    @@sidebar_style = SidebarSections.style!(value)
+  end
+
+  # ---- Surfaces ----
+  # How cards look. :glass makes them translucent over a soft ambient page, once the host
+  # layout says so on its root: <html data-surface-style="<%= Studio.surface_style %>">.
+  # :default is what every app has today. engine.css, THE GLASS SURFACES, holds the look.
+  SURFACE_STYLES = %i[default glass].freeze
+  mattr_reader :surface_style, default: :default
+
+  def self.surface_style=(value)
+    style = value.respond_to?(:to_sym) ? value.to_sym : value
+    unless SURFACE_STYLES.include?(style)
+      raise ArgumentError, "Studio.surface_style must be one of #{SURFACE_STYLES.join(', ')}, got #{value.inspect}"
+    end
+
+    @@surface_style = style
+  end
+
   # ---- Navbar links ----
   # Links for the engine navbar's desktop bar and phone row. The default []
   # renders nothing, so the navbar stays byte-identical until an app opts in.
@@ -338,6 +386,10 @@ module Studio
   #                     art: "/brand/loader-sparkle.svg" }
   mattr_reader :loader, default: Loader.normalize(nil)
 
+  # The page-load overlay reaches every page through layouts/studio/_head, at the one
+  # standard pace in Studio::Loader. false opts this app out. docs/LOADER.md.
+  mattr_accessor :loader_overlay, default: true
+
   def self.loader=(config)
     @@loader = Loader.normalize(config)
   end
@@ -1802,8 +1854,8 @@ module Studio
   #   config.site_footer_chat_label = "Chat"       # the default
   #   config.site_footer_chat_allowed = ->(user) { user&.admin? }  # default: Studio.agent_chat_allowed
   #
-  # site_footer_chat_allowed takes the viewer, nil when signed out; a hook that
-  # raises hides the entry and logs (SiteFooter.chat_row). Unset, the link follows
+  # site_footer_chat_allowed takes the viewer, nil when signed out; a path or a hook
+  # that raises hides the entry and logs (SiteFooter.chat_row). Unset, the link follows
   # Studio.agent_chat_allowed, so the link shows to whom the chat answers.
   mattr_accessor :site_footer_chat_path, default: nil
   mattr_accessor :site_footer_chat_label, default: "Chat"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.127.0
+  version: 0.129.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -489,6 +489,7 @@ files:
 - app/helpers/studio/public_user_helper.rb
 - app/helpers/studio/site_footer_helper.rb
 - app/helpers/studio_email_delivery_helper.rb
+- app/helpers/studio_icon_helper.rb
 - app/helpers/studio_navbar_helper.rb
 - app/helpers/studio_sidebar_helper.rb
 - app/helpers/studio_theme_helper.rb
@@ -790,6 +791,7 @@ files:
 - app/views/studio/voice/_recorder.html.erb
 - app/views/studio/voice/_styles.html.erb
 - app/views/style/_components.html.erb
+- app/views/style/_glass.html.erb
 - app/views/style/_host.html.erb
 - app/views/style/_modal_specimen.html.erb
 - app/views/style/_modals.html.erb
@@ -799,6 +801,7 @@ files:
 - app/views/style/_tasks.html.erb
 - app/views/style/_theme.html.erb
 - app/views/style/_tricks.html.erb
+- app/views/style/_type_ladder.html.erb
 - app/views/style/board/_demo_card.html.erb
 - app/views/style/index.html.erb
 - app/views/style/modals/_age_gate.html.erb
@@ -864,6 +867,26 @@ files:
 - lib/studio/health_report.rb
 - lib/studio/hold_button.rb
 - lib/studio/host_schema.rb
+- lib/studio/icons.rb
+- lib/studio/icons/README.md
+- lib/studio/icons/lucide/LICENSE
+- lib/studio/icons/lucide/activity.svg
+- lib/studio/icons/lucide/book-open.svg
+- lib/studio/icons/lucide/chart-column.svg
+- lib/studio/icons/lucide/diamond.svg
+- lib/studio/icons/lucide/door-stairwell.svg
+- lib/studio/icons/lucide/globe.svg
+- lib/studio/icons/lucide/hammer.svg
+- lib/studio/icons/lucide/inbox.svg
+- lib/studio/icons/lucide/key-round.svg
+- lib/studio/icons/lucide/layout-grid.svg
+- lib/studio/icons/lucide/log-out.svg
+- lib/studio/icons/lucide/message-circle.svg
+- lib/studio/icons/lucide/package.svg
+- lib/studio/icons/lucide/palette.svg
+- lib/studio/icons/lucide/plug.svg
+- lib/studio/icons/lucide/rocket.svg
+- lib/studio/icons/lucide/user.svg
 - lib/studio/image_cache.rb
 - lib/studio/ip_locations.rb
 - lib/studio/js_identifier.rb