Expand web_ui widget contracts and integration tests

Author: pcharbon70

packages/web_ui/lib/web_ui/info.ex

@@ -10,6 +10,7 @@ defmodule WebUi.Info do
       namespace: WebUi,
       package_areas: WebUi.package_areas(),
       validation_state: WebUi.Runtime.validation_state(),
+      bridge: bridge_summary(),
       tooling: %{
         workflows: WebUi.Tooling.workflows(),
         mix_tasks: WebUi.Tooling.mix_tasks()
@@ -26,4 +27,27 @@ defmodule WebUi.Info do
       responsibilities: WebUi.Renderer.responsibilities()
     }
   end
+
+  @spec widget_summary(WebUi.Widget.t()) :: map()
+  def widget_summary(%WebUi.Widget{} = widget) do
+    %{
+      id: widget.id,
+      family: widget.family,
+      kind: widget.kind,
+      metadata: widget.metadata,
+      state: widget.state,
+      slots: widget.slots,
+      style_keys: Map.keys(widget.styles),
+      event_keys: Map.keys(widget.events)
+    }
+  end
+
+  @spec bridge_summary() :: map()
+  def bridge_summary do
+    %{
+      boundaries: WebUi.Reference.browser_bridge_boundaries(),
+      frontend_modules: WebUi.Frontend.modules(),
+      server_modules: WebUi.Server.modules()
+    }
+  end
 end

packages/web_ui/lib/web_ui/reference.ex

@@ -8,6 +8,11 @@ defmodule WebUi.Reference do
     WebUi.Widgets.families()
   end
 
+  @spec widget_contract() :: map()
+  def widget_contract do
+    WebUi.Widget.contract()
+  end
+
   @spec runtime_modules() :: [module()]
   def runtime_modules do
     WebUi.Runtime.modules()
@@ -31,18 +36,25 @@ defmodule WebUi.Reference do
     WebUi.Runtime.assumptions()
   end
 
