@absolutejs/absolute 0.20.0-beta.72 → 0.20.0-beta.73

package/dist/src/dev/earlyListener.d.ts

@@ -1,5 +1,15 @@
 import type { Server } from 'bun';
 export declare const BOOT_STATUS_HEADER = "X-Absolute-Boot";
+/** Written by the child on fd 3 the instant the real server is bound, so
+ *  the CLI can close its placeholder. A dedicated pipe rather than stdout:
+ *  the marker must never reach the developer's terminal or the instance
+ *  log, and stdout chunks coalesce in ways that make stripping a line out
+ *  of the forwarded stream unreliable. */
+export declare const PARENT_HANDOFF_MARKER = "absolute:listening";
+/** Set on the child by the CLI when the CLI itself holds the placeholder
+ *  on the dev port. The child then skips its own placeholder and binds the
+ *  real server with `reusePort` so the two can overlap. */
+export declare const PARENT_LISTENER_ENV = "ABSOLUTE_PARENT_LISTENER";
 export type EarlyListenerOptions = {
     host: string;
     port: number;
@@ -7,6 +17,10 @@ export type EarlyListenerOptions = {
         cert: string;
         key: string;
     } | null;
+    /** Bind with `SO_REUSEPORT` so the child's real server can bind the
+     *  same port before this placeholder goes away. Only the CLI parent
+     *  sets it. */
+    reusePort?: boolean;
 };
 export type EarlyListener = {
     /** The placeholder server, or null while a bind retry is pending or
@@ -32,7 +46,25 @@ export declare const buildingResponse: (request: Request, startedAt: number) =>
  *  `networking` plugin: any `Bun.serve` that targets the placeholder's
  *  port first releases it. Installed once per process by the bootstrap. */
 export declare const installEarlyListenerServeGuard: (port: number) => void;
+/** Defensive hand-off for the parent-owned path: any `Bun.serve` that
+ *  targets the dev port is bound with `reusePort` (so it can come up while
+ *  the CLI's placeholder is still listening) and reports the bind back to
+ *  the CLI. The `networking` plugin does both explicitly; this guard is
+ *  what makes entries that call `.listen()` without it work too, mirroring
+ *  `installEarlyListenerServeGuard` on the child-owned path. */
+export declare const installParentPortHandoffGuard: (port: number) => void;
+/** `SO_REUSEPORT` is POSIX-only; Windows has no equivalent that lets two
+ *  processes share a listening socket, so the parent-side placeholder is
+ *  not offered there and the child's own placeholder stays in charge. */
+export declare const parentListenerSupported: () => boolean;
+/** True when the CLI parent, not this process, owns the placeholder. */
+export declare const parentOwnsDevPort: () => boolean;
 export declare const releaseEarlyListener: () => boolean;
+/** Tell the CLI parent that the real server is bound, so it can close its
+ *  placeholder. Idempotent, and silent when there is no hand-off pipe (the
+ *  bootstrap run directly, or a parent that never bound) — the CLI also
+ *  releases on the ready banner, so a missed signal is not fatal. */
+export declare const signalParentPortHandoff: (port: number) => void;
 /** Bind the placeholder. A failed bind (the previous child's socket is
  *  still draining, or the port genuinely conflicts) is retried in the
  *  background for a few seconds and then given up on silently — the real

package/dist/src/dev/importCost/deferability.d.ts

@@ -0,0 +1,11 @@
+export type EntryImport = {
+    line: number;
+    /** Why it is not deferrable, when it is not. */
+    reason: string | null;
+    specifier: string;
+    verdict: EntryImportVerdict;
+};
+export type EntryImportVerdict = 'deferrable' | 'side-effect import' | 'type-only' | 'used at module scope';
+/** One verdict per top-level import (and re-export) of the entry, in source
+ *  order. Pure: give it the entry's text, get the verdicts back. */
+export declare const analyzeEntryImports: (sourceText: string, fileName: string) => EntryImport[];

