feat(live_session_card): composite canonical widget Stage 1-4 (:workflow_progress_and_status family)

guides/user/UG-0003-widget-types-properties-and-signals.md

@@ -99,7 +99,7 @@ authoring boundaries and normalize before renderer-facing output.
 | Content, identity, and disclosure | `inline_rich_text_heading`, `disclosure`, `kicker`, `avatar`, `presence_dot` | none |
 | Form control and composer | `runtime_form_shell`, `segmented_button_group`, `chat_composer`, `collection_picker`, `mode_nav` | `phoenix_form` -> `runtime_form_shell` |
 | Row and artifact | `list_item_multi_column`, `artifact_row`, `thread_card`, `tool_call_card` | none |
-| Workflow, progress, and status | `pipeline_stepper_horizontal`, `segmented_progress_bar`, `workflow_stage_list_vertical`, `meter_thin`, `unread_badge`, `workflow_progress_status_card` | none |
+| Workflow, progress, and status | `pipeline_stepper_horizontal`, `segmented_progress_bar`, `workflow_stage_list_vertical`, `meter_thin`, `unread_badge`, `live_session_card`, `workflow_progress_status_card` | none |
 | Layer shell and callout | `sticky_frosted_header`, `slide_over_panel`, `event_callout`, `top_strip`, `sidebar_shell`, `sidebar_section`, `sidebar_item`, `command_palette`, `right_rail`, `composer_query_preview`, `propose_new_doc_card` | none |
 | Redline and code | `redline_inline`, `code_block_syntax_highlighted` | none |
 | Composition behavior | `list_repeat` | `repeat` -> `list_repeat`, `ui_relationship_repeat` -> `list_repeat` |
@@ -138,6 +138,14 @@ such as `subject_id`, `name`, `path`, `progress_pct`, `active_count`,
 `attributes.subject`; it does not expose map placement names, route helpers,
 LiveView event fields, or application-specific card names.
 
+`live_session_card` is the canonical card for an actively running assistant
+session. Author props such as `session_id`, `actor_handle`, `status`,
+`status_version`, `tools_count`, `edits_count`, `tokens_consumed`,
+`started_at`, optional `current_step`, `current_task_title`,
+`now_streaming`, `recent_events`, and `pinned?`. Use canonical
+`pin_toggled`, `interrupted`, and `expanded_recent` interactions. Keep
+LiveView event fields and route helpers in the host layer.
+
 `composer_query_preview` is the reusable inline preview band for query results
 adjacent to a composer. Author generic props such as `composer_id`, `query`,
 `preview_state`, `explanation`, `metrics`, `findings`, and

lib/ash_ui/rendering/iur_adapter.ex

@@ -94,11 +94,14 @@ defmodule AshUI.Rendering.IURAdapter do
     kind = map_element_kind(element.type)
     type = map_element_type(kind)
     props = if map_size(element.props || %{}) > 0, do: element.props, else: element.attributes
+    fallback_id = element.id || generate_id()
+    element_id = element_id_for_kind(kind, convert_props(props), fallback_id)
+    attribute_element_id = if kind == :live_session_card, do: element_id, else: element.id
 
     Element.new(type, kind,
-      id: element.id || generate_id(),
+      id: element_id,
       metadata: convert_metadata(element),
-      attributes: convert_attributes(kind, props, element.id),
+      attributes: convert_attributes(kind, props, attribute_element_id),
       children: convert_children(element.children)
     )
   end
@@ -155,6 +158,26 @@ defmodule AshUI.Rendering.IURAdapter do
 
   defp map_element_type(_kind), do: :widget
 
