stream_weaver 0.3.0

data/lib/stream_weaver/css.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  # Shared CSS for StreamWeaver themes and components
+  # Used by both AppView (standalone) and live session pages
+  module CSS
+    # Every framework-emitted style block (master theme, theme presets/
+    # overrides, component inject_*_css) is wrapped in this single named
+    # layer so any unlayered user stylesheet -- regardless of selector
+    # specificity or document order -- always wins the cascade
+    # (stream_weaver-oeo). User-authored CSS (App.new stylesheets:, and the
+    # `css`/`css_path` class macros a custom Component subclass can declare
+    # for itself) is deliberately left unlayered.
+    LAYER_NAME = "stream-weaver"
+
+    class << self
+      # Wraps framework CSS in the shared @layer so user CSS always wins
+      # the cascade regardless of specificity or document order.
+      # @param css [String] framework-emitted CSS
+      # @return [String] the CSS wrapped in `@layer stream-weaver { ... }`
+      def layer_wrap(css)
+        return css if css.nil? || css.strip.empty?
+
+        "@layer #{LAYER_NAME} {\n#{css}\n}"
+      end
+      # Returns the full StreamWeaver CSS (themes + components)
+      # @return [String] CSS content
+      def full_stylesheet
+        @full_stylesheet ||= begin
+          # Read from views.rb and extract the CSS heredoc
+          views_path = File.expand_path('views.rb', __dir__)
+          content = File.read(views_path)
+          
+          # Extract CSS between the heredoc markers
+          # Pattern: raw(safe(<<~CSS)) ... CSS
+          if content =~ /raw\(safe\(<<~CSS\)\)(.*?)^\s*CSS$/m
+            # Remove the 16-space indentation from the original
+            $1.gsub(/^                /, '')
+          else
+            # Fallback: return minimal CSS
+            minimal_css
+          end
+        end
+      end
+
+      # The framework stylesheet, or the best available substitute.
+      #
+      # full_stylesheet reads views.rb off disk. A compiled Opal bundle has no
+      # disk to read it from, so callers that run in both hosts -- notably the
+      # DOM-free render-to-string path -- ask for this instead and get the
+      # minimal token set rather than an exception when the file is out of
+      # reach.
+      # @return [String] CSS content
+      def base_stylesheet
+        full_stylesheet
+      rescue StandardError, NotImplementedError
+        minimal_css
+      end
+
+      # Minimal CSS for fallback
+      def minimal_css
+        <<~CSS
+          :root {
+            --sw-transition-fast: 120ms ease-out;
+            --sw-transition: 200ms ease-out;
+            --sw-color-primary: #c2410c;
+            --sw-color-text: #111111;
+            --sw-color-bg: #f8f8f8;
+            --sw-color-bg-card: #ffffff;
+            --sw-color-border: #e0e0e0;
+            --sw-spacing-md: 1.25rem;
+            --sw-radius-md: 6px;
+          }
+          
+          body {
+            font-family: 'Source Sans 3', system-ui, sans-serif;
+            background: var(--sw-color-bg);
+            color: var(--sw-color-text);
+            padding: 1rem;
+          }
+        CSS
+      end
+
+      # Google Fonts link tags
+      def google_fonts_html
+        <<~HTML
+          <link rel="preconnect" href="https://fonts.googleapis.com">
+          <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+          <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Crimson+Pro:wght@400;500;600&family=Source+Sans+3:wght@400;500;600;700&display=swap">
+        HTML
+      end
+
+      # CDN scripts for HTMX and Alpine.js
+      def cdn_scripts_html
+        <<~HTML
+          <script src="https://unpkg.com/htmx.org@2.0.4"></script>
+          <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
+        HTML
+      end
+
+      # Content update animation CSS
+      def animation_css
+        <<~CSS
+          /* Content update animations */
+          .sw-fade-in {
+            animation: sw-fade-in 350ms ease-out;
+          }
+
+          @keyframes sw-fade-in {
+            from {
+              opacity: 0;
+              transform: translateY(-12px) scale(0.98);
+            }
+            to {
+              opacity: 1;
+              transform: translateY(0) scale(1);
+            }
+          }
+          
+          .sw-slide-in {
+            animation: sw-slide-in 250ms ease-out;
+          }
+
+          @keyframes sw-slide-in {
+            from {
+              opacity: 0;
+              transform: translateX(-8px);
+            }
+            to {
+              opacity: 1;
+              transform: translateX(0);
+            }
+          }
+
+          /* Swap-target busy treatment during in-flight requests (FAC-P1.5).
+             Delay-in via transition-delay so fast responses never flicker;
+             undimming (class removed) is immediate. */
+          #app-container {
+            transition: opacity var(--sw-transition-fast, 120ms) ease-out;
+          }
+
+          #app-container.htmx-request {
+            opacity: 0.85;
+            transition-delay: 150ms;
+          }
+
+          /* Table styles */
+          .sw-table {
+            width: 100%;
+            border-collapse: collapse;
+          }
+          .sw-row-striped {
+            background: var(--sw-color-bg-muted, #f9fafb);
+          }
+          .sw-row-hoverable:hover {
+            background: var(--sw-color-bg-hover, #f0f0f0) !important;
+          }
+          .sw-table-bordered td,
+          .sw-table-bordered th {
+            border: 1px solid var(--sw-color-border, #e0e0e0);
+          }
+        CSS
+      end
+
+      # Dev-only "content missing" overlay (dev-loud-failure-overlay).
+      # Always emitted -- inert in production since DevFallbackOverlay only
+      # ever renders the `.sw-dev-fallback` markup these rules target when
+      # RACK_ENV=development. Styleable via the --sw-dev-fallback-* tokens;
+      # authors can also override the `.sw-dev-fallback` class hook directly.
+      def dev_fallback_css
+        <<~CSS
+          .sw-dev-fallback {
+            --sw-dev-fallback-bg: #fff7ed;
+            --sw-dev-fallback-border: #f59e0b;
+            --sw-dev-fallback-text: #7c2d12;
+            --sw-dev-fallback-accent: #b45309;
+            margin: 0 0 var(--sw-spacing-md, 1.25rem);
+            font-family: 'Source Sans 3', system-ui, sans-serif;
+          }
+
+          .sw-dev-fallback__dismiss:checked ~ .sw-dev-fallback__panel {
+            display: none;
+          }
+
+          .sw-dev-fallback__panel {
+            position: relative;
+            background: var(--sw-dev-fallback-bg);
+            border: 1px solid var(--sw-dev-fallback-border);
+            border-left: 4px solid var(--sw-dev-fallback-accent);
+            border-radius: var(--sw-radius-md, 6px);
+            padding: 0.75rem 2rem 0.75rem 1rem;
+            color: var(--sw-dev-fallback-text);
+            font-size: 0.875rem;
+            line-height: 1.5;
+          }
+
+          .sw-dev-fallback__panel > p {
+            margin: 0.25rem 0;
+          }
+
+          .sw-dev-fallback__title {
+            font-weight: 600;
+          }
+
+          .sw-dev-fallback__target code,
+          .sw-dev-fallback__cause code {
+            background: rgba(0, 0, 0, 0.06);
+            border-radius: 3px;
+            padding: 0.05rem 0.3rem;
+          }
+
+          .sw-dev-fallback__note {
+            font-size: 0.8rem;
+            opacity: 0.8;
+          }
+
+          .sw-dev-fallback__close {
+            position: absolute;
+            top: 0.5rem;
+            right: 0.6rem;
+            cursor: pointer;
+            font-size: 1.1rem;
+            line-height: 1;
+            color: var(--sw-dev-fallback-accent);
+          }
+        CSS
+      end
+    end
+  end
+end

data/lib/stream_weaver/dev_fallback_overlay.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'rack/utils'
+
+module StreamWeaver
+  # Development-only "content missing" analog (dev-loud-failure-overlay,
+  # streamweaver-way epic). Hotwire treats a missing/stale Turbo Frame
+  # target as its single best debugging aid; StreamWeaver's fallback path
+  # (server.rb's `rescue StaleActionDefinition`) instead self-heals with a
+  # silent full-container swap so production users never see broken wiring.
+  # That silence is deliberate in production (see docs/for_llms.md, "Dev
+  # loud, prod self-heal") but costs the author a debugging signal in dev --
+  # this module renders the loud version for RACK_ENV=development only.
+  #
+  # Framework-emitted only: app code stays zero-JS. The dismiss control is a
+  # pure CSS checkbox/label pattern (see CSS.dev_fallback_css) -- no inline
+  # `onclick`, no script tag.
+  module DevFallbackOverlay
+    CAUSES = {
+      definition_changed: "action token stale — the app's registered actions changed since this " \
+                           "token was issued (code reload). Interaction fell back to a full re-render.",
+      generation_changed: "action token stale — the server session's action generation changed " \
+                           "(restart or session reset) since this token was issued. Interaction " \
+                           "fell back to a full re-render."
+    }.freeze
+
+    DEFAULT_CAUSE = "action token stale after code reload — interaction fell back to a full re-render."
+
+    class << self
+      # @param action [Symbol, String, nil] the named action the stale token was minted for
+      # @param fragment [String, nil] the scoped fragment id the token declared as its swap target
+      # @param cause [Symbol, nil] :definition_changed or :generation_changed
+      # @return [String] HTML for the `.sw-dev-fallback` overlay, meant to be prepended to the
+      #   fallback response body so it lands inside the retargeted #app-container swap
+      def render(action: nil, fragment: nil, cause: nil)
+        dismiss_id = "sw-dev-fallback-dismiss-#{SecureRandom.hex(4)}"
+        target_label = fragment ? "##{fragment}" : (action ? "action #{action}" : "#app-container")
+
+        <<~HTML
+          <div class="sw-dev-fallback" role="alert">
+            <input type="checkbox" id="#{dismiss_id}" class="sw-dev-fallback__dismiss" hidden>
+            <div class="sw-dev-fallback__panel">
+              <label for="#{dismiss_id}" class="sw-dev-fallback__close" aria-label="Dismiss">&times;</label>
+              <p class="sw-dev-fallback__title">StreamWeaver dev warning — full re-render fallback</p>
+              <p class="sw-dev-fallback__target">Target: <code>#{escape(target_label)}</code> (swapped as <code>#app-container</code> instead)</p>
+              <p class="sw-dev-fallback__cause">#{escape(CAUSES.fetch(cause, DEFAULT_CAUSE))}</p>
+              <p class="sw-dev-fallback__note">Dev-only — production silently self-heals the same way. See docs/for_llms.md, "Dev loud, prod self-heal".</p>
+            </div>
+          </div>
+        HTML
+      end
+
+      private
+
+      def escape(str)
+        Rack::Utils.escape_html(str.to_s)
+      end
+    end
+  end
+end