package/dist/src/dev/importCost/dominators.d.ts

@@ -0,0 +1,37 @@
+export type ImportCandidate = {
+    specifier: string;
+    /** Module index the specifier resolved to, or `-1` if it never loaded. */
+    target: number;
+};
+export type ImportSaving = {
+    /** Modules that become unreachable when this edge is removed. */
+    count: number;
+    savingMs: number;
+    specifier: string;
+    target: number;
+};
+export type ImportSavings = {
+    attributedCount: number;
+    attributedMs: number;
+    candidates: ImportSaving[];
+    reachableCount: number;
+    sharedBaseCount: number;
+    sharedBaseMs: number;
+    totalMs: number;
+};
+export type SavingsInput = {
+    candidates: readonly ImportCandidate[];
+    edges: ReadonlyArray<readonly number[]>;
+    /** Module whose top-level imports the candidates are — the user's entry. */
+    entry: number;
+    /** Process root (the dev bootstrap), where reachability starts. */
+    root: number;
+    selfMs: readonly number[];
+};
+/** The modules dominated by the edge `from -> to`: reachable from the root
+ *  today, unreachable once that edge is gone. */
+export declare const dominatedByEdge: (edges: ReadonlyArray<readonly number[]>, root: number, fromIndex: number, toIndex: number, reachable?: Uint8Array) => number[];
+/** Modules reachable from `root`, optionally with the single edge
+ *  `skipFrom -> skipTo` removed. */
+export declare const reachableFrom: (edges: ReadonlyArray<readonly number[]>, root: number, skipFrom?: number, skipTo?: number) => Uint8Array<ArrayBuffer>;
+export declare const summarizeImportSavings: (input: SavingsInput) => ImportSavings;

package/dist/src/dev/importCost/format.d.ts

@@ -0,0 +1,29 @@
+export type ImportCostReport = {
+    entryLabel: string;
+    /** Modules whose exit call never ran; their self time is approximate. */
+    incomplete: number;
+    /** Out-of-order exits, i.e. top-level `await` interleaving. */
+    interleaved: number;
+    /** The entry's own body: everything it does after its imports, including
+     *  the `prepare()` the framework's boot build runs inside. */
+    entryBodyMs: number;
+    moduleCount: number;
+    /** Time that ran outside every instrumented module: CommonJS
+     *  dependencies, native modules, and the dev server's concurrent boot
+     *  build. Deliberately not credited to any import. */
+    outsideMs: number;
+    /** The recorder's own read-and-rewrite time, excluded from every figure
+     *  above and reported so the numbers can be sanity-checked. */
+    overheadMs: number;
+    rows: readonly ImportCostRow[];
+    sharedBaseCount: number;
+    sharedBaseMs: number;
+    totalMs: number;
+};
+export type ImportCostRow = {
+    count: number;
+    savingMs: number;
+    specifier: string;
+    verdict: string;
+};
+export declare const formatImportCostReport: (report: ImportCostReport) => string;

package/dist/src/dev/importCost/instrument.d.ts

@@ -0,0 +1,5 @@
+export type ImportCostLoader = 'js' | 'jsx' | 'ts' | 'tsx';
+/** The Bun loader to hand back with the rewritten contents. Bun infers
+ *  CommonJS versus ESM from the source, so `.cjs`/`.mjs` both take `js`. */
+export declare const importCostLoader: (path: string) => "ts" | "js" | "tsx" | "jsx";
+export declare const instrumentModuleSource: (source: string, moduleIndex: number) => string;

package/dist/src/dev/importCost/moduleGraph.d.ts

