@moku-labs/web 1.16.0 → 1.17.0

package/dist/browser.d.mts

@@ -871,7 +871,7 @@ type Api$1 = {
   composeTitle(head: HeadConfig | undefined): string;
 };
 declare namespace types_d_exports$4 {
-  export { COMPONENT_HOOK_NAMES, ComponentContext, ComponentDef, ComponentEventHandler, ComponentEvents, ComponentHooks, ComponentInstance, ComponentRender, ComponentRouteSlice, ComponentSpec, ComponentSpecExtras, ComponentStateFactory, ExtractApi, PageData, RenderResult, ResolvedSpaConfig, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState };
+  export { AnyVNode, COMPONENT_HOOK_NAMES, ComponentContext, ComponentDef, ComponentEventHandler, ComponentEvents, ComponentHooks, ComponentInstance, ComponentRender, ComponentRouteSlice, ComponentSpec, ComponentSpecExtras, ComponentStateFactory, ExtractApi, PageData, RenderResult, ResolvedSpaConfig, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState };
 }
 /** Payload map for the events `spa` emits, used to type the kernel's `emit` closure. */
 type SpaEvents = {
@@ -978,7 +978,13 @@ interface ResolvedSpaConfig {
  * - a `string` — set as the host's `innerHTML`;
  * - `void`/`undefined` — the render mutated the DOM itself (DOM-only islands → no Preact loaded).
  */
-type RenderResult = import("preact").VNode | Node | string | void;
+type RenderResult = AnyVNode | Node | string | void;
+/**
+ * A Preact `VNode` of ANY props shape. A render returns `h(Component, props)`, i.e. a
+ * `VNode<SomeProps>`; the props generic is invariant under `exactOptionalPropertyTypes`,
+ * so the only supertype that accepts every concrete `VNode<P>` is `VNode<any>`.
+ */
+type AnyVNode = import("preact").VNode<any>;
 /**
  * Factory that builds a component's typed per-instance state (mirrors a plugin's
  * `createState`). Called ONCE at mount; the returned object is stored on the

package/dist/browser.mjs

@@ -2518,6 +2518,13 @@ const COMPONENT_HOOK_NAMES = [
 ];
 //#endregion
 //#region src/plugins/spa/components.ts
+/**
+* @file spa plugin — component lifecycle, mounting, the plugin-mirror authoring
+* surface (`createComponent` with a typed `{ state, render, events, api }` spec),
+* the per-instance state + microtask-batched render scheduler, declarative
+* delegated events, and the cross-island api registry.
+* @see README.md
+*/
 /** Error prefix for spa fail-fast failures (spec/11 Part-3). */
 const ERROR_PREFIX$2 = "[web]";
 /** The set of legal hook names, frozen for O(1) membership checks. */

package/dist/index.cjs

@@ -8039,17 +8039,22 @@ function createApi$1(ctx) {
 		* @example
 		* await api.update(["src/islands/board.ts"]);
 		*/
-		update(changes, options = {}) {
+		async update(changes, options = {}) {
 			const overrides = devBuildOverrides({
 				og: options.og ?? false,
 				sitemap: options.sitemap ?? false,
 				feeds: options.feeds ?? false
 			});
-			return ctx.require(buildPlugin).run({
-				skipClean: true,
-				overrides,
-				changed: changes
-			});
+			ctx.state.render.setDriven(true);
+			try {
+				return await ctx.require(buildPlugin).run({
+					skipClean: true,
+					overrides,
+					changed: changes
+				});
+			} finally {
+				ctx.state.render.setDriven(false);
+			}
 		},
 		/**
 		* Dev loop: build once, serve `dist/` in-process (live-reload injected), watch
@@ -8342,6 +8347,7 @@ function createPanelRenderer(options = {}) {
 	let idle = false;
 	let idleStartedAt = 0;
 	let serveMode = false;
+	let driven = false;
 	let ticker;
 	/**
 	* Render one phase-tree row: a spinning cyan glyph + dim name while running, or a green
@@ -8503,7 +8509,7 @@ function createPanelRenderer(options = {}) {
 		* render.phase({ phase: "pages", status: "done", durationMs: 12 });
 		*/
 		phase(phase) {
-			if (rebuilding) return;
+			if (rebuilding || driven) return;
 			if (!color) {
 				if (phase.status === "done") write(`  ${palette.green("✓")} ${phase.phase}${durationSuffix(palette, phase.durationMs)}`);
 				return;
@@ -8537,7 +8543,7 @@ function createPanelRenderer(options = {}) {
 		* render.built({ outDir: "dist", pageCount: 12, durationMs: 840 });
 		*/
 		built(summary) {
-			if (rebuilding) return;
+			if (rebuilding || driven) return;
 			if (color && phaseOpen) {
 				let frame = (0, _moku_labs_common_cli.cursorUp)(phaseDrawn);
 				for (const row of phaseRows) frame += `${_moku_labs_common_cli.CLEAR_LINE}${renderPhaseRow(row)}\n`;
@@ -8711,6 +8717,20 @@ function createPanelRenderer(options = {}) {
 			if (detail !== void 0) for (const line of detail.split("\n")) write(`      ${palette.dim(line)}`);
 		},
 		/**
+		* Mark the build TUI as externally driven: when `on`, the per-phase build tree and the BUILD
+		* summary are suppressed so an external dev driver (e.g. the worker's `dev({ onChange })` loop,
+		* which calls `update()` and renders its own concise rebuild line) is the sole source of rebuild
+		* output. Off by default; a standalone `build()` / `serve()` renders the full TUI as before.
+		*
+		* @param on - Whether an external driver owns the dev TUI.
+		* @example
+		* render.setDriven(true);  // before an externally-driven update()
+		* render.setDriven(false); // after it settles
+		*/
+		setDriven(on) {
+			driven = on;
+		},
+		/**
 		* Stop every animation and release the interval timer (serve()'s teardown calls this).
 		*
 		* @example
@@ -9204,6 +9224,13 @@ const COMPONENT_HOOK_NAMES = [
 ];
 //#endregion
 //#region src/plugins/spa/components.ts
+/**
+* @file spa plugin — component lifecycle, mounting, the plugin-mirror authoring
+* surface (`createComponent` with a typed `{ state, render, events, api }` spec),
+* the per-instance state + microtask-batched render scheduler, declarative
+* delegated events, and the cross-island api registry.
+* @see README.md
+*/
 /** Error prefix for spa fail-fast failures (spec/11 Part-3). */
 const ERROR_PREFIX$2 = "[web]";
 /** The set of legal hook names, frozen for O(1) membership checks. */

package/dist/index.d.cts

@@ -872,7 +872,7 @@ type Api$4 = {
   composeTitle(head: HeadConfig | undefined): string;
 };
 declare namespace types_d_exports$7 {
-  export { COMPONENT_HOOK_NAMES, ComponentContext, ComponentDef, ComponentEventHandler, ComponentEvents, ComponentHooks, ComponentInstance, ComponentRender, ComponentRouteSlice, ComponentSpec, ComponentSpecExtras, ComponentStateFactory, ExtractApi$1 as ExtractApi, PageData, RenderResult, ResolvedSpaConfig, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState };
+  export { AnyVNode, COMPONENT_HOOK_NAMES, ComponentContext, ComponentDef, ComponentEventHandler, ComponentEvents, ComponentHooks, ComponentInstance, ComponentRender, ComponentRouteSlice, ComponentSpec, ComponentSpecExtras, ComponentStateFactory, ExtractApi$1 as ExtractApi, PageData, RenderResult, ResolvedSpaConfig, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState };
 }
 /** Payload map for the events `spa` emits, used to type the kernel's `emit` closure. */
 type SpaEvents = {
@@ -979,7 +979,13 @@ interface ResolvedSpaConfig {
  * - a `string` — set as the host's `innerHTML`;
  * - `void`/`undefined` — the render mutated the DOM itself (DOM-only islands → no Preact loaded).
  */
-type RenderResult = import("preact").VNode | Node | string | void;
+type RenderResult = AnyVNode | Node | string | void;
+/**
+ * A Preact `VNode` of ANY props shape. A render returns `h(Component, props)`, i.e. a
+ * `VNode<SomeProps>`; the props generic is invariant under `exactOptionalPropertyTypes`,
+ * so the only supertype that accepts every concrete `VNode<P>` is `VNode<any>`.
+ */
+type AnyVNode = import("preact").VNode<any>;
 /**
  * Factory that builds a component's typed per-instance state (mirrors a plugin's
  * `createState`). Called ONCE at mount; the returned object is stored on the
@@ -2213,6 +2219,19 @@ type CliRenderer = {
    * render.check(false, "CLOUDFLARE_API_TOKEN is set", "Create one at …");
    */
   check(ok: boolean, label: string, detail?: string): void;
+  /**
+   * Mark the build TUI as externally driven. When `on`, the per-phase build tree and the BUILD
+   * summary block are suppressed, so an external dev driver (e.g. the worker's `dev({ onChange })`
+   * loop, which calls `update()` and renders its own concise rebuild line) is the sole source of
+   * rebuild output — no duplicate full TUI on each incremental rebuild. Off by default; a standalone
+   * `build()` / `serve()` keeps the full TUI.
+   *
+   * @param on - Whether an external driver owns the dev TUI.
+   * @returns Nothing.
+   * @example
+   * render.setDriven(true);
+   */
+  setDriven(on: boolean): void;
   /**
    * Stop any running animation (the live `serve()` idle pulse, a phase/rebuild spinner)
    * and release the renderer's interval timer. Called by `serve()`'s SIGINT/SIGTERM

package/dist/index.d.mts

@@ -870,7 +870,7 @@ type Api$4 = {
   composeTitle(head: HeadConfig | undefined): string;
 };
 declare namespace types_d_exports$7 {
-  export { COMPONENT_HOOK_NAMES, ComponentContext, ComponentDef, ComponentEventHandler, ComponentEvents, ComponentHooks, ComponentInstance, ComponentRender, ComponentRouteSlice, ComponentSpec, ComponentSpecExtras, ComponentStateFactory, ExtractApi$1 as ExtractApi, PageData, RenderResult, ResolvedSpaConfig, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState };
+  export { AnyVNode, COMPONENT_HOOK_NAMES, ComponentContext, ComponentDef, ComponentEventHandler, ComponentEvents, ComponentHooks, ComponentInstance, ComponentRender, ComponentRouteSlice, ComponentSpec, ComponentSpecExtras, ComponentStateFactory, ExtractApi$1 as ExtractApi, PageData, RenderResult, ResolvedSpaConfig, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState };
 }
 /** Payload map for the events `spa` emits, used to type the kernel's `emit` closure. */
 type SpaEvents = {
@@ -977,7 +977,13 @@ interface ResolvedSpaConfig {
  * - a `string` — set as the host's `innerHTML`;
  * - `void`/`undefined` — the render mutated the DOM itself (DOM-only islands → no Preact loaded).
  */
-type RenderResult = import("preact").VNode | Node | string | void;
+type RenderResult = AnyVNode | Node | string | void;
+/**
+ * A Preact `VNode` of ANY props shape. A render returns `h(Component, props)`, i.e. a
+ * `VNode<SomeProps>`; the props generic is invariant under `exactOptionalPropertyTypes`,
+ * so the only supertype that accepts every concrete `VNode<P>` is `VNode<any>`.
+ */
+type AnyVNode = import("preact").VNode<any>;
 /**
  * Factory that builds a component's typed per-instance state (mirrors a plugin's
  * `createState`). Called ONCE at mount; the returned object is stored on the
@@ -2211,6 +2217,19 @@ type CliRenderer = {
    * render.check(false, "CLOUDFLARE_API_TOKEN is set", "Create one at …");
    */
   check(ok: boolean, label: string, detail?: string): void;
+  /**
+   * Mark the build TUI as externally driven. When `on`, the per-phase build tree and the BUILD
+   * summary block are suppressed, so an external dev driver (e.g. the worker's `dev({ onChange })`
+   * loop, which calls `update()` and renders its own concise rebuild line) is the sole source of
+   * rebuild output — no duplicate full TUI on each incremental rebuild. Off by default; a standalone
+   * `build()` / `serve()` keeps the full TUI.
+   *
+   * @param on - Whether an external driver owns the dev TUI.
+   * @returns Nothing.
+   * @example
+   * render.setDriven(true);
+   */
+  setDriven(on: boolean): void;
   /**
    * Stop any running animation (the live `serve()` idle pulse, a phase/rebuild spinner)
    * and release the renderer's interval timer. Called by `serve()`'s SIGINT/SIGTERM

package/dist/index.mjs

@@ -8026,17 +8026,22 @@ function createApi$1(ctx) {
 		* @example
 		* await api.update(["src/islands/board.ts"]);
 		*/
-		update(changes, options = {}) {
+		async update(changes, options = {}) {
 			const overrides = devBuildOverrides({
 				og: options.og ?? false,
 				sitemap: options.sitemap ?? false,
 				feeds: options.feeds ?? false
 			});
-			return ctx.require(buildPlugin).run({
-				skipClean: true,
-				overrides,
-				changed: changes
-			});
+			ctx.state.render.setDriven(true);
+			try {
+				return await ctx.require(buildPlugin).run({
+					skipClean: true,
+					overrides,
+					changed: changes
+				});
+			} finally {
+				ctx.state.render.setDriven(false);
+			}
 		},
 		/**
 		* Dev loop: build once, serve `dist/` in-process (live-reload injected), watch
@@ -8329,6 +8334,7 @@ function createPanelRenderer(options = {}) {
 	let idle = false;
 	let idleStartedAt = 0;
 	let serveMode = false;
+	let driven = false;
 	let ticker;
 	/**
 	* Render one phase-tree row: a spinning cyan glyph + dim name while running, or a green
@@ -8490,7 +8496,7 @@ function createPanelRenderer(options = {}) {
 		* render.phase({ phase: "pages", status: "done", durationMs: 12 });
 		*/
 		phase(phase) {
-			if (rebuilding) return;
+			if (rebuilding || driven) return;
 			if (!color) {
 				if (phase.status === "done") write(`  ${palette.green("✓")} ${phase.phase}${durationSuffix(palette, phase.durationMs)}`);
 				return;
@@ -8524,7 +8530,7 @@ function createPanelRenderer(options = {}) {
 		* render.built({ outDir: "dist", pageCount: 12, durationMs: 840 });
 		*/
 		built(summary) {
-			if (rebuilding) return;
+			if (rebuilding || driven) return;
 			if (color && phaseOpen) {
 				let frame = cursorUp(phaseDrawn);
 				for (const row of phaseRows) frame += `${CLEAR_LINE}${renderPhaseRow(row)}\n`;
@@ -8698,6 +8704,20 @@ function createPanelRenderer(options = {}) {
 			if (detail !== void 0) for (const line of detail.split("\n")) write(`      ${palette.dim(line)}`);
 		},
 		/**
+		* Mark the build TUI as externally driven: when `on`, the per-phase build tree and the BUILD
+		* summary are suppressed so an external dev driver (e.g. the worker's `dev({ onChange })` loop,
+		* which calls `update()` and renders its own concise rebuild line) is the sole source of rebuild
+		* output. Off by default; a standalone `build()` / `serve()` renders the full TUI as before.
+		*
+		* @param on - Whether an external driver owns the dev TUI.
+		* @example
+		* render.setDriven(true);  // before an externally-driven update()
+		* render.setDriven(false); // after it settles
+		*/
+		setDriven(on) {
+			driven = on;
+		},
+		/**
 		* Stop every animation and release the interval timer (serve()'s teardown calls this).
 		*
 		* @example
@@ -9191,6 +9211,13 @@ const COMPONENT_HOOK_NAMES = [
 ];
 //#endregion
 //#region src/plugins/spa/components.ts
+/**
+* @file spa plugin — component lifecycle, mounting, the plugin-mirror authoring
+* surface (`createComponent` with a typed `{ state, render, events, api }` spec),
+* the per-instance state + microtask-batched render scheduler, declarative
+* delegated events, and the cross-island api registry.
+* @see README.md
+*/
 /** Error prefix for spa fail-fast failures (spec/11 Part-3). */
 const ERROR_PREFIX$2 = "[web]";
 /** The set of legal hook names, frozen for O(1) membership checks. */

package/dist/testing.d.mts

@@ -6,7 +6,13 @@
  * - a `string` — set as the host's `innerHTML`;
  * - `void`/`undefined` — the render mutated the DOM itself (DOM-only islands → no Preact loaded).
  */
-type RenderResult = import("preact").VNode | Node | string | void;
+type RenderResult = AnyVNode | Node | string | void;
+/**
+ * A Preact `VNode` of ANY props shape. A render returns `h(Component, props)`, i.e. a
+ * `VNode<SomeProps>`; the props generic is invariant under `exactOptionalPropertyTypes`,
+ * so the only supertype that accepts every concrete `VNode<P>` is `VNode<any>`.
+ */
+type AnyVNode = import("preact").VNode<any>;
 /**
  * Factory that builds a component's typed per-instance state (mirrors a plugin's
  * `createState`). Called ONCE at mount; the returned object is stored on the

package/dist/testing.mjs

@@ -12,6 +12,13 @@ const COMPONENT_HOOK_NAMES = [
 ];
 //#endregion
 //#region src/plugins/spa/components.ts
+/**
+* @file spa plugin — component lifecycle, mounting, the plugin-mirror authoring
+* surface (`createComponent` with a typed `{ state, render, events, api }` spec),
+* the per-instance state + microtask-batched render scheduler, declarative
+* delegated events, and the cross-island api registry.
+* @see README.md
+*/
 /** Error prefix for spa fail-fast failures (spec/11 Part-3). */
 const ERROR_PREFIX = "[web]";
 new Set(COMPONENT_HOOK_NAMES);

package/package.json

@@ -132,5 +132,5 @@
     "test:build-e2e": "bun test src/plugins/build/__tests__/e2e/",
     "test:coverage": "vitest run --project unit --project integration --coverage"
   },
-  "version": "1.16.0"
+  "version": "1.17.0"
 }