@async/framework 0.11.17 → 0.11.19

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.11.19 - 2026-06-19
+
+- Added the first build-required profile subpaths,
+  `@async/framework/jsx` and `@async/framework/vite`, with package export,
+  declaration, pack, and installed-package coverage.
+- Added JSX authoring markers for `signal`, `component`, `Suspense`, and
+  `Reveal` that stay inert for compiler analysis instead of executing app code.
+- Added a Vite 8+ Rolldown plugin spike that emits a deterministic virtual
+  runtime plan/report from fixture metadata and rejects unsupported hosts before
+  transform output is trusted.
+- Added the build-profile report fixture proving selected runtime slices,
+  omitted no-build systems, visible fallbacks, signal/event/stream counts, and
+  generated locator counts without importing the root `Async` app hub.
+- Bundle size from bundled TypeScript source: `browser.ts` raw 221,403 B (221.4 KB / 0.221 MB), gzip 42,093 B (42.1 KB / 0.042 MB), br 34,797 B (34.8 KB / 0.035 MB) -> `browser.min.js` raw 95,027 B (95.0 KB / 0.095 MB), gzip 28,145 B (28.1 KB / 0.028 MB), br 24,793 B (24.8 KB / 0.025 MB); delta raw -126,376 B (-126.4 KB / -0.126 MB), gzip -13,948 B (-13.9 KB / -0.014 MB), br -10,004 B (-10.0 KB / -0.010 MB).
+
+## 0.11.18 - 2026-06-19
+
+- Added inert build optimizer artifact helpers for ADR 26 pass records,
+  diagnostics, runtime slice selection, handler emission, and development
+  report generation.
+- Added optimizer fixtures for signal source classification, signal ownership,
+  JSX event symbol extraction, Suspense/Reveal lowering, runtime selection, and
+  server-only browser import diagnostics.
+- Added build optimizer tests proving maybe-promise signals fail explicitly,
+  event handlers are not forced through dynamic imports, Reveal ordering is
+  deterministic, omitted runtime systems are visible, and helpers do not execute
+  app modules or import no-build runtime systems.
+- Bundle size from bundled TypeScript source: `browser.ts` raw 221,403 B (221.4 KB / 0.221 MB), gzip 42,093 B (42.1 KB / 0.042 MB), br 34,797 B (34.8 KB / 0.035 MB) -> `browser.min.js` raw 95,027 B (95.0 KB / 0.095 MB), gzip 28,145 B (28.1 KB / 0.028 MB), br 24,793 B (24.8 KB / 0.025 MB); delta raw -126,376 B (-126.4 KB / -0.126 MB), gzip -13,948 B (-13.9 KB / -0.014 MB), br -10,004 B (-10.0 KB / -0.010 MB).
+
 ## 0.11.17 - 2026-06-19
 
 - Added the stream backpatch protocol to `createBoundaryReceiver(...)` with

package/build-optimizer.js

