From f32ae15c293c80ac3be515b99bbd472b35761ddc Mon Sep 17 00:00:00 2001
From: slhx agent <slhx@users.noreply.github.com>
Date: Fri, 12 Jun 2026 07:39:36 +0200
Subject: [PATCH] feat(api): keep raw tokens out of prelude

Move generated metadata tokens behind a hidden compatibility export and tighten the public contract test so the beginner prelude stays focused on generated authoring, Html, forms, navigation, and IntoEffect.

req: dx/006

req: public_api/005
---
 hemx-test/tests/examples_contract.rs |  6 ++++++
 hemx/src/lib.rs                      | 17 ++++++++++++-----
 2 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/hemx-test/tests/examples_contract.rs b/hemx-test/tests/examples_contract.rs
index 8dd8e8d..6085ce7 100644
--- a/hemx-test/tests/examples_contract.rs
+++ b/hemx-test/tests/examples_contract.rs
@@ -145,6 +145,12 @@ fn public_prelude_does_not_export_low_level_primitives() {
         "ResourceId",
         "EffectBatch",
         "BuildFingerprint",
+        "Atom",
+        "ComponentRef",
+        "EventName",
+        "GeneratedTarget",
+        "Handle",
+        "ParamName",
     ] {
         assert!(
             !exported.contains(&token),
diff --git a/hemx/src/lib.rs b/hemx/src/lib.rs
index a9a1b01..abecb95 100644
--- a/hemx/src/lib.rs
+++ b/hemx/src/lib.rs
@@ -6,10 +6,17 @@
 use hemx_core::{Effect, KeyedSlot, SafeHtml, Slot};
 
 pub use hemx_core::{
-    navigate, push, redirect, replace, Atom, ComponentRef, CssClass, CssClasses, EventName, Form,
-    FormContract, FormControlKind, FormError, FormField, FormModel, FormValue, FromForm,
-    GeneratedTarget, Handle, IntoEffect, ParamName,
+    navigate, push, redirect, replace, CssClass, CssClasses, Form, FormContract, FormControlKind,
+    FormError, FormField, FormModel, FormValue, FromForm, IntoEffect,
 };
+
+/// Generated metadata tokens used by macros, generated code, integrations, and tests.
+///
+/// These stay addressable for compatibility, but ordinary app code should use generated
+/// helpers instead of naming raw handles, params, events, atoms, or component refs.
+/// req: dx/006 req: public_api/005
+#[doc(hidden)]
+pub use hemx_core::{Atom, ComponentRef, EventName, GeneratedTarget, Handle, ParamName};
 pub use hemx_derive::{app, component, form, handler, surface};
 
 /// Advanced/raw hemx primitives used by generated code, integrations, and tests.
@@ -171,8 +178,8 @@ where
 pub mod prelude {
     pub use crate::{page, Html};
     pub use hemx_core::{
-        navigate, push, redirect, replace, Atom, ComponentRef, CssClass, CssClasses, EventName,
-        Form, FormModel, FormValue, Handle, IntoEffect, ParamName,
+        navigate, push, redirect, replace, CssClass, CssClasses, Form, FormModel, FormValue,
+        IntoEffect,
     };
     pub use hemx_derive::{app, component, form, handler, surface};
 }