feat: add rendering mode and client theme management for Astro frontend

- Added rendering_mode to Pwb::Website to distinguish between Rails and client-side rendering
- Created Pwb::ClientTheme model to manage Astro-based themes
- Added Pwb::WebsiteRenderingMode concern for website rendering logic
- Updated database schema and added migrations
- Added factories and specs for the new functionality

Author: etewiah

app/models/concerns/pwb/website_rendering_mode.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Concern for managing website rendering modes
+# Websites can use either Rails (B themes) or Client (A themes) rendering
+#
+# Key behaviors:
+# - rendering_mode defaults to 'rails'
+# - client_theme_name is required when using 'client' mode
+# - rendering_mode becomes immutable after website has content
+#
+module Pwb
+  module WebsiteRenderingMode
+    extend ActiveSupport::Concern
+
+    RENDERING_MODES = %w[rails client].freeze
+
+    included do
+      # ===================
+      # Validations
+      # ===================
+      validates :rendering_mode, inclusion: { in: RENDERING_MODES }
+      validates :client_theme_name, presence: true, if: :client_rendering?
+      validate :client_theme_must_exist, if: :client_rendering?
+      validate :rendering_mode_immutable, on: :update
+    end
+
+    # ===================
+    # Instance Methods
+    # ===================
+
+    # Check if using Rails rendering (B themes)
+    #
+    # @return [Boolean]
+    def rails_rendering?
+      rendering_mode == 'rails'
+    end
+
+    # Check if using client rendering (A themes)
+    #
+    # @return [Boolean]
+    def client_rendering?
+      rendering_mode == 'client'
+    end
+
+    # Get the client theme object
+    #
+    # @return [Pwb::ClientTheme, nil]
+    def client_theme
+      return nil unless client_rendering?
+
+      @client_theme ||= Pwb::ClientTheme.enabled.by_name(client_theme_name)
+    end
+
+    # Get merged theme config (defaults + website overrides)
+    #
+    # @return [Hash]
+    def effective_client_theme_config
+      return {} unless client_theme
+
+      client_theme.config_for_website(self)
+    end
+
+    # Generate CSS variables for client theme
+    #
+    # @return [String]
+    def client_theme_css_variables
+      return '' unless client_theme
+
+      client_theme.generate_css_variables(effective_client_theme_config)
+    end
+
+    # Check if rendering mode can still be changed
+    # Locked after website has been provisioned and has content
+    #
+    # @return [Boolean]
+    def rendering_mode_locked?
+      provisioning_completed_at.present? && page_contents.any?
+    end
+
+    # Check if rendering mode can be changed
+    #
+    # @return [Boolean]
+    def rendering_mode_changeable?
+      !rendering_mode_locked?
+    end
+
+    private
+
+    # Validate that the client theme exists and is enabled
+    def client_theme_must_exist
+      return unless client_theme_name.present?
+
+      unless Pwb::ClientTheme.enabled.exists?(name: client_theme_name)
+        errors.add(:client_theme_name, 'is not a valid client theme')
+      end
+    end
+
+    # Prevent changing rendering_mode after content is created
+    def rendering_mode_immutable
+      return unless rendering_mode_changed?
+      return unless rendering_mode_locked?
+
+      errors.add(:rendering_mode, 'cannot be changed after website has content')
+    end
+  end
+end