+  defp element_id_for_kind(:live_session_card, props, fallback_id) do
+    live_session = props |> fetch(:live_session, %{}) |> normalize_map()
+
+    session_id =
+      first_present(live_session, [:session_id]) ||
+        first_present(props, [:session_id])
+
+    status_version =
+      first_present(live_session, [:status_version]) ||
+        first_present(props, [:status_version])
+
+    if is_binary(session_id) and not is_nil(status_version) do
+      "live_session:#{session_id}:#{status_version}"
+    else
+      fallback_id
+    end
+  end
+
+  defp element_id_for_kind(_kind, _props, fallback_id), do: fallback_id
+
   # Convert props with name transformations
   defp convert_props(props) when is_map(props) do
     Enum.reduce(props, %{}, fn {key, value}, acc ->
@@ -370,6 +393,13 @@ defmodule AshUI.Rendering.IURAdapter do
     |> Map.fetch!(:attributes)
   end
 
+  defp base_attributes(:live_session_card, props) do
+    props
+    |> live_session_card_opts()
+    |> IURComponents.live_session_card()
+    |> Map.fetch!(:attributes)
+  end
+
   defp base_attributes(:pipeline_stepper_horizontal = kind, props) do
     component_attributes(
       kind,
@@ -1341,6 +1371,60 @@ defmodule AshUI.Rendering.IURAdapter do
     |> compact_map()
   end
 
+  defp live_session_card_opts(props) do
+    live_session = props |> fetch(:live_session, %{}) |> normalize_map()
+
+    %{
+      session_id:
+        first_present(live_session, [:session_id]) ||
+          first_present(props, [:session_id]),
+      actor_handle:
+        first_present(live_session, [:actor_handle]) ||
+          first_present(props, [:actor_handle]),
+      status:
+        normalize_existing_atom(
+          first_present(live_session, [:status]) ||
+            first_present(props, [:status]) ||
+            :running
+        ),
+      status_version:
+        first_present(live_session, [:status_version]) ||
+          first_present(props, [:status_version]),
+      tools_count:
+        first_present(live_session, [:tools_count]) ||
+          first_present(props, [:tools_count]),
+      edits_count:
+        first_present(live_session, [:edits_count]) ||
+          first_present(props, [:edits_count]),
+      tokens_consumed:
+        first_present(live_session, [:tokens_consumed]) ||
+          first_present(props, [:tokens_consumed]),
+      started_at:
+        first_present(live_session, [:started_at]) ||
+          first_present(props, [:started_at]),
+      current_step:
+        first_present(live_session, [:current_step]) ||
+          first_present(props, [:current_step]),
+      current_task_title:
+        first_present(live_session, [:current_task_title]) ||
+          first_present(props, [:current_task_title]),
+      now_streaming:
+        first_present(live_session, [:now_streaming]) ||
+          first_present(props, [:now_streaming]),
+      recent_events:
+        first_present(live_session, [:recent_events]) ||
+          fetch(props, :recent_events, []),
+      pinned?:
+        boolean_present(live_session, [:pinned?], boolean_present(props, [:pinned?], false)),
+      pin_intent: first_present(props, [:pin_intent]) || :pin_toggled,
+      interrupt_intent: first_present(props, [:interrupt_intent]) || :interrupted,
+      expanded_recent_intent: first_present(props, [:expanded_recent_intent]) || :expanded_recent,
+      interactions: fetch(props, :interactions),
+      interaction: fetch(props, :interaction)
+    }
+    |> compact_map()
+  end
+
   defp normalize_heading_segments(props) do
     case fetch(props, :segments) do
       segments when is_list(segments) ->

lib/ash_ui/rendering/live_ui_adapter.ex

@@ -1090,6 +1090,92 @@ defmodule AshUI.Rendering.LiveUIAdapter do
     """
   end
 
+  defp generate_heex(%{"type" => "live_session_card"} = iur, _opts) do
+    props = iur["props"] || %{}
+    live_session = prop(props, "live_session", props) |> normalize_item()
+
+    session_id = escaped_text_prop(live_session, "session_id", "")
+    actor_handle = escaped_text_prop(live_session, "actor_handle", "")
+    status = escaped_text_prop(live_session, "status", "running")
+    status_version = numeric_value(live_session, "status_version", 0)
+    tools_count = numeric_value(live_session, "tools_count", 0)
+    edits_count = numeric_value(live_session, "edits_count", 0)
+    tokens_consumed = numeric_value(live_session, "tokens_consumed", 0)
+    started_at = escaped_text_prop(live_session, "started_at", "")
+    current_step = escaped_text_prop(live_session, "current_step")
+    current_task_title = escaped_text_prop(live_session, "current_task_title")
+    now_streaming = escaped_text_prop(live_session, "now_streaming")
+    pinned? = truthy_prop(live_session, "pinned?", false)
+    iur_id = iur["id"] || iur[:id] || "live-session-card"
+
+    recent_events =
+      live_session
+      |> prop("recent_events", [])
+      |> List.wrap()
+      |> Enum.take(5)
+      |> Enum.map_join(fn event ->
+        event = normalize_item(event)
+        kind = escaped_text_prop(event, "kind", "")
+        body = escaped_text_prop(event, ["body", "body_fragment", "fragment"], "")
+
+        """
+        <li class="ash-live-session-card__recent-item" data-event-kind="#{kind}">
+          <span class="ash-live-session-card__recent-kind">#{kind}</span>
+          <span class="ash-live-session-card__recent-body">#{body}</span>
+        </li>
+        """
+      end)
+
+    task_html =
+      cond do
+        current_task_title ->
+          ~s(<p class="ash-live-session-card__task">#{current_task_title}</p>)
+
+        current_step ->
+          ~s(<p class="ash-live-session-card__task">#{current_step}</p>)
+
+        true ->
+          ""
+      end
+
+    now_streaming_html =
+      if now_streaming do
+        """
+        <div class="ash-live-session-card__now-streaming" aria-live="polite" aria-atomic="true">
+          <span class="ash-live-session-card__live-indicator" aria-hidden="true">LIVE</span>
+          <span class="ash-live-session-card__now-streaming-text">#{now_streaming}</span>
+        </div>
+        """
+      else
+        ""
+      end
+
+    """
+    <article id="#{html_attr(iur_id)}" class="#{css_classes(["ash-live-session-card", "ash-live-session-card--#{status}", pinned? && "is-pinned", prop_class(iur)])}" data-live-ui-widget="live-session-card" data-session-id="#{session_id}" data-status-version="#{status_version}" data-pinned="#{pinned?}"#{style_attr(prop_style(iur))}>
+      <header class="ash-live-session-card__header">
+        <span class="ash-live-session-card__avatar" aria-hidden="true">#{String.first(actor_handle) || "?"}</span>
+        <div class="ash-live-session-card__identity">
+          <h3 class="ash-live-session-card__actor">#{actor_handle}</h3>
+          #{task_html}
+        </div>
+        <span class="ash-live-session-card__status-badge" role="status">#{String.upcase(status)}</span>
+        <time class="ash-live-session-card__duration" datetime="#{started_at}">#{adapter_duration_label(started_at)}</time>
+      </header>
+      <div class="ash-live-session-card__meters">
+        <div class="ash-live-session-card__meter" data-meter="tools"><span class="ash-live-session-card__meter-value">#{tools_count}</span><span class="ash-live-session-card__meter-label">tools</span></div>
+        <div class="ash-live-session-card__meter" data-meter="edits"><span class="ash-live-session-card__meter-value">#{edits_count}</span><span class="ash-live-session-card__meter-label">edits</span></div>
+        <div class="ash-live-session-card__meter" data-meter="tokens"><span class="ash-live-session-card__meter-value">#{tokens_consumed}</span><span class="ash-live-session-card__meter-label">tokens</span></div>
+      </div>
+      #{now_streaming_html}
+      <ol class="ash-live-session-card__recent" aria-label="Recent activity for #{actor_handle}" data-live-ui-intent="expanded_recent">#{recent_events}</ol>
+      <footer class="ash-live-session-card__actions">
+        <button type="button" class="ash-live-session-card__pin" aria-label="#{if pinned?, do: "Unpin", else: "Pin"} #{actor_handle} running session" aria-pressed="#{pinned?}" data-live-ui-intent="pin_toggled">#{if(pinned?, do: "Pinned", else: "Pin")}</button>
+        <button type="button" class="ash-live-session-card__interrupt" aria-label="Interrupt #{actor_handle} running session" data-live-ui-intent="interrupted">Interrupt</button>
+      </footer>
+    </article>
+    """
+  end
+
   defp generate_heex(%{"type" => "confidence_indicator"} = iur, _opts) do
     props = iur["props"] || %{}
 
@@ -3147,6 +3233,24 @@ defmodule AshUI.Rendering.LiveUIAdapter do
 
   defp html_attr(value), do: html_escape(value)
 
+  defp adapter_duration_label(started_at) when is_binary(started_at) do
+    case DateTime.from_iso8601(started_at) do
+      {:ok, dt, _offset} ->
+        diff_seconds = max(DateTime.diff(DateTime.utc_now(), dt, :second), 0)
+
+        cond do
+          diff_seconds < 60 -> "#{diff_seconds}s"
+          diff_seconds < 3_600 -> "#{div(diff_seconds, 60)}m"
+          true -> "#{div(diff_seconds, 3_600)}h"
+        end
+
+      _ ->
+        "running"
+    end
+  end
+
+  defp adapter_duration_label(_started_at), do: "running"
+
   defp html_escape(nil), do: ""
 
   defp html_escape(value) do

packages/live_ui/lib/live_ui/renderer.ex

@@ -495,6 +495,58 @@ defmodule LiveUi.Renderer do
     """
   end
 
+  # NOTE: `:live_session_card` is a canonical component kind, so keep this native
+  # renderer clause before the generic `@component_kinds` fallback.
+  def render(%{element: %Element{kind: :live_session_card}} = assigns) do
+    live_session = get_in(assigns.element.attributes, [:live_session]) || %{}
+    event_target = Map.get(assigns, :event_target)
+
+    assigns =
+      assigns
+      |> assign(:style_attrs, style_rest(assigns.element))
+      |> assign(:live_session, live_session)
+      |> assign(:recent_events, list_value(map_value(live_session, :recent_events, [])))
+      |> assign(
+        :pin_attrs,
+        command_interaction_attrs(assigns.element, event_target, :pin_toggled)
+      )
+      |> assign(
+        :interrupt_attrs,
+        command_interaction_attrs(assigns.element, event_target, :interrupted)
+      )
+      |> assign(
+        :recent_attrs,
+        command_interaction_attrs(assigns.element, event_target, :expanded_recent)
+      )
+
+    ~H"""
+    <LiveUi.Widgets.LiveSessionCard.component
+      id={element_id(@element, "live-session-card")}
+      session_id={string_value(map_value(@live_session, :session_id), "")}
+      actor_handle={string_value(map_value(@live_session, :actor_handle), "")}
+      status={map_value(@live_session, :status, :running)}
+      status_version={integer_value(map_value(@live_session, :status_version), 0)}
+      tools_count={integer_value(map_value(@live_session, :tools_count), 0)}
+      edits_count={integer_value(map_value(@live_session, :edits_count), 0)}
+      tokens_consumed={integer_value(map_value(@live_session, :tokens_consumed), 0)}
+      started_at={map_value(@live_session, :started_at)}
+      current_step={string_optional(map_value(@live_session, :current_step))}
+      current_task_title={string_optional(map_value(@live_session, :current_task_title))}
+      now_streaming={string_optional(map_value(@live_session, :now_streaming))}
+      recent_events={@recent_events}
+      pinned?={boolean_default(map_value(@live_session, :pinned?), false)}
+      pin_attrs={@pin_attrs}
+      interrupt_attrs={@interrupt_attrs}
+      recent_attrs={@recent_attrs}
+      tone={style_tone(@element)}
+      variant={theme_variant(@element)}
+      state={style_state(@element)}
+      class={style_class(@element)}
+      {@style_attrs}
+    />
+    """
+  end
+
   # NOTE: `:workflow_progress_status_card` is a canonical component kind, so keep this native
   # renderer clause before the generic `@component_kinds` fallback.
   def render(%{element: %Element{kind: :workflow_progress_status_card}} = assigns) do
@@ -2083,6 +2135,36 @@ defmodule LiveUi.Renderer do
     end
   end
 
+  defp command_interaction_attrs(%Element{} = element, event_target, command) do
+    case {command_interaction(element, command), event_target} do
+      {%Interaction{} = interaction, target} when not is_nil(target) ->
+        %{
+          :"phx-click" => "canonical_interaction",
+          :"phx-target" => target,
+          :"phx-value-interaction" => encode_interaction(interaction),
+          :"phx-value-element_id" => element_id(element, Atom.to_string(element.kind)),
+          :"phx-value-widget" => Atom.to_string(element.kind),
+          :"phx-value-command" => to_string(command)
+        }
+
+      _ ->
+        %{}
+    end
+  end
+
+  defp command_interaction(%Element{} = element, command) do
+    element.attributes
+    |> Map.get(:interactions, [])
+    |> List.wrap()
+    |> Enum.find(fn
+      %Interaction{family: :command, payload: payload} ->
+        to_string(map_value(payload, :command)) == to_string(command)
+
+      _interaction ->
+        false
+    end)
+  end
+
   defp primary_change_interaction(%Element{} = element) do
     primary_interaction(element, :change)
   end
@@ -2948,6 +3030,9 @@ defmodule LiveUi.Renderer do
   defp map_value(list, key, default) when is_list(list), do: Keyword.get(list, key, default)
   defp map_value(_other, _key, default), do: default
 
+  defp list_value(value) when is_list(value), do: value
+  defp list_value(_value), do: []
+
   defp normalize_key(nil), do: "panel"
 
   defp normalize_key(value) do