turbo_chat 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3fc14508fac1357a1da08a00d2cd3b905271a1fd5a18dc0ccc71e8f6a8572c7
-  data.tar.gz: dc7b1fb742ebe03541e5ab140c312d1b2ed6f27efeb0cfbd3adca266bd9f7b28
+  metadata.gz: 2a123f536b09e56d7dbbe582048c7d5eceff7d043126c947647c567b6004b972
+  data.tar.gz: d568733e0d68d5e74c67bf0ab7f0a3ccc6433aa14797575311fe1d9250490835
 SHA512:
-  metadata.gz: a452a6b3ba2b13ab03382150ca9f5780b13994781011a764f54a518939a095a46dec586319b9853f5e03bc4b7b0e70fc62af9749935540fcc5525534c2c910c6
-  data.tar.gz: be545c2e1dc54a1df52fa83e8785ab36ea48c138ce40338c12ebd122e5311d771c861688b1347fe3f3b1f77c646c5f1fa7e1207fd482293c5ef89858a6b39cc4
+  metadata.gz: 1ef3331843b81f06f0f5e77988a03ee6d7039b6afecdf4a744259cf0c704d6e0ebf4cec5e9ad37a61e060fea9c3620f1962dc7e0129e987615d3ddc79b65a81d
+  data.tar.gz: 155857795d96fdea994d64ac88fdbf4021900c9066a0343dcd36648c823f7bc30f6798db94a2a3b1bd6b1e11f90e6203cf09641fd719cad19f358b95c978f478

data/CHANGELOG.md

@@ -2,15 +2,38 @@
 
 All notable changes to `turbo_chat` will be documented in this file.
 
-## [0.2.0] - 2026-03-02
+## [0.3.0] - 2026-03-25
+
+### Added
+- `chat_mode` on chats with `standard` as the default and `assistant` as a built-in alternate mode.
+- Mode-aware configuration overrides via `config.mode(:assistant)` so assistant chats can simplify UI and behavior without affecting standard chats.
+- Built-in assistant-mode defaults for 1:1 assistant conversations, including a two-participant limit and simplified members/invite/mention/moderation defaults.
+- README and installer guidance for chat modes and assistant-mode overrides.
+
+### Changed
+- Chat UI, rendering helpers, validations, moderation events, and message/signal settings now resolve configuration against the current chat when mode-specific overrides are present.
+
+### Fixed
+- Inviting an already-active participant or a participant with a pending invitation no longer reuses the membership in a way that can silently demote it back to a pending state.
+
+## [0.2.0] - 2026-03-03
 
 ### Added
 - Membership lookup cache (`Chat#membership_lookup`) for efficient per-message role resolution, eliminating N+1 queries when rendering participant roles in message lists.
 - Memoized `actor_membership` in Permission to avoid redundant database queries within a single request.
+- Moderation UI: mute/unmute and remove buttons in the members panel with permission-gated visibility (`can_mute_member?`, `can_ban_member?`).
+- `mute` and `ban` member routes and controller actions backed by `TurboChat::Moderation`.
+- Narrower `chat-shell--narrow` variant for the new-chat page.
 
 ### Changed
 - Narrowed broad `rescue StandardError` clauses to specific exception types (`NoMethodError`, `TypeError`) across controllers, helpers, models, and permission modules for better error visibility during development.
 - Removed duplicated `containerBottomPadding` function from `realtime.js`; now imports the shared version from `shared.js`.
+- New-chat page uses compact inline grid form instead of full-width field and button.
+- Members invite dropdown no longer clipped by panel overflow when expanded.
+- Removed redundant "Conversation active/closed" kicker from chat header.
+- Invite submit button disabled until a participant is selected from the dropdown.
+- Gear button hidden (instead of disabled) for own member entry in the members panel.
+- Manage-member gear toggle now visible for moderators with mute/ban permissions, not only admins with grant permissions.
 
 ## [0.1.15] - 2026-02-28
 

data/README.md

@@ -6,10 +6,12 @@ Status: actively maintained.
 
 ## What You Get
 