@@ -0,0 +1,13 @@
+export type StaticGraph = {
+    edges: number[][];
+    /** Modules that import a file this diagnostic could not instrument — a
+     *  CommonJS dependency. Bun loads and parses those inside the gap that
+     *  would otherwise be charged to this module, so its parse time is not
+     *  its own and must not be credited to an import. */
+    hasUninstrumentedImports: Uint8Array;
+};
+/** Adjacency built from re-scanning every loaded module's source. */
+export declare const buildStaticEdges: (moduleIds: readonly string[]) => StaticGraph;
+/** One inferred edge per orphan module: the innermost module whose body was
+ *  still open when the orphan started evaluating is the one that asked for it. */
+export declare const inferDynamicEdges: (edges: ReadonlyArray<readonly number[]>, events: readonly number[], root: number) => [number, number][];

package/dist/src/dev/importCost/recorder.d.ts

@@ -0,0 +1,37 @@
+export type ImportCostRecorder = {
+    /** The `.absolutejs-hmr-*` copy of the user's entry that the dev
+     *  bootstrap actually imports. Set by the bootstrap. */
+    entryModule: string | null;
+    /** The developer's own server entry path, for reporting. */
+    entryOriginalModule: string | null;
+    /** Flat pairs of `code, timeMs`, where `code = moduleIndex * 4 + kind`
+     *  and kind is one of `IMPORT_COST_EVENT`. Numbers, not objects: two
+     *  array pushes per boundary is cheap enough to leave the timings alone. */
+    events: number[];
+    moduleIds: string[];
+    moduleIndexes: Map<string, number>;
+    /** Cleared before the report runs so the report's own imports (and any
+     *  later `--hot` re-evaluation) never land in the measurement. */
+    recording: boolean;
+    /** The first module of the process — the dev bootstrap. Reachability is
+     *  rooted here rather than at the user's entry so that anything the
+     *  bootstrap loads on its own (the framework runtime, via the boot
+     *  prebuild) is correctly seen as shared rather than as the entry's. */
+    rootModule: string | null;
+};
+type ImportCostEventKinds = {
+    enter: number;
+    exit: number;
+    loadEnd: number;
+    loadStart: number;
+};
+export declare const IMPORT_COST_ENV = "ABSOLUTE_DEV_IMPORT_COST";
+/** Event kinds packed into the low bits of each event code.
+ *  `loadStart`/`loadEnd` bracket the plugin's own work so that reading and
+ *  rewriting a module is charged to nobody, and the gap that follows — Bun
+ *  parsing that module and resolving its imports — is charged to it. */
+export declare const IMPORT_COST_EVENT: ImportCostEventKinds;
+export declare const IMPORT_COST_EVENT_KINDS = 4;
+export declare const ensureImportCostRecorder: () => ImportCostRecorder;
+export declare const importCostEnabled: () => boolean;
+export {};

package/dist/src/dev/importCost/report.d.ts

@@ -0,0 +1,3 @@
+/** Prints the report. Never throws: a diagnostic must not be able to take a
+ *  boot down. */
+export declare const reportImportCost: () => void;

package/dist/src/dev/importCost/scope.d.ts

@@ -0,0 +1,10 @@
+export type EsmRegions = {
+    /** Directories inside an ESM region that switch back to CommonJS. */
+    cjsPrefixes: string[];
+    /** Directories whose subtree is ESM. */
+    esmPrefixes: string[];
+};
+/** The ESM regions of an app's installed dependencies. */
+export declare const esmRegions: (root: string) => EsmRegions;
+/** The `onLoad` filter: app sources, `.mjs`, and files in ESM regions. */
+export declare const instrumentableFilter: (regions: EsmRegions) => RegExp;

package/dist/src/dev/importCost/selfTimes.d.ts

@@ -0,0 +1,17 @@
+export type SelfTimes = {
+    evalMs: number[];
+    /** Timestamp of each module's first enter, or `NaN` if it never ran. */
+    firstEnterMs: number[];
+    incomplete: number[];
+    interleaved: number;
+    /** Time spent inside the plugin's own read-and-rewrite, charged to nobody. */
+    overheadMs: number;
+    /** Time with no module open and nothing being parsed: uninstrumented
+     *  CommonJS dependencies, native modules, and the dev server's own
+     *  concurrent work. Deliberately credited to no import. */
+    unownedMs: number;
+    parseMs: number[];
+    /** Modules' own parse plus evaluation, exclusive of their children. */
+    selfMs: number[];
+};
+export declare const computeSelfTimes: (events: readonly number[], moduleCount: number) => SelfTimes;

