feat(composition): add scoped default children

Author: PatrickJS

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.11.24 - 2026-06-21
+
+- Added scoped default children fragments for `this.render(Component, props,
+  children)`, including lazy children factories, single-consumption checks, and
+  duplicate source validation.
+- Added component tests proving static children, lazy nested component children,
+  escaped string children, duplicate children errors, and cleanup for handlers
+  and signals created while rendering children.
+- Updated framework declarations and type fixtures so components can type
+  optional `Children` props while callers use the third render argument instead
+  of authoring `props.children`.
+- Documented the released default-children contract in the component README and
+  component-system spec while keeping slots as the post-mount replacement
+  primitive.
+- Bundle size from bundled TypeScript source: `browser.ts` raw 230,250 B (230.3 KB / 0.230 MB), gzip 43,813 B (43.8 KB / 0.044 MB), br 36,215 B (36.2 KB / 0.036 MB) -> `browser.min.js` raw 98,493 B (98.5 KB / 0.098 MB), gzip 29,286 B (29.3 KB / 0.029 MB), br 25,793 B (25.8 KB / 0.026 MB); delta raw -131,757 B (-131.8 KB / -0.132 MB), gzip -14,527 B (-14.5 KB / -0.015 MB), br -10,422 B (-10.4 KB / -0.010 MB).
+
 ## 0.11.23 - 2026-06-21
 
 - Added first-class JSX type profiles for runtime/no-build and

README.md

@@ -1147,7 +1147,7 @@ Component helpers:
 | `this.effect(fn)` | Scoped effect with cleanup |
 | `this.handler(name, fn)` | Scoped named handler registry entry |
 | `this.handler(fn)` | Generated scoped handler registry entry |
-| `this.render(Component, props)` | Child fragment rendering |
+| `this.render(Component, props, children?)` | Child fragment rendering with optional default children |
 | `this.slot(Component, propsOrFn)` | Child component outlet using an `on:attach` target |
 | `this.suspense(signalRef, views)` | Async boundary template helper |
 | `this.on(event, fn)` | Fragment lifecycle fallback for `attach`, `visible`, and `destroy` |
