@async/framework 0.11.13 → 0.11.15

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.11.15 - 2026-06-19
+
+- Made the source package private and kept its public surface to the minimal
+  export spec for root, `/browser`, `/server`, and `/package.json` only.
+- Moved publish staging to generated `dist/package.json` so npm and release
+  automation publish from `dist/` while package consumers still receive
+  root-level artifacts without `dist/` paths.
+- Removed legacy direct artifact subpath exports plus top-level
+  `main`/`module`/`browser`/`types` and generated file lists from the source
+  manifest.
+- Updated pack, size, pipeline, and installed-package coverage to verify the
+  browser and server entrypoints remain split after packing.
+- Bundle size from bundled TypeScript source: `browser.ts` 197,173 B raw /
+  37,198 B gzip -> `browser.min.js` 84,013 B raw / 24,894 B gzip
+  (-113,160 B raw, -12,304 B gzip).
+
+## 0.11.14 - 2026-06-18
+
+- Added condition-specific root declaration targets so browser-conditioned root
+  imports resolve to browser declarations while Node/default root imports keep
+  server-capable declarations.
+- Preserved the root browser runtime condition and documented that server-only
+  APIs remain on the Node/server entrypoints.
+- Added packed-artifact export-map, declaration/runtime parity, and static
+  import checks for root browser, root Node, explicit `/browser`, and explicit
+  `/server` entrypoints.
+- Added component-scoped continuous intersection helpers with
+  `this.intersect(...)` and `this.on("intersect", options?, fn)`, preserving
+  `on:visible` as a one-shot visibility lifecycle hook.
+- Added declarative `on:intersect` with `intersect:threshold`,
+  `intersect:root-margin`, and `intersect:once` pseudo-event options, including
+  custom `intersect` attribute prefix support.
+- Added observer cleanup coverage for component teardown, boundary swaps,
+  fallback scheduling, repeated entries, and existing visible compatibility.
+- Moved root release artifacts to an ignored generated-output workflow:
+  tests, bundle checks, pack checks, and generated CI tasks materialize the
+  current package surface before verification or publish.
+- Bundle size from bundled TypeScript source: `browser.ts` 197,173 B raw /
+  37,198 B gzip -> `browser.min.js` 84,013 B raw / 24,894 B gzip
+  (-113,160 B raw, -12,304 B gzip).
+
 ## 0.11.13 - 2026-06-18
 
 - Validated server proxy arguments, default input payloads, and selected signal

package/README.md

@@ -306,6 +306,9 @@ patches, and browser-cache patches. Async does not ship a component resume graph
 For npm consumers, `@async/framework` uses conditional exports: browser-aware
 tooling receives the browser entry, while Node receives the server-capable
 entry. Use explicit subpaths when the target matters.
+The root export also uses condition-specific declarations, so browser-conditioned
+root imports expose the same API as `@async/framework/browser`; server-only APIs
+remain declared on the Node/server entrypoints.
 
 ```js
 import {
@@ -607,6 +610,10 @@ Loader scans regular HTML attributes:
 | `on:click="server.cart.add(productId)"` | Server command with signal args |
 | `on:attach="setup"` | Component root attach lifecycle pseudo-event |
 | `on:visible="trackView"` | Component root visible lifecycle pseudo-event |
+| `on:intersect="trackSection"` | Continuous intersection lifecycle pseudo-event |
+| `intersect:threshold="0,0.5,1"` | Intersection threshold option for `on:intersect` |
+| `intersect:root-margin="-20% 0px -55% 0px"` | Intersection root margin option for `on:intersect` |
+| `intersect:once="true"` | Disconnect `on:intersect` after the first intersecting entry |
 | `signal:text="product.title"` | Text binding |
 | `signal:value="productId"` | Form value binding with writeback |
 | `signal:attr:disabled="product.$loading"` | Attribute binding |
@@ -641,6 +648,7 @@ Async.start({
   attributes: {
     async: "data-async-",
     class: "data-class-",
+    intersect: "data-intersect-",
     signal: "data-signal-",
     on: "data-on-"
   }
@@ -648,7 +656,8 @@ Async.start({
 ```
 
 That maps to `data-async-container`, `data-on-click="save"`,
