docs: demote boundary primitives in solid-js

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ryansolid

.changeset/demote-boundary-primitives.md

@@ -0,0 +1,5 @@
+---
+"solid-js": patch
+---
+
+Demote low-level `solid-js` boundary primitive docs in favor of the component APIs.

packages/solid/src/client/hydration.ts

@@ -8,6 +8,7 @@ import {
   isDisposed,
   getNextChildId,
   peekNextChildId,
+  createRevealOrder as coreRevealOrder,
   createMemo as coreMemo,
   createSignal as coreSignal,
   createOptimistic as coreOptimistic,
@@ -32,6 +33,7 @@ import {
   type SourceAccessor,
   type Store,
   type StoreSetter,
+  type RevealOrder,
   createOwner,
   getContext,
   setContext,
@@ -898,42 +900,40 @@ export const createSignal: {
 } = ((...args: any[]) => (_createSignal || coreSignal)(...args)) as any;
 
 /**
- * Lower-level primitive that backs the `<Errored>` flow control.
+ * Internal primitive that backs the `<Errored>` flow control.
  * Catches errors thrown inside `fn` and renders `fallback(error,
  * reset)` instead. `error` is an accessor for the latest captured error;
  * `reset()` recomputes the failing sources so the boundary can attempt to recover.
  *
- * App code should use `<Errored fallback={...}>` directly — reach for
- * this only when authoring a custom boundary component.
+ * App code should use `<Errored fallback={...}>` directly. This primitive is
+ * kept exported for renderer, test, and compatibility use, but it is not part
+ * of the recommended application authoring surface.
  *
  * **Hydration:** if the server serialized an error for this boundary,
  * the client re-throws it on the first hydration pass so `fallback`
  * renders the same content the server emitted.
  *
- * @example
- * ```tsx
- * // Custom boundary built on the primitive — adds telemetry around the
- * // canonical `<Errored>` shape.
- * function TracedErrored(props: {
- *   fallback: (e: () => unknown) => JSX.Element;
- *   children: JSX.Element;
- * }): JSX.Element {
- *   return createErrorBoundary(
- *     () => props.children,
- *     (err, reset) => {
- *       reportError(err());
- *       return props.fallback(err);
- *     }
- *   ) as unknown as JSX.Element;
- * }
- * ```
+ * @internal
  */
 export const createErrorBoundary = ((...args: any[]) =>
   (_createErrorBoundary || coreErrorBoundary)(...args)) as <U>(
   fn: () => any,
   fallback: (error: Accessor<unknown>, reset: () => void) => U
 ) => () => unknown;
 
+/**
+ * Internal primitive that backs `<Reveal>` coordination of sibling loading
+ * boundaries. App code should use `<Reveal>` directly.
+ *
+ * @internal
+ */
+export function createRevealOrder<T>(
+  fn: () => T,
+  options?: { order?: () => RevealOrder; collapsed?: () => boolean }
+): T {
+  return coreRevealOrder(fn, options);
+}
+
 /**
  * Creates an optimistic signal — a `Signal<T>` whose writes are
  * tentative inside an `action` transition: they show up immediately,
@@ -1308,22 +1308,14 @@ function scheduleResumeAfterAssets(
 }
 
 /**
- * Lower-level primitive that backs the `<Loading>` component. Returns a
+ * Internal primitive that backs the `<Loading>` component. Returns a
  * computation that yields `fallback()` while async reads inside `fn` are
- * pending, and `fn()` once they have settled. Most callers should use
- * `<Loading>` directly; this is exposed for renderers and library authors.
+ * pending, and `fn()` once they have settled. App code should use `<Loading>`
+ * directly. This primitive is kept exported for renderer, test, and
+ * compatibility use, but it is not part of the recommended application
+ * authoring surface.
  *
- * @example
- * ```tsx
- * // Custom boundary component built on the primitive. App code uses
- * // `<Loading fallback={…}>` directly.
- * function MyLoading(props: { fallback: JSX.Element; children: JSX.Element }): JSX.Element {
- *   return createLoadingBoundary(
- *     () => props.children,
- *     () => props.fallback
- *   ) as unknown as JSX.Element;
- * }
- * ```
+ * @internal
  */
 export function createLoadingBoundary(
   fn: () => any,

packages/solid/src/index.ts

@@ -5,7 +5,6 @@ export {
   action,
   createOwner,
   createReaction,
-  createRevealOrder,
   createRoot,
   createTrackedEffect,
   deep,
@@ -92,6 +91,7 @@ export {
   enableHydration,
   createErrorBoundary,
   createLoadingBoundary,
+  createRevealOrder,
   createMemo,
   createSignal,
   createStore,

packages/solid/src/server/hydration.ts

@@ -65,14 +65,6 @@ export function ssrHandleError(err: any) {
   throw err;
 }
 
-/**
- * Tracks all resources inside a component and renders a fallback until they are all resolved
- *
- * On the server, this is SSR-aware: it handles async mode (streaming) by registering
- * fragments and resolving asynchronously, and sync mode by serializing fallback markers.
- *
- * @description https://docs.solidjs.com/reference/components/suspense
- */
 export function createLoadingBoundary(
   fn: () => any,
   fallback: () => any,