@@ -1196,6 +1196,45 @@ this.suspense(product, (product) => html`
 `this.suspense(...)` is not React Suspense. It does not throw promises,
 hydrate, diff, rerender a component tree, or emit a wrapper element.
 
+Default children are a scoped fragment owned by the framework. Pass them as the
+third `this.render(...)` argument, then interpolate `children` in the child
+component:
+
+```js
+const Card = component(function Card({ title, children }) {
+  return html`
+    <article>
+      <h2>${title}</h2>
+      ${children}
+    </article>
+  `;
+});
+
+const Page = component(function Page() {
+  return html`
+    ${this.render(Card, { title: "Status" }, html`
+      <p>Ready</p>
+    `)}
+  `;
+});
+```
+
+Children can also be lazy when the caller supplies a factory. The factory runs
+only if the child component interpolates `children`, and any nested components
+or handlers created while rendering the fragment are cleaned up with the
+consuming component fragment:
+
+```js
+this.render(Card, { title: "Status" }, function children() {
+  return html`<p>${this.render(Badge, { label: "Live" })}</p>`;
+});
+```
+
+Do not pass `children` in the props object when also using the third argument.
+Default children are consumed once by interpolation; use `this.slot(...)` for
+post-mount replacement and use ordinary props when the child needs data from the
+caller.
+
 Component-scoped signals and handlers are unregistered when the mounted
 fragment is destroyed. `loader.swap(...)` cleans up old DOM bindings and mounted
 component fragments under the swapped boundary before inserting the new HTML.

examples/size/server-call-button/scenario.json

@@ -7,6 +7,6 @@
   ],
   "budget": {
     "mode": "baseline",
-    "maxGzipBytes": 29500
+    "maxGzipBytes": 29600
   }
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@async/framework",
-  "version": "0.11.23",
+  "version": "0.11.24",
   "description": "No-build Loader app runtime with browser and server entrypoints, signals, command events, route partials, cache split, SSR activation, and streaming boundaries.",
   "type": "module",
   "private": true,

scripts/build-framework-bundle.js

@@ -261,7 +261,8 @@ const browserDtsOutput = [
   "}",
   "",
   "export type TemplatePrimitive = string | number | boolean | null | undefined;",
-  "export type TemplateLike = TemplateResult | TemplatePrimitive | Node | TemplateLike[];",
+  "export type TemplateLike = TemplateResult | Children | TemplatePrimitive | Node | TemplateLike[];",
+  "export type ChildrenInput = TemplateLike | ((this: ComponentContext) => TemplateLike);",
   "export interface LazyDescriptor {",
   "  url: string;",
   "  [key: string]: unknown;",
@@ -282,6 +283,10 @@ const browserDtsOutput = [
   "  readonly values: readonly unknown[];",
   "}",
   "",
+  "export interface Children {",
+  "  readonly __asyncChildrenBrand: true;",
+  "}",
+  "",
   "export type SchedulerStrategy = \"microtask\" | \"manual\";",
   "export type SchedulerPhase = \"binding\" | \"lifecycle\" | \"effect\" | \"async\" | \"post\" | string;",
   "export interface SchedulerJob {",
@@ -682,7 +687,7 @@ const browserDtsOutput = [
   "  effect(fn: (this: ComponentContext) => unknown): Cleanup;",
   "  handler(fn: HandlerFunction): string;",
   "  handler(name: string, fn: HandlerFunction): string;",
-  "  render<TProps extends Record<string, unknown> = Record<string, unknown>>(Child: ComponentFunction<TProps>, props?: TProps): TemplateLike;",
+  "  render<TProps extends object = Record<string, unknown>>(Child: ComponentFunction<TProps>, props?: Omit<TProps, \"children\">, children?: ChildrenInput): TemplateLike;",
   "  suspense(signalRef: Pick<SignalRef, \"id\">, views: SuspenseViews | SuspenseReadyView): TemplateLike;",
   "  on(eventName: \"intersect\", fn: IntersectionCallback): void;",
   "  on(eventName: \"intersect\", options: IntersectionOptions | undefined | null, fn: IntersectionCallback): void;",
@@ -693,7 +698,7 @@ const browserDtsOutput = [
   "  intersect(target: Element, options: IntersectionOptions | undefined | null, fn: IntersectionCallback): Cleanup;",
   "}",
   "",
-  "export type ComponentFunction<TProps extends Record<string, unknown> = Record<string, unknown>> = (this: ComponentContext, props: TProps) => TemplateLike;",
+  "export type ComponentFunction<TProps extends object = Record<string, unknown>> = (this: ComponentContext, props: TProps) => TemplateLike;",
   "export type SuspenseReadyView = (this: ComponentContext, signalRef: Pick<SignalRef, \"id\">) => TemplateLike;",
   "export interface SuspenseViews {",
   "  loading?: SuspenseReadyView;",
@@ -731,7 +736,7 @@ const browserDtsOutput = [
   "  start(): this;",
   "  scan(rootOrFragment?: Document | Element | DocumentFragment): this;",
   "  swap(boundaryId: string, fragmentOrTemplate: TemplateLike): Element;",
-  "  mount<TProps extends Record<string, unknown> = Record<string, unknown>>(target: Element, Component: ComponentFunction<TProps>, props?: TProps): unknown;",
+  "  mount<TProps extends object = Record<string, unknown>>(target: Element, Component: ComponentFunction<TProps>, props?: TProps): unknown;",
   "  destroy(): void;",
   "}",
   "",
@@ -748,7 +753,7 @@ const browserDtsOutput = [
   "  ready(): Promise<LoaderInstance>;",
   "  scan(rootOrFragment?: Document | Element | DocumentFragment): Promise<LoaderInstance>;",
   "  swap(boundaryId: string, fragmentOrTemplate: TemplateLike): Promise<Element>;",
-  "  mount<TProps extends Record<string, unknown> = Record<string, unknown>>(target: Element, Component: ComponentFunction<TProps>, props?: TProps): Promise<unknown>;",
+  "  mount<TProps extends object = Record<string, unknown>>(target: Element, Component: ComponentFunction<TProps>, props?: TProps): Promise<unknown>;",
   "  inspect(): AsyncLoaderFacadeInspection;",
   "}",
   "",
@@ -1033,16 +1038,18 @@ const browserDtsOutput = [
   "export declare function createBoundaryReceiver(options: BoundaryReceiverOptions): BoundaryReceiver;",
   "export declare function createCacheRegistry(initialMap?: Record<string, CacheDefinition | CacheDefinitionOptions>, options?: { now?: () => number; registry?: RegistryStore; type?: \"cache.browser\" | \"cache.server\" }): CacheRegistry;",
   "export declare function defineCache(options?: CacheDefinitionOptions): CacheDefinition;",
-  "export declare function component<TProps extends Record<string, unknown> = Record<string, unknown>>(fn: ComponentFunction<TProps>): ComponentFunction<TProps>;",
+  "export declare function component<TProps extends object = Record<string, unknown>>(fn: ComponentFunction<TProps>): ComponentFunction<TProps>;",
+  "export declare function childrenFragment(source: ChildrenInput): Children;",
   "export declare function createComponentRegistry(initialMap?: Record<string, ComponentFunction>, options?: { registry?: RegistryStore; type?: \"component\" }): ComponentRegistry;",
-  "export declare function defineComponent<TProps extends Record<string, unknown> = Record<string, unknown>>(fn: ComponentFunction<TProps>): ComponentFunction<TProps>;",
+  "export declare function defineComponent<TProps extends object = Record<string, unknown>>(fn: ComponentFunction<TProps>): ComponentFunction<TProps>;",
   "export declare function defineAsyncContainerElement(options?: { tagName?: string; app?: AppHub; Async?: AppHub; customElements?: CustomElementRegistry; HTMLElement?: typeof HTMLElement; window?: Window }): CustomElementConstructor;",
   "export declare function defineAsyncSuspenseElement(options?: { tagName?: string; customElements?: CustomElementRegistry; HTMLElement?: typeof HTMLElement; window?: Window }): CustomElementConstructor;",
   "export declare function defineRegistrySnapshot<T extends RegistryRuntimeSnapshot>(snapshot?: T): T;",
   "export declare function createLazyRegistry(options?: { registryAssets?: RegistryAssetsConfig; assets?: RegistryAssetsConfig; importModule?: (url: string) => MaybePromise<Record<string, unknown>> }): LazyRegistry;",
   "export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;",
   "export declare function createHandlerRegistry(initialMap?: Record<string, HandlerFunction>, options?: { registry?: RegistryStore; type?: \"handler\" }): HandlerRegistry;",
   "export declare function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;",
+  "export declare function isChildrenFragment(value: unknown): value is Children;",
   "export declare function Loader(options?: LoaderOptions): LoaderInstance;",
   "export declare const AsyncLoader: typeof Loader;",
   "export declare function createPartialRegistry(initialMap?: Record<string, PartialFunction>, options?: { registry?: RegistryStore; type?: \"partial\" }): PartialRegistry;",
@@ -1250,10 +1257,10 @@ const jsxDtsOutput = [
   "export declare const ASYNC_JSX_SUSPENSE: unique symbol;",
   "export declare const ASYNC_JSX_REVEAL: unique symbol;",
   "export type JsxSignal<T = unknown> = { readonly kind: \"async-jsx-signal\"; readonly type: typeof ASYNC_JSX_SIGNAL; readonly source: T; readonly options: Record<string, unknown> };",
-  "export type JsxComponent<TProps extends Record<string, unknown> = Record<string, unknown>> = { readonly kind: \"async-jsx-component\"; readonly type: typeof ASYNC_JSX_COMPONENT; readonly render: (props: TProps) => unknown; readonly options: Record<string, unknown> };",
+  "export type JsxComponent<TProps extends object = Record<string, unknown>> = { readonly kind: \"async-jsx-component\"; readonly type: typeof ASYNC_JSX_COMPONENT; readonly render: (props: TProps) => unknown; readonly options: Record<string, unknown> };",
   "export type JsxBoundary = { readonly kind: \"async-jsx-suspense\" | \"async-jsx-reveal\"; readonly type: typeof ASYNC_JSX_SUSPENSE | typeof ASYNC_JSX_REVEAL; readonly props: Record<string, unknown> };",
   "export declare function signal<T = unknown>(source: T, options?: Record<string, unknown>): JsxSignal<T>;",
-  "export declare function component<TProps extends Record<string, unknown> = Record<string, unknown>>(render: (props: TProps) => unknown, options?: Record<string, unknown>): JsxComponent<TProps>;",
+  "export declare function component<TProps extends object = Record<string, unknown>>(render: (props: TProps) => unknown, options?: Record<string, unknown>): JsxComponent<TProps>;",
   "export declare function Suspense(props?: Record<string, unknown>): JsxBoundary;",
   "export declare function Reveal(props?: Record<string, unknown>): JsxBoundary;",
   ""

specs/framework/05-component-system.md

@@ -30,7 +30,7 @@ Component helpers include:
 - `this.asyncSignal(name, fn)`.
 - `this.effect(fn)`.
 - `this.handler(name, fn)` and `this.handler(fn)`.
-- `this.render(Component, props)`.
+- `this.render(Component, props, children?)`.
 - `this.slot(Component, propsOrFn)`.
 - `this.suspense(signalRef, views)`.
 - `this.on(event, fn)` with `attach`, `visible`, `intersect`, and `destroy`
@@ -41,6 +41,17 @@ Component helpers include:
 Components return HTML-compatible values. Promise-returning components are not
 part of the synchronous component contract.
 
+Default children are framework-owned scoped fragments. The canonical no-build
+form is `this.render(Component, props, children)`, and the child component
+receives the normalized fragment as `props.children`. The child consumes the
+fragment by interpolating `children` in an `html` template; it does not call a
+children callback directly.
+
+Children fragments are lazy when supplied as factories, caller-lexical through
+closed-over values, single-consumption by default, escaped as text for strings,
+and cleaned up with the consuming component fragment. Supplying both
+`props.children` and the third `this.render(...)` argument is invalid.
+
 ## Subsystem Boundaries
 
 - Components create scoped declarations; registries own their storage and
@@ -59,6 +70,9 @@ Components emit the same protocol as hand-authored HTML:
 - Local signals become scoped signal IDs referenced by `signal:*` or `class:*`.
 - Suspense helpers emit boundary templates and do not own wrapper elements.
 - Child rendering returns fragment output that remains scannable by the loader.
+- Default children interpolate through the same template renderer so escaping,
+  nested component rendering, handler registration, signal bindings, and cleanup
+  stay in one scoped path.
 - Slots mount a child component into an attached DOM target and may recompute
   props from signals without exposing loader mounting to application code.
 
@@ -77,6 +91,10 @@ Components must not be required to rerun to activate server-rendered DOM:
 
 - Components are scoped fragments, not virtual nodes.
 - Component output does not cause a component rerender loop.
+- Default children do not create a parent rerender path or runtime JSX node
+  array.
+- Default children and slots are separate primitives: children are mount-time
+  projection; slots are explicit attached child replacement.
 - Slot updates are explicit child component replacement, not parent rerendering.
 - Component-local state and handlers are unregistered on fragment cleanup.
 - `on:visible` is a one-shot visibility lifecycle hook.
@@ -90,6 +108,10 @@ Components must not be required to rerun to activate server-rendered DOM:
 - Lazy component descriptors that resolve asynchronously are not valid for
   synchronous render paths unless a future async component contract defines it.
 - Invalid suspense inputs fail before emitting ambiguous boundary markup.
+- Supplying children through both `props.children` and the third render
+  argument fails before the child component renders.
+- Consuming the same children fragment twice fails instead of duplicating
+  handler IDs or cleanup records.
 - Observer-less environments report unsupported intersection behavior through
   the defined fallback path.
 
@@ -105,6 +127,9 @@ Components must not be required to rerun to activate server-rendered DOM:
   signal without creating a wrapper element.
 - Multiple child components with identical hook bodies do not dedupe each
   other incorrectly.
+- Static and lazy default children render through `this.render(...)`, preserve
+  escaping, support nested component output, and clean up scoped child resources
+  when the consuming fragment is destroyed.
 
 ## Open Or Deferred Decisions
 

src/browser.js

@@ -7,7 +7,7 @@ export { component, createComponentRegistry, defineComponent } from "./component
 export { delay } from "./delay.js";
 export { defineAsyncContainerElement, defineAsyncSuspenseElement } from "./elements.js";
 export { createHandlerRegistry } from "./handlers.js";
-export { html } from "./html.js";
+export { childrenFragment, html, isChildrenFragment } from "./html.js";
 export { createLazyRegistry, defineRegistrySnapshot } from "./lazy-registry.js";
 export { Loader, AsyncLoader } from "./loader.js";
 export { createPartialRegistry } from "./partials.js";

src/component.js

@@ -1,5 +1,5 @@
 import { attributeName } from "./attributes.js";
-import { escapeHtml, rawHtml, renderTemplate } from "./html.js";
+import { childrenFragment, escapeHtml, rawHtml, renderTemplate } from "./html.js";
 import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
 import { createLazyRegistry, isLazyDescriptor } from "./lazy-registry.js";
 
@@ -136,6 +136,7 @@ export function renderComponent(Component, props = {}, runtime, parentScope = "c
     destroyHooks,
     renderScopedTemplate
   });
+  templateOptions.fragmentContext = context;
 
   const output = Component.call(context, props);
   if (output && typeof output.then === "function") {
@@ -307,8 +308,8 @@ function createComponentContext({ runtime, scope, cleanups, attachHooks, visible
       return registerScopedHandler(name, fn);
     },
 
-    render(Child, childProps = {}) {
-      const child = renderComponent(Child, childProps, runtime, scope);
+    render(Child, childProps = {}, childrenInput) {
+      const child = renderComponent(Child, normalizeRenderProps(childProps, childrenInput), runtime, scope);
       cleanups.push(child.cleanup);
       attachHooks.push((target) => child.attach(target));
       visibleHooks.push((target) => child.visible(target, loader._observeVisible));
@@ -432,6 +433,25 @@ function createComponentContext({ runtime, scope, cleanups, attachHooks, visible
   }
 }
 
+function normalizeRenderProps(props, childrenInput) {
+  const normalizedProps = props == null ? {} : props;
+  if (typeof normalizedProps !== "object" || Array.isArray(normalizedProps)) {
+    throw new TypeError("this.render(Component, props, children) props must be an object.");
+  }
+  const hasPropsChildren = Object.hasOwn(normalizedProps, "children") && normalizedProps.children !== undefined;
+  const hasThirdArgumentChildren = childrenInput !== undefined;
+  if (hasPropsChildren && hasThirdArgumentChildren) {
+    throw new TypeError("this.render(Component, props, children) cannot receive both props.children and a children argument.");
+  }
+  if (!hasPropsChildren && !hasThirdArgumentChildren) {
+    return normalizedProps;
+  }
+  return {
+    ...normalizedProps,
+    children: childrenFragment(hasThirdArgumentChildren ? childrenInput : normalizedProps.children)
+  };
+}
+
 function normalizeOptionsCallback(label, optionsOrFn, maybeFn) {
   if (typeof optionsOrFn === "function" && maybeFn === undefined) {
     return { options: {}, fn: optionsOrFn };