+  @spec browser_bridge_boundaries() :: [atom()]
+  def browser_bridge_boundaries do
+    [:hydration_envelope, :event_envelope, :acknowledgement]
+  end
+
   @spec package_reference() :: map()
   def package_reference do
     %{
       package: WebUi,
       widgets: %{
         families: widget_families(),
-        modules: WebUi.Widgets.modules()
+        modules: WebUi.Widgets.modules(),
+        contract: widget_contract()
       },
       runtime: %{
         capabilities: WebUi.Runtime.capabilities(),
         modules: runtime_modules(),
-        assumptions: runtime_assumptions()
+        assumptions: runtime_assumptions(),
+        bridge_boundaries: browser_bridge_boundaries()
       },
       renderer: %{
         accepts: WebUi.Renderer.accepts(),

packages/web_ui/lib/web_ui/widget.ex

@@ -9,6 +9,9 @@ defmodule WebUi.Widget do
           id: String.t() | atom() | nil,
           family: family(),
           kind: atom(),
+          metadata: map(),
+          state: map(),
+          slots: [atom() | String.t()],
           attributes: map(),
           styles: map(),
           events: map(),
@@ -18,11 +21,25 @@ defmodule WebUi.Widget do
   defstruct id: nil,
             family: :content,
             kind: :text,
+            metadata: %{},
+            state: %{},
+            slots: [:default],
             attributes: %{},
             styles: %{},
             events: %{},
             children: []
 
+  @spec contract() :: map()
+  def contract do
+    %{
+      metadata: [:label, :description, :role, :variant],
+      state: [:disabled, :selected, :expanded, :focused],
+      slots: [:default],
+      styles: [:tone, :size, :spacing, :surface],
+      events: [:click, :change, :submit, :navigation]
+    }
+  end
+
   @spec new(atom(), keyword() | map()) :: t()
   def new(kind, attrs \\ %{}) when is_atom(kind) do
     attrs = normalize_map(attrs)
@@ -31,6 +48,9 @@ defmodule WebUi.Widget do
       id: Map.get(attrs, :id) || Map.get(attrs, "id"),
       family: Map.get(attrs, :family) || Map.get(attrs, "family") || family_for(kind),
       kind: kind,
+      metadata: normalize_map(Map.get(attrs, :metadata) || Map.get(attrs, "metadata")),
+      state: normalize_map(Map.get(attrs, :state) || Map.get(attrs, "state")),
+      slots: normalize_slots(Map.get(attrs, :slots) || Map.get(attrs, "slots") || [:default]),
       attributes: normalize_map(Map.get(attrs, :attributes) || Map.get(attrs, "attributes")),
       styles: normalize_map(Map.get(attrs, :styles) || Map.get(attrs, "styles")),
       events: normalize_map(Map.get(attrs, :events) || Map.get(attrs, "events")),
@@ -48,17 +68,30 @@ defmodule WebUi.Widget do
     %{widget | styles: Map.put(widget.styles, key, value)}
   end
 
+  @spec put_state(t(), atom() | String.t(), term()) :: t()
+  def put_state(%__MODULE__{} = widget, key, value) do
+    %{widget | state: Map.put(widget.state, key, value)}
+  end
+
   @spec put_event(t(), atom() | String.t(), map()) :: t()
   def put_event(%__MODULE__{} = widget, key, value) when is_map(value) do
     %{widget | events: Map.put(widget.events, key, value)}
   end
 
+  @spec put_slot(t(), atom() | String.t()) :: t()
+  def put_slot(%__MODULE__{} = widget, slot) when is_atom(slot) or is_binary(slot) do
+    %{widget | slots: Enum.uniq(widget.slots ++ [slot])}
+  end
+
   @spec serialize(t()) :: map()
   def serialize(%__MODULE__{} = widget) do
     %{
       id: widget.id,
       family: widget.family,
       kind: widget.kind,
+      metadata: widget.metadata,
+      state: widget.state,
+      slots: widget.slots,
       attributes: widget.attributes,
       styles: widget.styles,
       events: widget.events,
@@ -75,6 +108,9 @@ defmodule WebUi.Widget do
   defp normalize_map(map) when is_map(map), do: Map.new(map)
   defp normalize_map(list) when is_list(list), do: Enum.into(list, %{})
 
+  defp normalize_slots(slots) when is_list(slots), do: slots
+  defp normalize_slots(_slots), do: [:default]
+
   defp normalize_children(children) when is_list(children) do
     Enum.map(children, fn
       %__MODULE__{} = child ->

packages/web_ui/lib/web_ui/widgets.ex

@@ -21,6 +21,7 @@ defmodule WebUi.Widgets do
   def text(id, content, opts \\ []) do
     Widget.new(:text,
       id: id,
+      metadata: %{label: "text"},
       attributes: %{content: content},
       styles: Keyword.get(opts, :styles, %{})
     )
@@ -30,6 +31,8 @@ defmodule WebUi.Widgets do
   def button(id, label, opts \\ []) do
     Widget.new(:button,
       id: id,
+      metadata: %{label: label, role: :action},
+      state: %{disabled: Keyword.get(opts, :disabled, false)},
       attributes: %{label: label},
       styles: Keyword.get(opts, :styles, %{}),
       events: build_events(opts)
@@ -40,6 +43,8 @@ defmodule WebUi.Widgets do
   def stack(id, children, opts \\ []) do
     Widget.new(:stack,
       id: id,
+      metadata: %{label: "stack"},
+      slots: [:default],
       attributes: %{direction: Keyword.get(opts, :direction, :column)},
       styles: Keyword.get(opts, :styles, %{}),
       children: children
@@ -50,6 +55,8 @@ defmodule WebUi.Widgets do
   def panel(id, title, children, opts \\ []) do
     Widget.new(:panel,
       id: id,
+      metadata: %{label: title, role: :panel},
+      slots: [:header, :body],
       attributes: %{title: title},
       styles: Keyword.get(opts, :styles, %{}),
       children: children

packages/web_ui/test/web_ui/phase_one_integration_test.exs

@@ -0,0 +1,73 @@
+defmodule WebUi.PhaseOneIntegrationTest do
+  use ExUnit.Case, async: true
+
+  alias UnifiedIUR.Element
+  alias WebUi.FrontendRuntime.{Boot, Message}
+  alias WebUi.ServerRuntime
+
+  test "package and split runtime entrypoints stay available without owning application startup" do
+    assert WebUi.server() == WebUi.Server
+    assert WebUi.frontend() == WebUi.Frontend
+    assert WebUi.runtime() == WebUi.Runtime
+    assert WebUi.renderer() == WebUi.Renderer
+    assert WebUi.transport() == WebUi.Transport
+  end
+
+  test "minimal native screen mounts, hydrates, and renders through the backbone" do
+    assert {:ok, runtime_state} =
+             WebUi.Runtime.mount_native_screen(WebUi.Examples.native_counter_screen())
+
+    envelope = ServerRuntime.frontend_envelope(runtime_state)
+    assert {:ok, frontend_model} = Boot.hydrate_message(envelope)
+
+    assert runtime_state.rendered_tree.kind == :stack
+    assert frontend_model.tree.kind == :stack
+    assert frontend_model.boundary_mode == :native_local
+  end
+
+  test "canonical screens reuse the same runtime and frontend flow" do
+    element =
+      Element.new(:widget, :button,
+        id: :phase_one_button,
+        attributes: %{label: "Continue"}
+      )
+
+    assert {:ok, runtime_state} = WebUi.Runtime.mount_iur_screen(element, runtime_id: "phase-one")
+    assert {:ok, frontend_model} = WebUi.Runtime.hydrate_frontend(runtime_state)
+
+    assert runtime_state.boundary_mode == :canonical_boundary
+    assert frontend_model.tree.kind == :button
+  end
+
+  test "malformed widget declarations, hydration payloads, and wiring fail with deterministic diagnostics" do
+    assert {:error, %ServerRuntime.Error{reason: :invalid_screen}} =
+             WebUi.Runtime.mount_native_screen(%{id: :broken, title: "Broken"})
+
+    assert {:error, %WebUi.FrontendRuntime.Error{reason: :invalid_hydration_payload}} =
+             Boot.hydrate(%{runtime_id: "missing"})
+
+    assert {:error, %ServerRuntime.Error{reason: :unsupported_frontend_message}} =
+             ServerRuntime.receive_frontend_message(
+               %WebUi.ServerRuntime.State{
+                 runtime_id: "phase-one",
+                 rendered_tree: WebUi.Widgets.text(:id, "ok")
+               },
+               Message.new(:hydrate, %{runtime_id: "phase-one"})
+             )
+  end
+
+  test "reference helpers and inspection surfaces expose phase one boundaries without renderer coupling" do
+    reference = WebUi.reference()
+    info = WebUi.info()
+
+    widget =
+      WebUi.Widgets.button(:save, "Save",
+        on_click: %{family: :click, intent: :save, boundary: :local}
+      )
+
+    assert :hydration_envelope in reference.runtime.bridge_boundaries
+    assert reference.widgets.contract.metadata == [:label, :description, :role, :variant]
+    assert info.bridge.boundaries == [:hydration_envelope, :event_envelope, :acknowledgement]
+    assert WebUi.Info.widget_summary(widget).event_keys == [:click]
+  end
+end