app/models/pwb/client_theme.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# == Schema Information
+#
+# Table name: pwb_client_themes
+#
+#  id                :bigint           not null, primary key
+#  name              :string           not null
+#  friendly_name     :string           not null
+#  version           :string           default("1.0.0")
+#  description       :text
+#  preview_image_url :string
+#  default_config    :jsonb            not null, default({})
+#  color_schema      :jsonb            not null, default({})
+#  font_schema       :jsonb            not null, default({})
+#  layout_options    :jsonb            not null, default({})
+#  enabled           :boolean          default(TRUE), not null
+#  created_at        :datetime         not null
+#  updated_at        :datetime         not null
+#
+# Indexes
+#
+#  index_pwb_client_themes_on_enabled  (enabled)
+#  index_pwb_client_themes_on_name     (name) UNIQUE
+#
+module Pwb
+  class ClientTheme < ApplicationRecord
+    self.table_name = 'pwb_client_themes'
+
+    # ===================
+    # Validations
+    # ===================
+    validates :name, presence: true, uniqueness: true,
+                     format: { with: /\A[a-z][a-z0-9_]*\z/, message: 'must be lowercase letters, numbers, and underscores' }
+    validates :friendly_name, presence: true
+
+    # ===================
+    # Scopes
+    # ===================
+    scope :enabled, -> { where(enabled: true) }
+    scope :by_name, ->(name) { where(name: name) }
+
+    # Find a single theme by name
+    def self.by_name(name)
+      find_by(name: name)
+    end
+
+    # ===================
+    # Instance Methods
+    # ===================
+
+    # Get the merged config for a website (defaults + website overrides)
+    #
+    # @param website [Pwb::Website] The website to get config for
+    # @return [Hash] Merged configuration
+    def config_for_website(website)
+      default_config.merge(website.client_theme_config || {})
+    end
+
+    # Generate CSS variables from a configuration
+    #
+    # @param config [Hash] Configuration to convert (defaults to default_config)
+    # @return [String] CSS :root block with variables
+    def generate_css_variables(config = default_config)
+      return '' if config.blank?
+
+      css_vars = config.map do |key, value|
+        css_var_name = key.to_s.tr('_', '-')
+        "--#{css_var_name}: #{value}"
+      end
+
+      ":root { #{css_vars.join('; ')}; }"
+    end
+
+    # API serialization
+    #
+    # @return [Hash] Theme data for API responses
+    def as_api_json
+      {
+        name: name,
+        friendly_name: friendly_name,
+        version: version,
+        description: description,
+        preview_image_url: preview_image_url,
+        default_config: default_config,
+        color_schema: color_schema,
+        font_schema: font_schema,
+        layout_options: layout_options
+      }
+    end
+
+    # For select options in forms
+    #
+    # @return [Array<Array>] Array of [friendly_name, name] pairs
+    def self.options_for_select
+      enabled.order(:friendly_name).pluck(:friendly_name, :name)
+    end
+  end
+end

app/models/pwb/website.rb

@@ -10,6 +10,8 @@
 #  analytics_id_type                   :integer
 #  available_currencies                :text             default([]), is an Array
 #  available_themes                    :text             is an Array
+#  client_theme_config                 :jsonb
+#  client_theme_name                   :string
 #  company_display_name                :string
 #  compiled_palette_css                :text
 #  configuration                       :json
@@ -63,6 +65,7 @@
 #  raw_css                             :text
 #  realty_assets_count                 :integer          default(0), not null
 #  recaptcha_key                       :string
+#  rendering_mode                      :string           default("rails"), not null
 #  rent_price_options_from             :text             default(["", "250", "500", "750", "1,000", "1,500", "2,500", "5,000"]), is an Array
 #  rent_price_options_till             :text             default(["", "250", "500", "750", "1,000", "1,500", "2,500", "5,000"]), is an Array
 #  sale_price_options_from             :text             default(["", "25,000", "50,000", "75,000", "100,000", "150,000", "250,000", "500,000", "1,000,000", "2,000,000", "5,000,000", "10,000,000"]), is an Array
@@ -100,6 +103,7 @@
 #  index_pwb_websites_on_palette_mode              (palette_mode)
 #  index_pwb_websites_on_provisioning_state        (provisioning_state)
 #  index_pwb_websites_on_realty_assets_count       (realty_assets_count)
+#  index_pwb_websites_on_rendering_mode            (rendering_mode)
 #  index_pwb_websites_on_search_config             (search_config) USING gin
 #  index_pwb_websites_on_selected_palette          (selected_palette)
 #  index_pwb_websites_on_site_type                 (site_type)
@@ -118,6 +122,7 @@ class Website < ApplicationRecord
     include Pwb::WebsiteSocialLinkable
     include Pwb::WebsiteLocalizable
     include Pwb::WebsiteThemeable
+    include Pwb::WebsiteRenderingMode
     include Pwb::DemoWebsite
     include FlagShihTzu
 

db/migrate/20260115140000_add_rendering_mode_to_websites.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Migration to add rendering mode support to websites
+# This enables websites to choose between Rails (B themes) and Client (A themes) rendering
+class AddRenderingModeToWebsites < ActiveRecord::Migration[8.0]
+  def change
+    # Rendering mode: 'rails' for traditional server-side rendering, 'client' for Astro
+    add_column :pwb_websites, :rendering_mode, :string, default: 'rails', null: false
+
+    # Client theme name (only used when rendering_mode = 'client')
+    add_column :pwb_websites, :client_theme_name, :string
+
+    # Website-specific client theme configuration overrides
+    add_column :pwb_websites, :client_theme_config, :jsonb, default: {}
+
+    # Index for filtering by rendering mode
+    add_index :pwb_websites, :rendering_mode
+
+    # Check constraint to ensure only valid values
+    add_check_constraint :pwb_websites,
+                         "rendering_mode IN ('rails', 'client')",
+                         name: 'rendering_mode_valid'
+  end
+end