-- Turbo Stream chat UI.
-- Role-based permissions.
-- Mentions, invitations, moderation, and typing signals.
-- A Rails-first path to ship chat quickly.
+- Turbo Stream chat UI with two layout styles (bounded card or full-viewport).
+- Role-based permissions with a swappable adapter.
+- Mentions, invitations, inline message editing, and typing signals.
+- Moderation: mute, timeout, ban, and message deletion.
+- System messages for membership lifecycle events.
+- Browser and server-side event hooks.
 
 ## Basic Setup
 
@@ -59,20 +61,11 @@ class User < ApplicationRecord
 end
 ```
 
-### 2. Resolve the current participant
-
-You can define `current_chat_participant` in your host `ApplicationController`.
-If you already expose `current_user` and it returns a model using `acts_as_chat_participant`, TurboChat works without adding this method.
+This adds `has_many :chat_memberships` and the associations TurboChat needs to resolve participants in chats.
 
-Recommended hook:
+### 2. Resolve the current participant
 
-```ruby
-class ApplicationController < ActionController::Base
-  def current_chat_participant
-    current_user
-  end
-end
-```
+If your app exposes `current_user` and it returns a model using `acts_as_chat_participant`, TurboChat works out of the box.
 
 Resolution order:
 
@@ -81,7 +74,7 @@ Resolution order:
 3. `current_user` (if available)
 4. Raise `NotImplementedError`
 
-Optional resolver for non-`current_user` auth:
+For non-`current_user` auth:
 
 ```ruby
 TurboChat.configure do |config|
@@ -91,186 +84,177 @@ end
 
 ## First Working Example
 
-Create a chat and add an admin membership:
-
 ```ruby
 chat = TurboChat::Chat.create!(title: "Support")
 TurboChat::ChatMembership.create!(chat: chat, participant: current_user, role: :admin)
 ```
 
-Link to it:
-
 ```erb
 <%= link_to "Open chat", turbo_chat.chat_path(chat) %>
 ```
 
-## Essential Configuration
+## Configuration
+
+The installer generates a full initializer at `config/initializers/turbo_chat.rb` with every option documented. Start with the defaults and change only what you need.
 
-Start with a minimal initializer and only expand when needed:
+Config is organized into scoped namespaces:
 
 ```ruby
 TurboChat.configure do |config|
-  config.chat.permission_adapter = TurboChat::Permission
-
+  # Limits
   config.chat.max_chat_participants = 10
   config.chat_message.max_message_length = 1000
-  config.chat_message.message_history_limit = 200
 
+  # Features
   config.chat_message.enable_mentions = true
-  config.chat_message.enable_emoji_aliases = true
-
   config.chat_message.blocked_words = []
-  config.chat_message.blocked_words_action = :reject # or :scramble
+  config.chat_message.blocked_words_action = :reject  # or :scramble
 
-  config.chat_message.render_message_html = false
-  config.style.show_timestamp = true
-  config.style.show_role = false
-  config.chat_message.message_source_labels = TurboChat::Configuration::DEFAULT_MESSAGE_SOURCE_LABELS.dup
-  config.style.chat_style = "chat_style_bounded"
+  # Layout
+  config.style.chat_style = "chat_style_bounded"       # or "chat_style_unbounded"
   config.chat_message.message_insert_position = "append_end" # or "append_start"
-  config.chat.disable_input = false
-  config.chat.show_members = true
-  config.chat.show_members_list = true
-  config.chat.show_members_invite_controls = true
-  config.chat.show_invite_fallback_when_members_hidden = true
-  config.chat.show_header_title = true
-  config.chat.show_header_status = true
-  config.chat.show_header_close_action = true
-  config.chat.show_header_leave_action = true
-  config.chat.show_header_back_action = true
-  config.signals.signal_ttl_seconds = 60
-  config.style.signal_text_sheen = true
-
-  config.moderation.emit_moderation_events = false
-  config.moderation.emit_blocked_words_events = false
-  config.events.emit_mention_events = false
+
+  # Events (all opt-in, all false by default)
+  config.events.emit_typing_events = true
+  config.events.emit_message_events = true
 end
 ```
 