@@ -0,0 +1,736 @@
+export const OPTIMIZER_ARTIFACT_VERSION = 1;
+
+export const OPTIMIZER_PASSES = Object.freeze([
+  "source-inventory",
+  "jsx-semantic-graph",
+  "signal-source-classification",
+  "signal-ownership-lifetime",
+  "event-symbol-extraction",
+  "suspense-reveal-lowering",
+  "runtime-slice-selection",
+  "handler-emission",
+  "plan-bootstrap-emit"
+]);
+
+export const RUNTIME_ENTRYPOINTS = Object.freeze({
+  runtime: "@async/framework/runtime",
+  signals: "@async/framework/runtime/signals",
+  events: "@async/framework/runtime/events"
+});
+
+export const RUNTIME_SLICE_NAMES = Object.freeze([
+  "signals",
+  "events",
+  "async-signals",
+  "stream"
+]);
+
+const omittedRuntimeSystems = Object.freeze([
+  "no-build-loader",
+  "router",
+  "server",
+  "cache",
+  "partials",
+  "components",
+  "boundary-receiver"
+]);
+
+const validRevealOrders = new Set(["as-ready", "forwards", "backwards", "together"]);
+const validRevealTails = new Set(["visible", "collapsed", "hidden"]);
+const validHandlerModes = new Set(["inline", "direct-import", "eager-chunk", "lazy-chunk"]);
+
+export function createOptimizerArtifactSet(input = {}) {
+  const diagnostics = [];
+  const sourceInventory = createSourceInventoryArtifact(input.sourceInventory, { diagnostics });
+  const jsxSemanticGraph = createJsxSemanticGraphArtifact(input.semanticGraph, { diagnostics });
+  const signalSources = classifySignalSources(jsxSemanticGraph.signals, { diagnostics }).artifact;
+  const signalOwnership = inferSignalOwnership(jsxSemanticGraph.signals, { diagnostics }).artifact;
+  const eventSymbols = extractEventSymbols(jsxSemanticGraph.eventProps, { diagnostics }).artifact;
+  const streamBoundaries = lowerSuspenseReveal(jsxSemanticGraph, { diagnostics }).artifact;
+  const runtimeSelection = selectRuntimeSlices({
+    sourceInventory,
+    signalSources,
+    eventSymbols,
+    streamBoundaries
+  }, { diagnostics }).artifact;
+  const handlerEmission = planHandlerEmission(eventSymbols.handlers, { diagnostics }).artifact;
+  const report = createOptimizerReport({
+    sourceInventory,
+    signalSources,
+    signalOwnership,
+    eventSymbols,
+    streamBoundaries,
+    runtimeSelection,
+    handlerEmission,
+    jsxSemanticGraph
+  });
+  const buildEmit = {
+    bootstrap: {
+      mode: "fixture",
+      entrypoint: runtimeSelection.entrypoint,
+      slices: runtimeSelection.slices.map((slice) => slice.name)
+    },
+    manifest: {
+      version: OPTIMIZER_ARTIFACT_VERSION,
+      passes: OPTIMIZER_PASSES
+    },
+    report
+  };
+
+  return {
+    version: OPTIMIZER_ARTIFACT_VERSION,
+    passes: OPTIMIZER_PASSES,
+    artifacts: {
+      sourceInventory,
+      jsxSemanticGraph,
+      signalSources,
+      signalOwnership,
+      eventSymbols,
+      streamBoundaries,
+      runtimeSelection,
+      handlerEmission,
+      buildEmit
+    },
+    diagnostics,
+    report
+  };
+}
+
+export function createSourceInventoryArtifact(input = {}, options = {}) {
+  const diagnostics = getDiagnostics(options);
+  const config = input.config ?? {};
+  const host = config.host ?? {};
+  const hostName = host.name ?? config.hostName;
+  const hostVersion = Number(host.major ?? host.versionMajor ?? parseVersionMajor(host.version));
+  const hostEngine = host.engine ?? config.engine;
+
+  if (hostName && hostName !== "vite") {
+    addDiagnostic(diagnostics, "unsupported-build-host", "Only Vite 8+ with Rolldown is supported by the build optimizer.", {
+      pass: "source-inventory",
+      value: hostName
+    });
+  }
+  if (hostName === "vite" && hostVersion && hostVersion < 8) {
+    addDiagnostic(diagnostics, "unsupported-build-host", "Vite hosts must be version 8 or newer.", {
+      pass: "source-inventory",
+      value: host.version ?? hostVersion
+    });
+  }
+  if (hostName === "vite" && hostEngine && hostEngine !== "rolldown") {
+    addDiagnostic(diagnostics, "unsupported-build-host", "The initial build optimizer supports the Rolldown engine only.", {
+      pass: "source-inventory",
+      value: hostEngine
+    });
+  }
+
+  const frameworkImports = arrayOf(input.frameworkImports);
+  for (const frameworkImport of frameworkImports) {
+    if (frameworkImport.supported === false) {
+      addDiagnostic(diagnostics, "unsupported-framework-import-shape", "Framework import shape is not supported by the build optimizer.", {
+        pass: "source-inventory",
+        sourceId: frameworkImport.sourceId ?? frameworkImport.module
+      });
+    }
+  }
+
+  const serverModules = arrayOf(input.serverModules);
+  const serverIds = new Set(serverModules.map((module) => module.id).filter(Boolean));
+  const entries = arrayOf(input.entries);
+  for (const entry of entries) {
+    if (entry.target !== "browser") {
+      continue;
+    }
+    for (const imported of arrayOf(entry.imports)) {
+      if (serverIds.has(imported)) {
+        addDiagnostic(diagnostics, "browser-imports-server-only-code", "Browser output cannot import server-only modules.", {
+          pass: "source-inventory",
+          sourceId: entry.id,
+          value: imported
+        });
+      }
+    }
+  }
+
+  return {
+    version: OPTIMIZER_ARTIFACT_VERSION,
+    entries,
+    frameworkImports,
+    jsxModules: arrayOf(input.jsxModules),
+    serverModules,
+    config
+  };
+}
+
+export function createJsxSemanticGraphArtifact(input = {}) {
+  return {
+    version: OPTIMIZER_ARTIFACT_VERSION,
+    components: arrayOf(input.components),
+    signals: arrayOf(input.signals),
+    eventProps: arrayOf(input.eventProps),
+    suspense: arrayOf(input.suspense),
+    revealPolicies: arrayOf(input.revealPolicies),
+    serverCalls: arrayOf(input.serverCalls),
+    routes: arrayOf(input.routes),
+    locators: arrayOf(input.locators)
+  };
+}
+
+export function classifySignalSources(signalFeatures = [], options = {}) {
+  const diagnostics = getDiagnostics(options);
+  const sources = [];
+
+  for (const feature of arrayOf(signalFeatures)) {
+    const sourceId = requireFeatureId(feature, "signal", diagnostics, "signal-source-classification");
+    if (!sourceId) {
+      continue;
+    }
+    const sourceShape = feature.sourceShape ?? feature.shape ?? feature.sourceKind;
+    const dependencies = normalizeReads(feature.reads ?? feature.dependencies);
+
+    if (sourceShape === "value" || sourceShape === "literal" || sourceShape === "non-function") {
+      sources.push({
+        kind: "writable",
+        sourceId,
+        initialValue: feature.initialValue
+      });
+      continue;
+    }
+    if (sourceShape === "sync-function" || sourceShape === "derived" || sourceShape === "computed") {
+      sources.push({
+        kind: "derived",
+        sourceId,
+        dependencies
+      });
+      continue;
+    }
+    if (sourceShape === "async-function" || sourceShape === "async" || sourceShape === "promise-wrapper") {
+      if (dependencies.length === 0) {
+        addDiagnostic(diagnostics, "async-source-missing-tracked-dependencies", "Async signal sources need tracked dependencies.", {
+          pass: "signal-source-classification",
+          sourceId
+        });
+      }
+      sources.push({
+        kind: "async",
+        sourceId,
+        dependencies,
+        latest: feature.latest !== false,
+        pending: feature.pending !== false,
+        error: feature.error !== false,
+        versioned: true,
+        stream: feature.stream ?? "default"
+      });
+      continue;
+    }
+    if (sourceShape === "maybe-promise" || sourceShape === "maybe-promise-function") {
+      addDiagnostic(diagnostics, "maybe-promise-signal-source", "Maybe-promise signal sources must be made explicit before optimizer output is trusted.", {
+        pass: "signal-source-classification",
+        sourceId
+      });
+      continue;
+    }
+
+    addDiagnostic(diagnostics, "signal-source-unclassified", "signal(...) function source cannot be classified from static metadata.", {
+      pass: "signal-source-classification",
+      sourceId
+    });
+  }
+
+  return {
+    artifact: {
+      version: OPTIMIZER_ARTIFACT_VERSION,
+      sources
+    },
+    diagnostics
+  };
+}
+
+export function inferSignalOwnership(signalFeatures = [], options = {}) {
+  const diagnostics = getDiagnostics(options);
+  const ownership = [];
+
+  for (const feature of arrayOf(signalFeatures)) {
+    const sourceId = requireFeatureId(feature, "signal", diagnostics, "signal-ownership-lifetime");
+    if (!sourceId) {
+      continue;
+    }
+
+    if (feature.createdIn === "event-handler" && !feature.explicitLifetime) {
+      addDiagnostic(diagnostics, "invalid-handler-signal-lifetime", "Signals created inside event handlers need explicit lifetime before optimizer output.", {
+        pass: "signal-ownership-lifetime",
+        sourceId
+      });
+      continue;
+    }
+
+    const owner = normalizeOwner(feature.owner ?? feature.scope);
+    if (!owner) {
+      addDiagnostic(diagnostics, "ambiguous-signal-owner", "Signal ownership is ambiguous and must not be silently promoted to global.", {
+        pass: "signal-ownership-lifetime",
+        sourceId
+      });
+      continue;
+    }
+
+    ownership.push({
+      sourceId,
+      owner,
+      reason: feature.ownerReason ?? ownershipReason(owner)
+    });
+  }
+
+  return {
+    artifact: {
+      version: OPTIMIZER_ARTIFACT_VERSION,
+      ownership
+    },
+    diagnostics
+  };
+}
+
+export function extractEventSymbols(eventProps = [], options = {}) {
+  const diagnostics = getDiagnostics(options);
+  const events = [];
+  const handlers = [];
+
+  for (const [index, feature] of arrayOf(eventProps).entries()) {
+    const propName = feature.propName ?? feature.name;
+    const eventId = feature.eventId ?? `event:${index}`;
+    const handlerId = feature.handlerId ?? feature.handler ?? `${eventId}:handler`;
+
+    if (feature.syntax === "no-build" || String(propName).startsWith("on:")) {
+      addDiagnostic(diagnostics, "no-build-event-syntax-in-jsx", "JSX build profile uses onClick-style props unless compatibility mode is explicit.", {
+        pass: "event-symbol-extraction",
+        sourceId: eventId,
+        value: propName
+      });
+      continue;
+    }
+
+    const eventType = jsxEventType(propName);
+    if (!eventType) {
+      addDiagnostic(diagnostics, "event-command-unlowerable", "Event command cannot be statically lowered.", {
+        pass: "event-symbol-extraction",
+        sourceId: eventId,
+        value: propName
+      });
+      continue;
+    }
+
+    const commands = normalizeCommands(feature.commands, handlerId, feature.syncEventApis);
+    events.push({
+      eventId,
+      elementId: feature.elementId,
+      propName,
+      eventType,
+      commands,
+      handlerId
+    });
+    handlers.push({
+      symbolId: handlerId,
+      eventId,
+      propName,
+      eventType,
+      module: feature.module,
+      exportName: feature.exportName ?? handlerId,
+      mode: feature.emissionMode,
+      chunk: feature.chunk,
+      preload: Boolean(feature.preload),
+      syncEventApis: arrayOf(feature.syncEventApis),
+      preserveSyncEventApi: Boolean(feature.preserveSyncEventApi)
+    });
+  }
+
+  return {
+    artifact: {
+      version: OPTIMIZER_ARTIFACT_VERSION,
+      events,
+      handlers
+    },
+    diagnostics
+  };
+}
+
+export function lowerSuspenseReveal(semanticGraph = {}, options = {}) {
+  const diagnostics = getDiagnostics(options);
+  const suspenseBoundaries = [];
+  const suspenseById = new Map();
+
+  for (const [index, feature] of arrayOf(semanticGraph.suspense).entries()) {
+    const boundaryId = feature.boundaryId ?? feature.id;
+    if (!boundaryId) {
+      addDiagnostic(diagnostics, "unstable-suspense-boundary-id", "Suspense boundary cannot get a stable stream boundary id.", {
+        pass: "suspense-reveal-lowering",
+        sourceId: `suspense:${index}`
+      });
+      continue;
+    }
+    const boundary = {
+      boundaryId,
+      sourceOrder: Number(feature.sourceOrder ?? index),
+      fallbackId: feature.fallbackId,
+      finalId: feature.finalId,
+      asyncSourceIds: arrayOf(feature.asyncSourceIds)
+    };
+    suspenseBoundaries.push(boundary);
+    suspenseById.set(boundaryId, boundary);
+  }
+
+  const revealGroups = [];
+  for (const [index, policy] of arrayOf(semanticGraph.revealPolicies).entries()) {
+    const order = policy.order ?? "as-ready";
+    const tail = policy.tail ?? "visible";
+    const groupId = policy.groupId ?? `reveal:${index}`;
+    const boundaryIds = arrayOf(policy.boundaryIds);
+    if (!validRevealOrders.has(order) || !validRevealTails.has(tail)) {
+      addDiagnostic(diagnostics, "invalid-reveal-policy", "Invalid Reveal order or tail policy.", {
+        pass: "suspense-reveal-lowering",
+        sourceId: groupId,
+        value: `${order}/${tail}`
+      });
+      continue;
+    }
+
+    const boundaries = boundaryIds.map((boundaryId) => suspenseById.get(boundaryId));
+    if (boundaries.some((boundary) => !boundary)) {
+      addDiagnostic(diagnostics, "malformed-reveal-nesting", "Reveal policies must reference known direct Suspense boundaries.", {
+        pass: "suspense-reveal-lowering",
+        sourceId: groupId
+      });
+      continue;
+    }
+
+    const sourceOrder = boundaries
+      .toSorted((left, right) => left.sourceOrder - right.sourceOrder)
+      .map((boundary) => boundary.boundaryId);
+    const arrivalOrder = arrayOf(policy.arrivalOrder).filter((boundaryId) => boundaryIds.includes(boundaryId));
+    revealGroups.push({
+      groupId,
+      order,
+      tail,
+      boundaryIds,
+      arrivalOrder,
+      commitOrder: commitOrderForReveal(order, sourceOrder, arrivalOrder)
+    });
+  }
+
+  return {
+    artifact: {
+      version: OPTIMIZER_ARTIFACT_VERSION,
+      suspenseBoundaries,
+      revealGroups
+    },
+    diagnostics
+  };
+}
+
+export function selectRuntimeSlices(featureArtifacts = {}, options = {}) {
+  const signalSources = featureArtifacts.signalSources ?? { sources: [] };
+  const eventSymbols = featureArtifacts.eventSymbols ?? { events: [], handlers: [] };
+  const streamBoundaries = featureArtifacts.streamBoundaries ?? { suspenseBoundaries: [], revealGroups: [] };
+  const diagnostics = getDiagnostics(options);
+  const signalCounts = countBy(signalSources.sources, "kind");
+  const hasSignals = signalSources.sources.length > 0;
+  const hasAsyncSignals = signalCounts.async > 0;
+  const hasEvents = eventSymbols.events.length > 0;
+  const hasStream = streamBoundaries.suspenseBoundaries.length > 0 || streamBoundaries.revealGroups.length > 0;
+  const slices = [];
+
+  if (hasSignals) {
+    slices.push({ name: "signals", reason: "signal source artifact is non-empty" });
+  }
+  if (hasEvents) {
+    slices.push({ name: "events", reason: "event symbol artifact is non-empty" });
+  }
+  if (hasAsyncSignals) {
+    slices.push({ name: "async-signals", reason: "async signal source records require status/version state" });
+  }
+  if (hasStream) {
+    slices.push({ name: "stream", reason: "Suspense or Reveal artifacts require stream boundary coordination" });
+  }
+
+  const entrypoint = chooseRuntimeEntrypoint({ hasSignals, hasEvents, hasAsyncSignals, hasStream });
+  const selected = new Set(slices.map((slice) => slice.name));
+  const omitted = omittedRuntimeSystems.map((system) => ({
+    system,
+    reason: omittedSystemReason(system)
+  }));
+  if (!selected.has("async-signals")) {
+    omitted.push({ system: "async-signal-status", reason: "no async signal source records" });
+  }
+  if (!selected.has("stream")) {
+    omitted.push({ system: "stream-boundary-coordination", reason: "no Suspense, Reveal, boundary, or patch records" });
+  }
+
+  const fallbacks = [];
+  if (entrypoint === "no-build-loader") {
+    addDiagnostic(diagnostics, "runtime-slice-fallback", "Runtime selection must not silently fall back to the no-build loader.", {
+      pass: "runtime-slice-selection"
+    });
+  }
+
+  return {
+    artifact: {
+      version: OPTIMIZER_ARTIFACT_VERSION,
+      entrypoint,
+      slices,
+      omitted,
+      fallbacks
+    },
+    diagnostics
+  };
+}
+
+export function planHandlerEmission(handlers = [], options = {}) {
+  const diagnostics = getDiagnostics(options);
+  const decisions = [];
+
+  for (const handler of arrayOf(handlers)) {
+    const mode = handler.mode ?? (handler.module ? "direct-import" : "inline");
+    if (!validHandlerModes.has(mode)) {
+      addDiagnostic(diagnostics, "handler-emission-mode-unknown", "Handler emission mode is not supported.", {
+        pass: "handler-emission",
+        sourceId: handler.symbolId,
+        value: mode
+      });
+      continue;
+    }
+    if (mode === "lazy-chunk" && handler.syncEventApis.length > 0 && !handler.preserveSyncEventApi) {
+      addDiagnostic(diagnostics, "handler-emission-loses-event-semantics", "Lazy handler emission must preserve synchronous event API semantics.", {
+        pass: "handler-emission",
+        sourceId: handler.symbolId
+      });
+      continue;
+    }
+
+    const decision = { mode, symbolId: handler.symbolId };
+    if (mode === "direct-import") {
+      decision.module = handler.module;
+    }
+    if (mode === "eager-chunk" || mode === "lazy-chunk") {
+      decision.chunk = handler.chunk;
+      if (mode === "lazy-chunk" && handler.preload) {
+        decision.preload = true;
+      }
+    }
+    decisions.push(decision);
+  }
+
+  return {
+    artifact: {
+      version: OPTIMIZER_ARTIFACT_VERSION,
+      handlers: decisions
+    },
+    diagnostics
+  };
+}
+
+export function createOptimizerReport(artifacts) {
+  const signalSourceCounts = countBy(artifacts.signalSources.sources, "kind", ["writable", "derived", "async"]);
+  const signalOwnershipCounts = countBy(artifacts.signalOwnership.ownership, "owner", [
+    "app",
+    "shared-module",
+    "component",
+    "owner-relative"
+  ]);
+  const asyncStatusCounts = {
+    latest: countWhere(artifacts.signalSources.sources, (source) => source.kind === "async" && source.latest),
+    pending: countWhere(artifacts.signalSources.sources, (source) => source.kind === "async" && source.pending),
+    error: countWhere(artifacts.signalSources.sources, (source) => source.kind === "async" && source.error),
+    versioned: countWhere(artifacts.signalSources.sources, (source) => source.kind === "async" && source.versioned),
+    streamDefault: countWhere(artifacts.signalSources.sources, (source) => source.kind === "async" && source.stream === "default"),
+    streamDefer: countWhere(artifacts.signalSources.sources, (source) => source.kind === "async" && source.stream === "defer")
+  };
+  const handlerEmissionCounts = countBy(artifacts.handlerEmission.handlers, "mode", [
+    "inline",
+    "direct-import",
+    "eager-chunk",
+    "lazy-chunk"
+  ]);
+  const revealOrderCounts = countBy(artifacts.streamBoundaries.revealGroups, "order", [
+    "as-ready",
+    "forwards",
+    "backwards",
+    "together"
+  ]);
+  const revealTailCounts = countBy(artifacts.streamBoundaries.revealGroups, "tail", [
+    "visible",
+    "collapsed",
+    "hidden"
+  ]);
+
+  return {
+    version: OPTIMIZER_ARTIFACT_VERSION,
+    runtime: {
+      entrypoint: artifacts.runtimeSelection.entrypoint,
+      slices: artifacts.runtimeSelection.slices,
+      omitted: artifacts.runtimeSelection.omitted,
+      fallbacks: artifacts.runtimeSelection.fallbacks
+    },
+    signals: {
+      sources: signalSourceCounts,
+      ownership: signalOwnershipCounts,
+      asyncStatus: asyncStatusCounts
+    },
+    events: {
+      eventCount: artifacts.eventSymbols.events.length,
+      handlerCount: artifacts.eventSymbols.handlers.length
+    },
+    handlers: {
+      emission: handlerEmissionCounts
+    },
+    stream: {
+      suspenseBoundaryCount: artifacts.streamBoundaries.suspenseBoundaries.length,
+      reveal: {
+        byOrder: revealOrderCounts,
+        byTail: revealTailCounts
+      }
+    },
+    serverOnlyModuleExclusions: artifacts.sourceInventory.serverModules.length,
+    generatedLocatorCount: countGraphLocators(artifacts.jsxSemanticGraph)
+  };
+}
+
+export function hasOptimizerErrors(diagnostics = []) {
+  return arrayOf(diagnostics).some((diagnostic) => diagnostic.severity === "error");
+}
+
+function parseVersionMajor(version) {
+  const match = String(version ?? "").match(/^(\d+)/);
+  return match ? Number(match[1]) : 0;
+}
+
+function getDiagnostics(options) {
+  return Array.isArray(options.diagnostics) ? options.diagnostics : [];
+}
+
+function addDiagnostic(diagnostics, code, message, details = {}) {
+  diagnostics.push({
+    severity: "error",
+    code,
+    message,
+    ...details
+  });
+}
+
+function arrayOf(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function requireFeatureId(feature, label, diagnostics, pass) {
+  const id = feature.sourceId ?? feature.id;
+  if (id) {
+    return id;
+  }
+  addDiagnostic(diagnostics, `${label}-id-missing`, `${label} feature is missing a stable id.`, { pass });
+  return null;
+}
+
+function normalizeReads(reads) {
+  return arrayOf(reads).map((read) => {
+    if (typeof read === "string") {
+      return { sourceId: read };
+    }
+    return read;
+  });
+}
+
+function normalizeOwner(owner) {
+  if (owner === "global") {
+    return "app";
+  }
+  if (owner === "module") {
+    return "shared-module";
+  }
+  if (owner === "app" || owner === "shared-module" || owner === "component" || owner === "owner-relative") {
+    return owner;
+  }
+  return null;
+}
+
+function ownershipReason(owner) {
+  if (owner === "app") {
+    return "module-level signal is shared across the app graph";
+  }
+  if (owner === "shared-module") {
+    return "module-level signal is shared by imported modules";
+  }
+  if (owner === "component") {
+    return "signal is created inside component instance scope";
+  }
+  return "signal ownership is relative to the current owner";
+}
+
+function jsxEventType(propName) {
+  if (typeof propName !== "string" || !/^on[A-Z]/.test(propName)) {
+    return null;
+  }
+  return propName.slice(2).replace(/[A-Z]/g, (letter, index) => {
+    const lower = letter.toLowerCase();
+    return index === 0 ? lower : `-${lower}`;
+  });
+}
+
+function normalizeCommands(commands, handlerId, syncEventApis = []) {
+  const normalized = arrayOf(commands).map((command) => Array.isArray(command) ? command : [command]);
+  if (!normalized.some((command) => command[0] === "handler")) {
+    normalized.push(["handler", handlerId]);
+  }
+  for (const api of arrayOf(syncEventApis)) {
+    if (!normalized.some((command) => command[0] === api)) {
+      normalized.unshift([api]);
+    }
+  }
+  return normalized;
+}
+
+function commitOrderForReveal(order, sourceOrder, arrivalOrder) {
+  if (order === "as-ready") {
+    return arrivalOrder.length > 0 ? arrivalOrder : sourceOrder;
+  }
+  if (order === "backwards") {
+    return [...sourceOrder].reverse();
+  }
+  return sourceOrder;
+}
+
+function chooseRuntimeEntrypoint(features) {
+  if (features.hasSignals && !features.hasEvents && !features.hasAsyncSignals && !features.hasStream) {
+    return RUNTIME_ENTRYPOINTS.signals;
+  }
+  if (features.hasEvents && !features.hasSignals && !features.hasAsyncSignals && !features.hasStream) {
+    return RUNTIME_ENTRYPOINTS.events;
+  }
+  return RUNTIME_ENTRYPOINTS.runtime;
+}
+
+function omittedSystemReason(system) {
+  if (system === "no-build-loader") {
+    return "build profile emits an explicit runtime plan instead of scanning HTML through the no-build loader";
+  }
+  if (system === "server") {
+    return "server-only modules are excluded from browser output";
+  }
+  return "feature graph does not require this no-build system";
+}
+
+function countBy(items, key, knownKeys = []) {
+  const counts = Object.fromEntries(knownKeys.map((knownKey) => [knownKey, 0]));
+  for (const item of arrayOf(items)) {
+    const value = item[key];
+    counts[value] = (counts[value] ?? 0) + 1;
+  }
+  return counts;
+}
+
+function countWhere(items, predicate) {
+  return arrayOf(items).filter(predicate).length;
+}
+
+function countGraphLocators(graph) {
+  let total = arrayOf(graph.locators).length;
+  for (const component of arrayOf(graph.components)) {
+    total += arrayOf(component.locators).length;
+  }
+  return total;
+}

package/build-profile.js

@@ -0,0 +1,146 @@
+import {
+  createOptimizerArtifactSet,
+  hasOptimizerErrors
+} from "./build-optimizer.js";
+
+export const BUILD_PROFILE_VERSION = 1;
+export const BUILD_PROFILE_NAME = "build-required";
+export const VIRTUAL_PLAN_ID = "virtual:async-framework/generated-plan";
+export const RESOLVED_VIRTUAL_PLAN_ID = "\0virtual:async-framework/generated-plan";
+
+export function createBuildProfileReport(fixture = {}, options = {}) {
+  const artifactSet = createOptimizerArtifactSet(fixture);
+  const diagnostics = [...artifactSet.diagnostics];
+  const plan = createBuildProfilePlan(fixture, artifactSet);
+  const bootstrap = createBuildProfileBootstrap(artifactSet.report.runtime.entrypoint);
+  const report = {
+    version: BUILD_PROFILE_VERSION,
+    profile: BUILD_PROFILE_NAME,
+    mode: options.mode ?? fixture.mode ?? "development",
+    host: normalizeBuildHost(fixture.sourceInventory?.config?.host),
+    runtime: artifactSet.report.runtime,
+    signals: artifactSet.report.signals,
+    events: artifactSet.report.events,
+    handlers: artifactSet.report.handlers,
+    stream: artifactSet.report.stream,
+    serverOnlyModuleExclusions: artifactSet.report.serverOnlyModuleExclusions,
+    generatedLocatorCount: artifactSet.report.generatedLocatorCount,
+    virtualModules: [VIRTUAL_PLAN_ID],
+    diagnostics
+  };
+
+  return {
+    version: BUILD_PROFILE_VERSION,
+    profile: BUILD_PROFILE_NAME,
+    artifacts: artifactSet.artifacts,
+    diagnostics,
+    failed: hasOptimizerErrors(diagnostics),
+    plan,
+    report,
+    bootstrap
+  };
+}
+
+export function createBuildProfilePlan(fixture = {}, artifactSet = createOptimizerArtifactSet(fixture)) {
+  if (fixture.runtimePlan) {
+    return normalizeRuntimePlan(fixture.runtimePlan);
+  }
+
+  const locators = artifactSet.artifacts.jsxSemanticGraph.locators;
+  const signalSources = artifactSet.artifacts.signalSources.sources;
+  const eventSymbols = artifactSet.artifacts.eventSymbols.events;
+  const elementIndex = new Map(locators.map((locator, index) => [locator, index]));
+  const plan = {
+    version: 1,
+    elements: locators,
+    signals: undefined,
+    events: undefined
+  };
+
+  const values = signalSources
+    .filter((source) => source.kind === "writable")
+    .map((source) => [source.sourceId, source.initialValue]);
+  if (values.length > 0) {
+    plan.signals = {
+      version: 1,
+      values,
+      bindings: fixture.signalBindings ?? []
+    };
+  }
+
+  if (eventSymbols.length > 0) {
+    plan.events = {
+      version: 1,
+      events: eventSymbols.map((event) => [
+        elementIndex.get(event.elementId) ?? 0,
+        event.eventType,
+        event.commands
+      ]),
+      handlers: fixture.handlers ?? {}
+    };
+  }
+
+  return withoutUndefined(plan);
+}
+
+export function createBuildProfileBootstrap(entrypoint) {
+  return {
+    entrypoint,
+    virtualPlan: VIRTUAL_PLAN_ID,
+    usesAsyncGlobal: false,
+    importsRootAsync: false
+  };
+}
+
+export function emitGeneratedPlanModule(profile) {
+  return [
+    "// Generated by @async/framework/vite. Do not edit.",
+    `export const plan = ${stableJson(profile.plan)};`,
+    `export const report = ${stableJson(profile.report)};`,
+    "export default plan;",
+    ""
+  ].join("\n");
+}
+
+export function emitBootstrapModule(profile) {
+  return [
+    "// Generated by @async/framework/vite. Do not edit.",
+    `import { start } from ${JSON.stringify(profile.bootstrap.entrypoint)};`,
+    `import { plan } from ${JSON.stringify(VIRTUAL_PLAN_ID)};`,
+    "",
+    "export { plan };",
+    "export function startAsyncFramework(root = document, options = {}) {",
+    "  return start(root, plan, options);",
+    "}",
+    ""
+  ].join("\n");
+}
+
+function normalizeRuntimePlan(plan) {
+  if (!plan || typeof plan !== "object") {
+    throw new TypeError("Build profile runtime plan must be an object.");
+  }
+  if (plan.version !== 1) {
+    throw new Error(`Unsupported build profile runtime plan version: ${String(plan.version)}.`);
+  }
+  return {
+    version: 1,
+    ...plan
+  };
+}
+
+function normalizeBuildHost(host = {}) {
+  return {
+    name: host.name ?? "vite",
+    version: host.version ?? String(host.major ?? host.versionMajor ?? "8"),
+    engine: host.engine ?? "rolldown"
+  };
+}
+
+function withoutUndefined(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+
+function stableJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}

package/jsx.d.ts

@@ -0,0 +1,14 @@
+// Generated by scripts/build-framework-bundle.js. Do not edit by hand.
+// Type declarations for @async/framework/jsx.
+
+export declare const ASYNC_JSX_SIGNAL: unique symbol;
+export declare const ASYNC_JSX_COMPONENT: unique symbol;
+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 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 Suspense(props?: Record<string, unknown>): JsxBoundary;
+export declare function Reveal(props?: Record<string, unknown>): JsxBoundary;

package/jsx.js

@@ -0,0 +1,48 @@
+export const ASYNC_JSX_SIGNAL = Symbol.for("async.framework.jsx.signal");
+export const ASYNC_JSX_COMPONENT = Symbol.for("async.framework.jsx.component");
+export const ASYNC_JSX_SUSPENSE = Symbol.for("async.framework.jsx.suspense");
+export const ASYNC_JSX_REVEAL = Symbol.for("async.framework.jsx.reveal");
+
+export function signal(source, options = {}) {
+  return Object.freeze({
+    kind: "async-jsx-signal",
+    type: ASYNC_JSX_SIGNAL,
+    source,
+    options: freezeOptions(options)
+  });
+}
+
+export function component(render, options = {}) {
+  if (typeof render !== "function") {
+    throw new TypeError("component(...) expects a render function.");
+  }
+  return Object.freeze({
+    kind: "async-jsx-component",
+    type: ASYNC_JSX_COMPONENT,
+    render,
+    options: freezeOptions(options)
+  });
+}
+
+export function Suspense(props = {}) {
+  return Object.freeze({
+    kind: "async-jsx-suspense",
+    type: ASYNC_JSX_SUSPENSE,
+    props: freezeOptions(props)
+  });
+}
+
+export function Reveal(props = {}) {
+  return Object.freeze({
+    kind: "async-jsx-reveal",
+    type: ASYNC_JSX_REVEAL,
+    props: freezeOptions(props)
+  });
+}
+
+function freezeOptions(options) {
+  if (!options || typeof options !== "object") {
+    return {};
+  }
+  return Object.freeze({ ...options });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@async/framework",
-  "version": "0.11.17",
+  "version": "0.11.19",
   "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",
   "sideEffects": false,
@@ -60,6 +60,16 @@
       "import": "./server.js",
       "default": "./server.js"
     },
+    "./jsx": {
+      "types": "./jsx.d.ts",
+      "import": "./jsx.js",
+      "default": "./jsx.js"
+    },
+    "./vite": {
+      "types": "./vite.d.ts",
+      "import": "./vite.js",
+      "default": "./vite.js"
+    },
     "./runtime": {
       "types": "./runtime.d.ts",
       "import": "./runtime.js",
@@ -91,9 +101,15 @@
     "framework.ts",
     "package.json",
     "server.js",
+    "jsx.d.ts",
+    "vite.d.ts",
     "runtime.d.ts",
     "runtime/signals.d.ts",
     "runtime/events.d.ts",
+    "jsx.js",
+    "vite.js",
+    "build-profile.js",
+    "build-optimizer.js",
     "runtime.js",
     "runtime/signals.js",
     "runtime/events.js",

package/vite.d.ts

@@ -0,0 +1,18 @@
+// Generated by scripts/build-framework-bundle.js. Do not edit by hand.
+// Type declarations for @async/framework/vite.
+
+export type ViteRolldownHost = { readonly name?: string; readonly version?: string | number; readonly viteVersion?: string | number; readonly versionMajor?: string | number; readonly engine?: string; readonly builder?: string | { readonly name?: string }; readonly rolldown?: boolean };
+export type AsyncFrameworkPluginOptions = { readonly fixture?: Record<string, unknown>; readonly mode?: "development" | "production" | string; readonly host?: ViteRolldownHost };
+export type AsyncFrameworkVitePlugin = {
+  readonly name: "async-framework";
+  readonly enforce: "pre";
+  readonly asyncFramework: { readonly profile: Record<string, unknown>; readonly report: Record<string, unknown> };
+  configResolved(config: ViteRolldownHost): void;
+  resolveId(id: string): string | null;
+  load(id: string): string | null;
+  transform(code: string, id: string): { code: string; map: null } | null;
+  getAsyncFrameworkReport(): Record<string, unknown>;
+};
+export declare function asyncFramework(options?: AsyncFrameworkPluginOptions): AsyncFrameworkVitePlugin;
+export declare function validateViteRolldownHost(host?: ViteRolldownHost): Required<Pick<ViteRolldownHost, "name" | "version" | "engine">>;
+export declare function normalizeViteHost(host?: ViteRolldownHost): Required<Pick<ViteRolldownHost, "name" | "version" | "engine">>;

package/vite.js

@@ -0,0 +1,82 @@
+import {
+  RESOLVED_VIRTUAL_PLAN_ID,
+  VIRTUAL_PLAN_ID,
+  createBuildProfileReport,
+  emitBootstrapModule,
+  emitGeneratedPlanModule
+} from "./build-profile.js";
+
+export function asyncFramework(options = {}) {
+  const host = normalizeViteHost(options.host);
+  validateViteRolldownHost(host);
+  const profile = createBuildProfileReport(options.fixture ?? {}, {
+    mode: options.mode ?? "development"
+  });
+
+  return {
+    name: "async-framework",
+    enforce: "pre",
+    asyncFramework: {
+      profile,
+      report: profile.report
+    },
+    configResolved(config) {
+      validateViteRolldownHost(normalizeViteHost(options.host ?? config));
+    },
+    resolveId(id) {
+      if (id === VIRTUAL_PLAN_ID) {
+        return RESOLVED_VIRTUAL_PLAN_ID;
+      }
+      return null;
+    },
+    load(id) {
+      if (id === RESOLVED_VIRTUAL_PLAN_ID) {
+        return emitGeneratedPlanModule(profile);
+      }
+      return null;
+    },
+    transform(code, id) {
+      if (!isJsxModule(id) || !usesAsyncJsx(code)) {
+        return null;
+      }
+      return {
+        code: emitBootstrapModule(profile),
+        map: null
+      };
+    },
+    getAsyncFrameworkReport() {
+      return profile.report;
+    }
+  };
+}
+
+export function validateViteRolldownHost(host = {}) {
+  const normalized = normalizeViteHost(host);
+  if (normalized.name !== "vite") {
+    throw new Error(`@async/framework/vite requires Vite 8+ with Rolldown; received ${normalized.name}.`);
+  }
+  if (Number.parseInt(normalized.version, 10) < 8) {
+    throw new Error(`@async/framework/vite requires Vite 8+; received ${normalized.version}.`);
+  }
+  if (normalized.engine !== "rolldown") {
+    throw new Error(`@async/framework/vite requires the Rolldown engine; received ${normalized.engine}.`);
+  }
+  return normalized;
+}
+
+export function normalizeViteHost(host = {}) {
+  const builder = host.builder && typeof host.builder === "object" ? host.builder.name : host.builder;
+  return {
+    name: host.name ?? "vite",
+    version: String(host.version ?? host.viteVersion ?? host.versionMajor ?? "8.0.0"),
+    engine: host.engine ?? builder ?? (host.rolldown === false ? "rollup" : "rolldown")
+  };
+}
+
+function isJsxModule(id) {
+  return /\.(?:jsx|tsx)$/.test(String(id));
+}
+
+function usesAsyncJsx(source) {
+  return /@async\/framework\/jsx/.test(source);
+}