db/migrate/20260115140001_create_pwb_client_themes.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Creates the pwb_client_themes table for Astro A themes
+# These are database-backed themes used by client-rendered websites
+class CreatePwbClientThemes < ActiveRecord::Migration[8.0]
+  def change
+    create_table :pwb_client_themes do |t|
+      # Theme identifier (lowercase, e.g., 'amsterdam')
+      t.string :name, null: false
+
+      # Human-readable name (e.g., 'Amsterdam Modern')
+      t.string :friendly_name, null: false
+
+      # Semantic version
+      t.string :version, default: '1.0.0'
+
+      # Description for admin UI
+      t.text :description
+
+      # Preview image URL for theme selection
+      t.string :preview_image_url
+
+      # Default configuration values
+      t.jsonb :default_config, default: {}
+
+      # Schema for color customization options
+      t.jsonb :color_schema, default: {}
+
+      # Schema for font customization options
+      t.jsonb :font_schema, default: {}
+
+      # Schema for layout customization options
+      t.jsonb :layout_options, default: {}
+
+      # Whether this theme is available for selection
+      t.boolean :enabled, default: true, null: false
+
+      t.timestamps
+    end
+
+    # Unique constraint on name
+    add_index :pwb_client_themes, :name, unique: true
+
+    # Index for filtering enabled themes
+    add_index :pwb_client_themes, :enabled
+  end
+end

db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[8.1].define(version: 2026_01_10_165317) do
+ActiveRecord::Schema[8.1].define(version: 2026_01_15_140001) do
   # These are extensions that must be enabled in order to support this database
   enable_extension "pg_catalog.plpgsql"
   enable_extension "pgcrypto"
@@ -166,6 +166,23 @@
     t.index ["user_id"], name: "index_pwb_authorizations_on_user_id"
   end
 
+  create_table "pwb_client_themes", force: :cascade do |t|
+    t.jsonb "color_schema", default: {}
+    t.datetime "created_at", null: false
+    t.jsonb "default_config", default: {}
+    t.text "description"
+    t.boolean "enabled", default: true, null: false
+    t.jsonb "font_schema", default: {}
+    t.string "friendly_name", null: false
+    t.jsonb "layout_options", default: {}
+    t.string "name", null: false
+    t.string "preview_image_url"
+    t.datetime "updated_at", null: false
+    t.string "version", default: "1.0.0"
+    t.index ["enabled"], name: "index_pwb_client_themes_on_enabled"
+    t.index ["name"], name: "index_pwb_client_themes_on_name", unique: true
+  end
+
   create_table "pwb_clients", id: :serial, force: :cascade do |t|
     t.integer "address_id"
     t.string "client_title"
@@ -1086,6 +1103,8 @@
     t.integer "analytics_id_type"
     t.text "available_currencies", default: [], array: true
     t.text "available_themes", array: true
+    t.jsonb "client_theme_config", default: {}
+    t.string "client_theme_name"
     t.string "company_display_name"
     t.text "compiled_palette_css"
     t.json "configuration", default: {}
@@ -1141,6 +1160,7 @@
     t.text "raw_css"
     t.integer "realty_assets_count", default: 0, null: false
     t.string "recaptcha_key"
+    t.string "rendering_mode", default: "rails", null: false
     t.text "rent_price_options_from", default: ["", "250", "500", "750", "1,000", "1,500", "2,500", "5,000"], array: true
     t.text "rent_price_options_till", default: ["", "250", "500", "750", "1,000", "1,500", "2,500", "5,000"], array: true
     t.text "sale_price_options_from", default: ["", "25,000", "50,000", "75,000", "100,000", "150,000", "250,000", "500,000", "1,000,000", "2,000,000", "5,000,000", "10,000,000"], array: true
@@ -1172,11 +1192,13 @@
     t.index ["palette_mode"], name: "index_pwb_websites_on_palette_mode"
     t.index ["provisioning_state"], name: "index_pwb_websites_on_provisioning_state"
     t.index ["realty_assets_count"], name: "index_pwb_websites_on_realty_assets_count"
+    t.index ["rendering_mode"], name: "index_pwb_websites_on_rendering_mode"
     t.index ["search_config"], name: "index_pwb_websites_on_search_config", using: :gin
     t.index ["selected_palette"], name: "index_pwb_websites_on_selected_palette"
     t.index ["site_type"], name: "index_pwb_websites_on_site_type"
     t.index ["slug"], name: "index_pwb_websites_on_slug"
     t.index ["subdomain"], name: "index_pwb_websites_on_subdomain", unique: true
+    t.check_constraint "rendering_mode::text = ANY (ARRAY['rails'::character varying, 'client'::character varying]::text[])", name: "rendering_mode_valid"
   end
 
   create_table "pwb_widget_configs", id: :uuid, default: -> { "gen_random_uuid()" }, force: :cascade do |t|