-Flat aliases (for example `config.max_message_length`) still work for backward compatibility.
+Available scopes: `config.chat`, `config.chat_message`, `config.style`, `config.events`, `config.moderation`, `config.signals`. Flat aliases (e.g. `config.max_message_length`) still work for backward compatibility.
 
-### Rate Limiting
-
-TurboChat does not include built-in rate limiting. For production deployments, add request throttling for message creation in your host application using middleware such as [rack-attack](https://github.com/rack/rack-attack).
-
-## Message Ingest API
+### Chat Modes
 
-Post messages as a specific participant, including external sources like WhatsApp:
+Chats default to `chat_mode: :standard`.
 
 ```ruby
-TurboChat::Messages.send_message_as(
-  current_user,
-  chat,
-  body: "Internal note",
-  source: :app
-)
+chat = TurboChat::Chat.create!(title: "Assistant", chat_mode: :assistant)
 ```
 
-External ingest with idempotency (`chat_id + source + external_id`):
+Built-in assistant-mode defaults make the chat simpler for 1:1 assistant use cases:
 
-```ruby
-TurboChat::Messages.ingest_external!(
-  chat: chat,
-  participant: current_user,
-  body: "Hello from WhatsApp",
-  source: :whatsapp,
-  external_id: webhook_payload.fetch("message_id"),
-  sent_at: webhook_payload["sent_at"]
-)
-```
+- `max_chat_participants = 2`
+- members panel and invite UI hidden
+- mentions disabled
+- system messages disabled
+- chat close action hidden
+- invitation, mention, lifecycle, and moderation events disabled
 
-`external_id` is required for `ingest_external!` so duplicate webhook deliveries can resolve to the same stored message.
-
-Source labels shown in message badges are configurable:
+You can override assistant-mode defaults without changing standard chats:
 
 ```ruby
 TurboChat.configure do |config|
-  config.chat_message.message_source_labels = {
-    "app" => "In App",
-    "whatsapp" => "WhatsApp",
-    "sms_gateway" => "SMS"
-  }
+  config.mode(:assistant).show_members = true
+  config.mode(:assistant).enable_mentions = true
 end
 ```
 
-Chat UI layout style is configurable:
+### Rate Limiting
 
-```ruby
-TurboChat.configure do |config|
-  config.style.chat_style = "chat_style_unbounded" # or "chat_style_bounded"
-end
-```
+TurboChat does not include built-in rate limiting. For production, add request throttling using middleware such as [rack-attack](https://github.com/rack/rack-attack).
 
-Timeline insert position is configurable:
+## Roles and Permissions
 
-```ruby
-TurboChat.configure do |config|
-  config.chat_message.message_insert_position = "append_end" # or "append_start"
-end
-```
+### Built-in roles
+
+| Role | Rank | Key capabilities |
+|------|------|-----------------|
+| `member` | 0 | View, post, mention members, edit own messages |
+| `moderator` | 1 | + invite, `@all`/`@ROLE` mentions, mute/timeout/ban, delete messages |
+| `admin` | 2 | + close/reopen chats, change member roles |
 
-Composer input can be disabled globally:
+Higher-rank roles can act on lower-rank members but not on peers or above.
+
+### Custom roles
 
 ```ruby
 TurboChat.configure do |config|
-  config.chat.disable_input = true
+  config.add_role(
+    :support_agent,
+    name: "Support Agent",
+    rank: 1,
+    permissions: %i[view_chat post_message delete_message]
+  )
 end
 ```
 
-Chat header elements can also be disabled globally:
+### Permission adapter
+
+All access checks go through `config.chat.permission_adapter` (default: `TurboChat::Permission`). To customize, create a class that implements the same public interface:
 
 ```ruby
+class CustomPermission < TurboChat::Permission
+  def can_post_message?
+    super && !participant.suspended?
+  end
+end
+
 TurboChat.configure do |config|
-  config.chat.show_header_title = false
-  config.chat.show_header_status = false
-  config.chat.show_header_close_action = false
-  config.chat.show_header_leave_action = false
-  config.chat.show_header_back_action = false
+  config.chat.permission_adapter = CustomPermission
 end
 ```
 
-Members area visibility can be tuned independently:
+The adapter must respond to: `can_view_chat?`, `can_create_chat?`, `can_post_message?`, `can_invite_member?`, `can_grant_member_permissions?`, `can_mute_member?`, `can_timeout_member?`, `can_ban_member?`, `can_delete_message?`, `can_edit_message?`, `can_close_chat?`, `can_reopen_chat?`.
+
+## Invitations
+
+Admins and moderators can invite participants through the members panel. The invited participant sees pending invitations on the chat index with Accept/Decline buttons.
+
+Programmatic invitation:
 
 ```ruby
-TurboChat.configure do |config|
-  config.chat.show_members = true
-  config.chat.show_members_list = true
-  config.chat.show_members_invite_controls = true
-  config.chat.show_invite_fallback_when_members_hidden = true
-end
+TurboChat::ChatMembership.create!(
+  chat: chat,
+  participant: invitee,
+  role: :member,
+  invitation_accepted: false
+)
 ```
 
-## Roles
+Accept/decline routes are built in: `PATCH /chats/:id/accept` and `PATCH /chats/:id/decline`.
 
-Built-in roles:
+## Message Ingest API
+
+Post messages as a specific participant:
 
-- `member`
-- `moderator`
-- `admin`
+```ruby
+TurboChat::Messages.send_message_as(
+  current_user,
+  chat,
+  body: "Internal note",
+  source: :app
+)
+```
 
-Role behavior:
+External ingest with idempotency (`chat_id + source + external_id`):
 
-- `member`: can view/post and mention members.
-- `moderator`: can invite, mention `@all`/roles, mute/timeout/ban, and delete lower-rank messages.
-- `admin`: can do moderator actions plus close/reopen chats.
+```ruby
+TurboChat::Messages.ingest_external!(
+  chat: chat,
+  participant: current_user,
+  body: "Hello from WhatsApp",
+  source: :whatsapp,
+  external_id: webhook_payload.fetch("message_id"),
+  sent_at: webhook_payload["sent_at"]
+)
+```
 
-Custom role example:
+Duplicate webhook deliveries with the same `external_id` resolve to the existing message.
+
+Source labels shown in message badges are configurable:
 
 ```ruby
-TurboChat.configure do |config|
-  config.add_role(
-    :support_agent,
-    name: "Support Agent",
-    rank: 1,
-    permissions: %i[view_chat post_message delete_message]
-  )
-end
+config.chat_message.message_source_labels = {
+  "app" => "In App",
+  "whatsapp" => "WhatsApp",
+  "sms_gateway" => "SMS"
+}
 ```
 
 ## Moderation API
 
 ```ruby
 TurboChat::Moderation.mute_member!(actor: moderator, membership: membership)
+TurboChat::Moderation.unmute_member!(actor: moderator, membership: membership)
 TurboChat::Moderation.timeout_member!(actor: moderator, membership: membership, until_time: 30.minutes.from_now)
 TurboChat::Moderation.ban_member!(actor: moderator, membership: membership)
 TurboChat::Moderation.delete_message!(actor: moderator, message: message)
@@ -278,93 +262,97 @@ TurboChat::Moderation.close_chat!(actor: admin, chat: chat)
 TurboChat::Moderation.reopen_chat!(actor: admin, chat: chat)
 ```
 
-Raises:
+All actions are permission-checked and generate system messages in the chat timeline. Mute, timeout, ban, and role changes are visible to all participants as system messages (disable with `config.chat.system_messages = false`).
 
-- `TurboChat::Moderation::AuthorizationError`
-- `TurboChat::Moderation::InvalidActionError`
+Raises `TurboChat::Moderation::AuthorizationError` or `TurboChat::Moderation::InvalidActionError`.
 
 ## Signals API
 
 ```ruby
-TurboChat::Signals.start!(chat: chat, participant: current_user, signal_type: :typing)
-TurboChat::Signals.start!(chat: chat, participant: current_user, signal_type: :custom, signal_text: "Hello")
-TurboChat::Signals.custom!(chat: chat, participant: current_user, signal_text: "Reviewing your request")
-TurboChat::Signals.clear!(chat: chat, participant: current_user)
+TurboChat::Signals.start!(chat: chat, participant: user, signal_type: :typing)
+TurboChat::Signals.start!(chat: chat, participant: user, signal_type: :thinking)
+TurboChat::Signals.start!(chat: chat, participant: user, signal_type: :planning)
+TurboChat::Signals.custom!(chat: chat, participant: user, signal_text: "Reviewing your request")
+TurboChat::Signals.clear!(chat: chat, participant: user)
 ```
 
-## Event Emissions
-
-All event emissions are opt-in.
-
-Enable only what you consume:
+Block form that auto-clears when the work finishes:
 
 ```ruby
-TurboChat.configure do |config|
-  config.events.emit_typing_events = true
-  config.events.emit_message_events = true
-  config.events.emit_mention_events = true
-  config.events.emit_invitation_events = true
-  config.events.emit_chat_lifecycle_events = true
-  config.moderation.emit_moderation_events = true
-  config.moderation.emit_blocked_words_events = true
+TurboChat::Signals.with(chat: chat, participant: user, signal_type: :thinking) do
+  # long-running operation
 end
 ```
 
-Browser events (`CustomEvent`):
+Signal lifetime is configurable via `config.signals.signal_ttl_seconds` (default: 60).
 
-- `emit_typing_events`: `turbo-chat:typing-started`, `turbo-chat:typing-ended`
-- `emit_message_events`: `turbo-chat:message-sent`
-- `emit_mention_events`: `turbo-chat:mention`
-- `emit_invitation_events`: `turbo-chat:invitation-accepted`
-- `emit_chat_lifecycle_events`: `turbo-chat:chat-invited`, `turbo-chat:chat-joined`, `turbo-chat:chat-declined`, `turbo-chat:chat-left`, `turbo-chat:chat-closed`, `turbo-chat:chat-reopened`
+## Events
 
-Minimal browser listener:
+All event emissions are opt-in.
+
+### Browser events (`CustomEvent` on `document`)
+
+```ruby
+config.events.emit_typing_events = true         # turbo-chat:typing-started, turbo-chat:typing-ended
+config.events.emit_message_events = true         # turbo-chat:message-sent
+config.events.emit_mention_events = true         # turbo-chat:mention
+config.events.emit_invitation_events = true      # turbo-chat:invitation-accepted
+config.events.emit_chat_lifecycle_events = true  # turbo-chat:chat-invited, chat-joined, chat-declined,
+                                                 #   chat-left, chat-closed, chat-reopened
+```
 
 ```js
-[
-  "turbo-chat:typing-started",
-  "turbo-chat:typing-ended",
-  "turbo-chat:message-sent",
-  "turbo-chat:mention",
-  "turbo-chat:invitation-accepted",
-  "turbo-chat:chat-invited",
-  "turbo-chat:chat-joined",
-  "turbo-chat:chat-declined",
-  "turbo-chat:chat-left",
-  "turbo-chat:chat-closed",
-  "turbo-chat:chat-reopened"
-].forEach(function (eventName) {
-  document.addEventListener(eventName, function (event) {
-    console.log(eventName, event.detail);
-  });
+document.addEventListener("turbo-chat:message-sent", function (event) {
+  console.log(event.detail); // { chatId: "123" }
 });
 ```
 
-Server-side notifications (`ActiveSupport::Notifications`):
-
-- `emit_moderation_events`:
-  `turbo_chat.moderation.member_muted`,
-  `turbo_chat.moderation.member_unmuted`,
-  `turbo_chat.moderation.member_timed_out`,
-  `turbo_chat.moderation.member_timeout_cleared`,
-  `turbo_chat.moderation.member_banned`,
-  `turbo_chat.moderation.message_deleted`,
-  `turbo_chat.moderation.chat_closed`,
-  `turbo_chat.moderation.chat_reopened`
-- `emit_blocked_words_events`:
-  `turbo_chat.blocked_words.detected`,
-  `turbo_chat.blocked_words.rejected`,
-  `turbo_chat.blocked_words.scrambled`
+### Server-side events (`ActiveSupport::Notifications`)
 
-Minimal Rails listener:
+```ruby
+config.moderation.emit_moderation_events = true    # turbo_chat.moderation.member_muted, member_banned, ...
+config.moderation.emit_blocked_words_events = true  # turbo_chat.blocked_words.detected, rejected, scrambled
+```
 
 ```ruby
-ActiveSupport::Notifications.subscribe(/turbo_chat\.(moderation|blocked_words)\./) do |*args|
+ActiveSupport::Notifications.subscribe(/turbo_chat\.moderation\./) do |*args|
   event = ActiveSupport::Notifications::Event.new(*args)
   Rails.logger.info("[TurboChat] #{event.name} #{event.payload.inspect}")
 end
 ```
 
+## Theming
+
+TurboChat ships a default theme built on CSS custom properties. Override them in your app stylesheet:
+
+```css
+:root {
+  --chat-text: #12263f;
+  --chat-muted: #5f738a;
+  --chat-border: #c9d5e3;
+  --chat-surface: #ffffff;
+  --chat-surface-soft: #f6f9fd;
+  --chat-primary: #1f6edc;
+  --chat-primary-dark: #1452ac;
+  --chat-primary-soft: #e7f1ff;
+  --chat-danger: #b42318;
+  --chat-danger-soft: #fff1f3;
+  --chat-success: #1f7a40;
+  --chat-success-soft: #ecfdf3;
+  --chat-mention-highlight-color: #b42318;
+  --chat-shadow: 0 20px 48px rgba(16, 36, 58, 0.12);
+}
+```
+
+Additional style config:
+
+```ruby
+config.style.own_message_hex_color = "#e7f1ff"
+config.style.other_message_hex_color = "#ffffff"
+config.style.mention_mark_hex_color = "#b42318"
+config.style.composer_placeholder_text = "Type a message..."
+```
+
 ## Upgrade
 
 ```bash
@@ -374,9 +362,9 @@ bin/rails db:migrate
 
 ## Known Limitations
 
-- **Stream subscriptions after member removal.** Turbo Stream subscriptions persist until the page is reloaded. A removed member may continue to see new messages until they navigate away. This is not a security issue because stream names are cryptographically signed, but it can be surprising.
-- **Blocked word filtering.** Word-boundary matching can be bypassed with Unicode homoglyphs, zero-width characters, or leetspeak substitutions. Treat it as a first line of defense, not a guarantee.
-- **Invitable participants cap.** The invite picker returns at most 100 non-member participants. Applications with larger user bases should provide a custom search endpoint.
+- **Stream subscriptions after member removal.** Turbo Stream subscriptions persist until page reload. A removed member may see new messages until they navigate away. Stream names are cryptographically signed so this is not a security issue.
+- **Blocked word filtering.** Word-boundary matching can be bypassed with Unicode homoglyphs, zero-width characters, or leetspeak. Treat it as a first line of defense.
+- **Invitable participants cap.** The invite picker returns at most 100 non-member participants. Larger user bases should provide a custom search endpoint.
 
 ## Dependencies
 

data/app/assets/config/turbo_chat_manifest.js

@@ -1,7 +1,10 @@
 //= link turbo_chat/application.css
 //= link turbo_chat/application.js
 //= link turbo_chat/shared.js
+//= link turbo_chat/mentions.js
+//= link turbo_chat/scroll_proxy.js
 //= link turbo_chat/messages.js
 //= link turbo_chat/realtime.js
 //= link turbo_chat/invite_picker.js
+//= link turbo_chat/member_sync.js
 //= link turbo_chat/lifecycle_events.js

data/app/assets/javascripts/turbo_chat/application.js

@@ -1,5 +1,8 @@
 //= require turbo_chat/shared
+//= require turbo_chat/scroll_proxy
+//= require turbo_chat/mentions
 //= require turbo_chat/messages
 //= require turbo_chat/realtime
 //= require turbo_chat/invite_picker
+//= require turbo_chat/member_sync
 //= require turbo_chat/lifecycle_events