@@ -511,33 +511,23 @@ export function* expandSegments(
511511 }
512512
513513 if ( segment . name === "Capture" ) {
514- const captureResult = yield * expandCapture (
515- segment ,
516- parentMeta ,
517- parentProps ,
518- hideSet ,
519- counter ,
514+ // No raise() here: expandCapture reports the errors it creates, and
515+ // its body settled its own (§6.9).
516+ result . push (
517+ ...( yield * expandCapture ( segment , parentMeta , parentProps , hideSet , counter ) ) ,
520518 ) ;
521- for ( const captureSegment of captureResult ) {
522- result . push ( yield * raise ( captureSegment ) ) ;
523- }
524519 break ;
525520 }
526521
527522 if ( segment . name === "Each" ) {
528- const eachResult = yield * expandEach ( segment , parentMeta , parentProps , hideSet , counter ) ;
529- for ( const eachSegment of eachResult ) {
530- if ( eachSegment . type === "error" ) {
531- result . push ( yield * raise ( eachSegment ) ) ;
532- } else {
533- result . push ( eachSegment ) ;
534- }
535- }
523+ // Same as <Capture>: expandEach reports its own errors and hands the
524+ // body's back untouched (§6.9).
525+ result . push ( ...( yield * expandEach ( segment , parentMeta , parentProps , hideSet , counter ) ) ) ;
536526 break ;
537527 }
538528
539529 if ( segment . name === "If" ) {
540- // No raise() here, unlike the branches above: expandIf reports the
530+ // No raise() here, like the branches above: expandIf reports the
541531 // errors it creates, and the selected branch settled its own (§6.9).
542532 result . push ( ...( yield * expandIf ( segment , parentMeta , parentProps , hideSet , counter ) ) ) ;
543533 break ;
@@ -574,11 +564,13 @@ export function* expandSegments(
574564 counter ,
575565 segment . projectedEnv ,
576566 ) ;
577- // Consumer boundary: re-raise transported error segments under the
578- // ambient policy before appending them (spec §6.9).
567+ // Consumer boundary: the callee reported these where they were created,
568+ // under whatever policy its body ran — an `<Output>` region collects,
569+ // documentation throws. Settling them here applies this caller's policy
570+ // without reporting them a second time (spec §6.9).
579571 for ( const expandedSegment of expanded ) {
580572 if ( expandedSegment . type === "error" ) {
581- result . push ( yield * raise ( expandedSegment ) ) ;
573+ result . push ( yield * settle ( expandedSegment ) ) ;
582574 } else {
583575 result . push ( expandedSegment ) ;
584576 }
@@ -676,6 +668,19 @@ function captureError(message: string): ErrorSegment {
676668 return { type : "error" , message, source : "Capture" } ;
677669}
678670
671+ /**
672+ * Capture the rendered body into an `as` binding (spec §6.5 `<Capture>`).
673+ *
674+ * Like `<If>`, it is not an observation boundary. Errors it creates itself — a
675+ * missing or invalid `as`, an unknown prop, an empty body — are reported here,
676+ * exactly once. Body segments come back from `expandSegments` already reported
677+ * where they were produced, and are handed on untouched: a failing element
678+ * inside a capture settles once, exactly as it would inline.
679+ *
680+ * A capture never swallows an error. When the body produced one, `as` creates no
681+ * binding and the error segments stand in place of the capture, so the reader
682+ * sees the failure instead of a binding holding a diagnostic as its text.
683+ */
679684function * expandCapture (
680685 segment : Extract < Segment , { type : "component" } > ,
681686 parentMeta : Record < string , unknown > ,
@@ -684,35 +689,39 @@ function* expandCapture(
684689 counter : BlockCounter ,
685690) : Operation < ErrorSegment [ ] > {
686691 if ( segment . selfClosing || segment . children . length === 0 ) {
687- return [ captureError ( '<Capture> must have content. Use <Capture as="x">...</Capture>.' ) ] ;
692+ return [
693+ yield * raise ( captureError ( '<Capture> must have content. Use <Capture as="x">...</Capture>.' ) ) ,
694+ ] ;
688695 }
689696
690697 const propNames = Object . keys ( segment . props ) ;
691698 if ( propNames . some ( ( name ) => name !== "as" && name !== "select" ) ) {
692- return [ captureError ( '<Capture> only accepts "as" and "select" props.' ) ] ;
699+ return [ yield * raise ( captureError ( '<Capture> only accepts "as" and "select" props.' ) ) ] ;
693700 }
694701
695702 const expressionNames = Object . keys ( segment . expressions ) ;
696703 if ( expressionNames . length > 0 ) {
697704 if ( expressionNames . includes ( "as" ) ) {
698- return [ captureError ( '<Capture as={...}> is invalid: "as" must be a string literal.' ) ] ;
705+ return [
706+ yield * raise ( captureError ( '<Capture as={...}> is invalid: "as" must be a string literal.' ) ) ,
707+ ] ;
699708 }
700709 if ( ! expressionNames . every ( ( n ) => n === "select" ) ) {
701- return [ captureError ( '<Capture> only accepts "as" and "select" props.' ) ] ;
710+ return [ yield * raise ( captureError ( '<Capture> only accepts "as" and "select" props.' ) ) ] ;
702711 }
703712 }
704713
705714 if ( segment . props . as === undefined ) {
706- return [ captureError ( '<Capture> requires an "as" prop (non-empty string).' ) ] ;
715+ return [ yield * raise ( captureError ( '<Capture> requires an "as" prop (non-empty string).' ) ) ] ;
707716 }
708717
709718 const asBinding = validateBindingName ( segment . props . as ) ;
710719 if ( ! asBinding . ok ) {
711- return [ captureError ( asBinding . error . message ) ] ;
720+ return [ yield * raise ( captureError ( asBinding . error . message ) ) ] ;
712721 }
713722 const bindingName = asBinding . value ;
714723 if ( bindingName === undefined ) {
715- return [ captureError ( '<Capture> requires an "as" prop (non-empty string).' ) ] ;
724+ return [ yield * raise ( captureError ( '<Capture> requires an "as" prop (non-empty string).' ) ) ] ;
716725 }
717726
718727 const expandedChildren = yield * expandSegments (
@@ -723,9 +732,9 @@ function* expandCapture(
723732 counter ,
724733 ) ;
725734
726- // Consumer boundary (spec §6.9): a capture never swallows an error. Hand the
727- // error segments back before rendering or `select` folds them into text, so
728- // expandSegments applies the ambient policy and the binding stays unset .
735+ // The body reported these where they were created (§6.9). They are returned
736+ // before rendering or `select` folds them into text, so the binding stays
737+ // unset and the diagnostics reach the document unchanged .
729738 const errors : ErrorSegment [ ] = [ ] ;
730739 for ( const child of expandedChildren ) {
731740 if ( child . type === "error" ) {
@@ -752,7 +761,7 @@ function* expandCapture(
752761
753762 const bindingEnv = yield * env ;
754763 if ( ! bindingEnv ) {
755- return [ captureError ( "<Capture> requires an evaluation environment." ) ] ;
764+ return [ yield * raise ( captureError ( "<Capture> requires an evaluation environment." ) ) ] ;
756765 }
757766 bindingEnv . values [ bindingName ] = captured ;
758767 return [ ] ;
@@ -764,6 +773,17 @@ function eachError(message: string): ErrorSegment {
764773
765774const EACH_PROPS = new Set ( [ "in" , "let" , "as" ] ) ;
766775
776+ /**
777+ * Expand the body once per item, binding `let` to the item (spec §6.5 `<Each>`).
778+ *
779+ * Like `<If>` and `<Loop>`, it is not an observation boundary: errors it creates
780+ * itself — an unknown prop, a `let`/`as`/`in` that does not hold up — are
781+ * reported here, exactly once, and every iteration's segments come back already
782+ * reported and are handed on untouched.
783+ *
784+ * With `as`, a capture never swallows an error: when any iteration produced one,
785+ * no binding is created and the error segments stand in place of the capture.
786+ */
767787function * expandEach (
768788 segment : Extract < Segment , { type : "component" } > ,
769789 parentMeta : Record < string , unknown > ,
@@ -775,30 +795,34 @@ function* expandEach(
775795 ( n ) => ! EACH_PROPS . has ( n ) ,
776796 ) ;
777797 if ( unknownProp !== undefined ) {
778- return [ eachError ( `<Each> only accepts "in", "let", and "as" props. Got: "${ unknownProp } ".` ) ] ;
798+ return [
799+ yield * raise (
800+ eachError ( `<Each> only accepts "in", "let", and "as" props. Got: "${ unknownProp } ".` ) ,
801+ ) ,
802+ ] ;
779803 }
780804
781805 if ( "let" in segment . expressions ) {
782- return [ eachError ( 'Prop "let" on <Each /> must be a string literal.' ) ] ;
806+ return [ yield * raise ( eachError ( 'Prop "let" on <Each /> must be a string literal.' ) ) ] ;
783807 }
784808 if ( segment . props . let === undefined ) {
785- return [ eachError ( '<Each> requires a "let" prop (the item binding name).' ) ] ;
809+ return [ yield * raise ( eachError ( '<Each> requires a "let" prop (the item binding name).' ) ) ] ;
786810 }
787811 const letBinding = validateBindingName ( segment . props . let ) ;
788812 if ( ! letBinding . ok ) {
789- return [ eachError ( `Prop "let" on <Each /> ${ letBinding . error . message } ` ) ] ;
813+ return [ yield * raise ( eachError ( `Prop "let" on <Each /> ${ letBinding . error . message } ` ) ) ] ;
790814 }
791815 const name = letBinding . value ;
792816 if ( name === undefined ) {
793- return [ eachError ( '<Each> requires a "let" prop (the item binding name).' ) ] ;
817+ return [ yield * raise ( eachError ( '<Each> requires a "let" prop (the item binding name).' ) ) ] ;
794818 }
795819
796820 if ( "as" in segment . expressions ) {
797- return [ eachError ( 'Prop "as" on <Each /> must be a string literal.' ) ] ;
821+ return [ yield * raise ( eachError ( 'Prop "as" on <Each /> must be a string literal.' ) ) ] ;
798822 }
799823 const asResult = validateBindingName ( segment . props . as ) ;
800824 if ( ! asResult . ok ) {
801- return [ eachError ( `Prop "as" on <Each /> ${ asResult . error . message } ` ) ] ;
825+ return [ yield * raise ( eachError ( `Prop "as" on <Each /> ${ asResult . error . message } ` ) ) ] ;
802826 }
803827 const asBinding = asResult . value ;
804828
@@ -815,13 +839,13 @@ function* expandEach(
815839 ) ;
816840 items = resolved . in ;
817841 } catch ( error ) {
818- return [ eachError ( error instanceof Error ? error . message : String ( error ) ) ] ;
842+ return [ yield * raise ( eachError ( error instanceof Error ? error . message : String ( error ) ) ) ] ;
819843 }
820844 } else {
821- return [ eachError ( '<Each> requires an "in" prop (the array to iterate).' ) ] ;
845+ return [ yield * raise ( eachError ( '<Each> requires an "in" prop (the array to iterate).' ) ) ] ;
822846 }
823847 if ( ! Array . isArray ( items ) ) {
824- return [ eachError ( 'Prop "in" on <Each /> must resolve to an array.' ) ] ;
848+ return [ yield * raise ( eachError ( 'Prop "in" on <Each /> must resolve to an array.' ) ) ] ;
825849 }
826850
827851 // Effective caller env honors projection through <Content />, mirroring
@@ -858,18 +882,19 @@ function* expandEach(
858882 return out ;
859883 }
860884
861- // Consumer boundary (spec §6.9): a capture never swallows an error. Hand the
862- // error segments back so expandSegments applies the ambient policy exactly
863- // once — a collecting policy keeps them in the document, a throwing policy
864- // aborts — and leave the binding unset either way.
885+ // A capture never swallows an error. The body reported these where they were
886+ // created (§6.9), so they are returned as they are: the diagnostics reach the
887+ // document unchanged and the binding stays unset.
865888 const errors = out . filter ( ( outSegment ) => outSegment . type === "error" ) ;
866889 if ( errors . length > 0 ) {
867890 return errors ;
868891 }
869892
870893 const captureEnv = yield * env ;
871894 if ( ! captureEnv ) {
872- return [ eachError ( 'Prop "as" on <Each /> requires a parent evaluation environment.' ) ] ;
895+ return [
896+ yield * raise ( eachError ( 'Prop "as" on <Each /> requires a parent evaluation environment.' ) ) ,
897+ ] ;
873898 }
874899 captureEnv . values [ asBinding ] = renderSegments ( out ) ;
875900 return [ ] ;
@@ -1658,10 +1683,9 @@ function* expandComponent(
16581683 } ) ;
16591684
16601685 if ( asBinding ) {
1661- // Consumer boundary (spec §6.9): a capture never swallows an error. Hand
1662- // the error segments back so expandSegments applies the ambient policy
1663- // exactly once — a collecting policy keeps them in the document, a
1664- // throwing policy aborts — and leave the binding unset either way.
1686+ // A capture never swallows an error. The body reported these where they
1687+ // were created (§6.9), so they are handed back as they are and the binding
1688+ // stays unset.
16651689 const errors = expanded . filter ( ( capturedSegment ) => capturedSegment . type === "error" ) ;
16661690 if ( errors . length > 0 ) {
16671691 return errors ;
@@ -1826,9 +1850,9 @@ function* expandFunctionComponent(
18261850 return yield * definition . fn ( validatedProps ) ;
18271851 } ) ;
18281852 if ( asBinding ) {
1829- // Consumer boundary (spec §6.9): a capture never swallows an error. Hand
1830- // the content errors back so expandSegments applies the ambient policy
1831- // and leave the binding unset.
1853+ // A capture never swallows an error. The projection reported these where
1854+ // they were created (§6.9), so they are handed back as they are and the
1855+ // binding stays unset.
18321856 if ( contentErrors . length > 0 ) {
18331857 return contentErrors ;
18341858 }
@@ -2529,8 +2553,8 @@ function buildBody(
25292553 * whole body renders (backward compatible). With `<Output>`, only the declared
25302554 * regions render; documentation executes for its side effects under a throwing
25312555 * raise policy (fail-fast) and its rendered result is discarded; output
2532- * regions install a collecting raise that shadows any inherited throwing
2533- * middleware (innermost min runs first), so their errors render as comments .
2556+ * regions set a collecting policy of their own, so their errors render as
2557+ * comments; the caller settles them again on the way out .
25342558 * Regions and documentation run in document order, so output can depend on
25352559 * bindings computed by preceding documentation.
25362560 */
0 commit comments