package/dist/src/dev/importCostPreload.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/dev/importCostReport.d.ts

@@ -0,0 +1 @@
+export { reportImportCost } from './importCost/report';

package/dist/types/globals.d.ts

@@ -9,6 +9,16 @@ declare global {
 	 * watchers and can observe entry/configuration edits. */
 	var __absoluteEntryWatcherReady: boolean | undefined;
 	var __absoluteEntryCopies: Set<string> | undefined;
+	/** Import-cost diagnostic (`ABSOLUTE_DEV_IMPORT_COST=1`). The recorder is
+	 *  filled by the preloaded `onLoad` plugin, read by the report, and
+	 *  written to by the dev bootstrap — three separate bundles, so it lives
+	 *  here rather than in module state. Stays unset unless the flag is on. */
+	var __absoluteImportCost:
+		| import('../src/dev/importCost/recorder').ImportCostRecorder
+		| undefined;
+	var __absoluteImportCostEnter: ((moduleIndex: number) => void) | undefined;
+	var __absoluteImportCostExit: ((moduleIndex: number) => void) | undefined;
+	var __absoluteImportCostReport: (() => Promise<void>) | undefined;
 	var __absoluteEntryBootstrapSequence: number | undefined;
 	var __absoluteEntryCleanupRegistered: boolean | undefined;
 	var __absoluteEntryWatcherStarted: boolean | undefined;
@@ -53,6 +63,11 @@ declare global {
 		| import('../src/dev/earlyListener').EarlyListener
 		| undefined;
 	var __absoluteEarlyListenerServeGuard: boolean | undefined;
+	/** Parent-owned hand-off (see `src/dev/earlyListener.ts`): the CLI holds
+	 *  the "Building…" placeholder, so this child skips its own, binds the
+	 *  real server with `reusePort` and reports the bind back exactly once. */
+	var __absoluteParentPortHandoffGuard: boolean | undefined;
+	var __absoluteParentHandoffSignalled: boolean | undefined;
 	/** Label of the boot step currently running (shown on the placeholder
 	 *  page). See `src/dev/bootLifecycle.ts`. */
 	var __absoluteBootPhase: string | undefined;

package/package.json

@@ -300,12 +300,12 @@
 	"main": "./dist/index.js",
 	"name": "@absolutejs/absolute",
 	"optionalDependencies": {
-		"@absolutejs/native-darwin-arm64": "0.20.0-beta.72",
-		"@absolutejs/native-darwin-x64": "0.20.0-beta.72",
-		"@absolutejs/native-linux-arm64": "0.20.0-beta.72",
-		"@absolutejs/native-linux-x64": "0.20.0-beta.72",
-		"@absolutejs/native-windows-arm64": "0.20.0-beta.72",
-		"@absolutejs/native-windows-x64": "0.20.0-beta.72"
+		"@absolutejs/native-darwin-arm64": "0.20.0-beta.73",
+		"@absolutejs/native-darwin-x64": "0.20.0-beta.73",
+		"@absolutejs/native-linux-arm64": "0.20.0-beta.73",
+		"@absolutejs/native-linux-x64": "0.20.0-beta.73",
+		"@absolutejs/native-windows-arm64": "0.20.0-beta.73",
+		"@absolutejs/native-windows-x64": "0.20.0-beta.73"
 	},
 	"overrides": {
 		"@sinclair/typebox": "0.34.52",
@@ -525,7 +525,7 @@
 			]
 		}
 	},
-	"version": "0.20.0-beta.72",
+	"version": "0.20.0-beta.73",
 	"workspaces": [
 		"tests/fixtures/*",
 		"tests/fixtures/_packages/*"