-`data-signal-text="product.title"`, and `data-class-selected="selected"`.
+`data-signal-text="product.title"`, `data-class-selected="selected"`, and
+`data-intersect-threshold="0.5"`.
 
 Inside `html` templates, signal refs can be passed directly to binding
 attributes:
@@ -1099,6 +1108,8 @@ Component helpers:
 | `this.on(event, fn)` | Fragment lifecycle fallback for `attach`, `visible`, and `destroy` |
 | `this.onMount(fn)` | Compatibility alias for `this.on("attach", fn)` |
 | `this.onVisible(fn)` | Compatibility alias for `this.on("visible", fn)` |
+| `this.on("intersect", options?, fn)` | Continuous intersection lifecycle for the mounted component scope |
+| `this.intersect(element, options?, fn)` | Component-owned continuous intersection observer for a direct element |
 
 `this.suspense(...)` is sugar for Loader boundaries:
 `asyncSignal + async:boundary + async:* templates`. It emits only templates. The
@@ -1173,6 +1184,73 @@ this.on("destroy", () => {
 the component root first becomes visible. Lifecycle events do not drive
 component rerenders.
 
+Use `on:intersect` when markup should receive continuous intersection updates
+through a registered handler:
+
+```html
+<section
+  on:intersect="trackSection"
+  intersect:threshold="0,0.25,0.5,0.75,1"
+  intersect:root-margin="-20% 0px -55% 0px"
+>
+  ...
+</section>
+```
+
+The handler receives `element`, `entry`, `entries`, `observer`,
+`isIntersecting`, `intersectionRatio`, and `unsupported`. Custom roots are not
+selector-based; use `this.intersect(...)` with a direct root element when a
+custom observer root is needed.
+
+Use `this.on("intersect", ...)` when a component needs continuous visibility
+state:
+
+```js
+const Card = defineComponent(function Card() {
+  const visible = this.signal(false);
+
+  this.on("intersect", { threshold: 0.5 }, ({ isIntersecting }) => {
+    visible.set(isIntersecting);
+  });
+
+  return html`<article class:visible="${visible}">...</article>`;
+});
+```
+
+Use `this.intersect(...)` with a direct element when a parent owns scroll-spy or
+active-section state:
+
+```js
+const Section = defineComponent(function Section({ id, observeSection }) {
+  const attach = this.handler("attach", function ({ element }) {
+    return observeSection(id, element);
+  });
+
+  return html`<section on:attach="${attach}"><h2>${id}</h2></section>`;
+});
+
+const Page = defineComponent(function Page() {
+  const active = this.signal("intro");
+  const ratios = new Map();
+  const options = {
+    rootMargin: "-20% 0px -55% 0px",
+    threshold: [0, 0.25, 0.5, 0.75, 1]
+  };
+
+  const observeSection = (id, element) => this.intersect(element, options, ({ entry }) => {
+    ratios.set(id, entry.isIntersecting ? entry.intersectionRatio : 0);
+    const best = [...ratios.entries()].sort((a, b) => b[1] - a[1])[0];
+    active.set(best?.[0] ?? id);
+  });
+
+  return html`
+    <nav signal:text="${active}"></nav>
+    ${this.render(Section, { id: "intro", observeSection })}
+    ${this.render(Section, { id: "runtime", observeSection })}
+  `;
+});
+```
+
 ## Streaming
 
 Out-of-order HTML can target a boundary and keep delegated handlers working:
@@ -1261,6 +1339,8 @@ pnpm run pipeline:github:check
 Useful commands:
 
 ```bash
+pnpm run bundle
+pnpm run bundle:clean
 pnpm run pipeline:verify
 pnpm run pipeline:pages
 pnpm run registry:lint
@@ -1268,6 +1348,20 @@ pnpm run pipeline:release:doctor
 pnpm run release:check
 ```
 
+Release artifacts such as `browser.js`, `browser.min.js`,
+`browser.umd.min.js`, `browser.ts`, `browser.d.ts`, `framework.ts`,
+`framework.d.ts`, and `server.js` are generated into `dist/`. The generated
+`dist/` directory is the package root for `npm pack` and release publishing, so
+the published package and CDN surface still expose those files at package root
+rather than under `dist/`. The source `package.json` stays private and owns the
+minimal public export spec, while omitting legacy `main`/`module`/`browser`
+entry fields and generated package file lists. `scripts/build-framework-bundle.js`
+derives the generated `dist/package.json` and staged artifact names from that
+spec. Feature branches should edit source files and let `pnpm run bundle`,
+`pnpm test`, `pnpm run pack:check`, or the generated release workflow
+materialize the publish tree. Use `pnpm run bundle:clean` to remove local
+generated artifacts after inspection.
+
 `registry:lint` scans package source and examples for declared registry ids
 such as signals, handlers, server functions, partials, routes, and components.
 It writes `.async/registry-manifest.json` plus a per-file cache at

package/browser.d.ts

@@ -23,6 +23,7 @@ export interface AttributeConfig {
   async?: string | string[];
   class?: string | string[];
   signal?: string | string[];
+  intersect?: string | string[];
   on?: string | string[];
 }
 
@@ -30,6 +31,7 @@ export interface NormalizedAttributeConfig {
   async: string[];
   class: string[];
   signal: string[];
+  intersect: string[];
   on: string[];
 }
 
@@ -403,7 +405,41 @@ export interface Router {
   destroy(): void;
 }
 
-export type LifecycleEventName = "attach" | "mount" | "visible" | "destroy";
+export type LifecycleEventName = "attach" | "mount" | "visible" | "intersect" | "destroy";
+
+export interface IntersectionFallbackEntry {
+  target: Element;
+  isIntersecting: boolean;
+  intersectionRatio: number;
+  time: number;
+  rootBounds: DOMRectReadOnly | null;
+  boundingClientRect: DOMRect | DOMRectReadOnly | null;
+  intersectionRect: DOMRect | DOMRectReadOnly | null;
+}
+
+export interface IntersectionEvent {
+  target: Element;
+  element: Element;
+  el: Element;
+  root: Document | Element | DocumentFragment;
+  entry: IntersectionObserverEntry | IntersectionFallbackEntry;
+  entries: Array<IntersectionObserverEntry | IntersectionFallbackEntry>;
+  observer: IntersectionObserver | null;
+  isIntersecting: boolean;
+  intersectionRatio: number;
+  unsupported: boolean;
+}
+
+export interface IntersectionOptions {
+  root?: Element | Document | null;
+  rootMargin?: string;
+  threshold?: number | number[];
+  once?: boolean;
+  schedule?: "lifecycle" | "sync";
+  key?: string;
+}
+
+export type IntersectionCallback = (this: ComponentContext, event: IntersectionEvent) => unknown;
 
 export interface ComponentContext {
   scope: string;
@@ -423,9 +459,13 @@ export interface ComponentContext {
   handler(name: string, fn: HandlerFunction): string;
   render<TProps extends Record<string, unknown> = Record<string, unknown>>(Child: ComponentFunction<TProps>, props?: TProps): TemplateLike;
   suspense(signalRef: Pick<SignalRef, "id">, views: SuspenseViews | SuspenseReadyView): TemplateLike;
-  on(eventName: LifecycleEventName, fn: (this: ComponentContext, target?: Element) => unknown): void;
+  on(eventName: "intersect", fn: IntersectionCallback): void;
+  on(eventName: "intersect", options: IntersectionOptions | undefined | null, fn: IntersectionCallback): void;
+  on(eventName: Exclude<LifecycleEventName, "intersect">, fn: (this: ComponentContext, target?: Element) => unknown): void;
   onMount(fn: (this: ComponentContext, target?: Element) => unknown): void;
   onVisible(fn: (this: ComponentContext, target?: Element) => unknown): void;
+  intersect(target: Element, fn: IntersectionCallback): Cleanup;
+  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;