@alloy-js/core 0.24.0-dev.1 → 0.24.0-dev.6

package/src/context.ts

@@ -1,7 +1,7 @@
 import { shallowRef } from "@vue/reactivity";
 import { effect, getContext } from "./reactivity.js";
 import type { Children, ComponentDefinition } from "./runtime/component.js";
-import { stc, type StcSignature } from "./stc.js";
+import type { StcSignature } from "./stc.js";
 
 export interface ComponentContext<T> {
   id: symbol;
@@ -11,6 +11,23 @@ export interface ComponentContext<T> {
   name?: string;
 }
 
+let _stcImpl:
+  | (<T extends {}>(Component: ComponentDefinition<T>) => StcSignature<T>)
+  | null = null;
+
+/**
+ * Registers the {@link stc} factory used to lazily build `ProviderStc`.
+ * Called once by `stc.ts` at module initialization to break the
+ * `context.ts ↔ stc.ts` import cycle.
+ *
+ * @internal
+ */
+export function _registerStcImpl(
+  impl: <T extends {}>(Component: ComponentDefinition<T>) => StcSignature<T>,
+): void {
+  _stcImpl = impl;
+}
+
 export interface ContextProviderProps<T = unknown> {
   value?: T;
   children?: Children;
@@ -57,13 +74,29 @@ export function createContext<T = unknown>(
 
     return rendered.value;
   }
-  const ctx = {
+  const ctx: ComponentContext<T> = {
     id,
     default: defaultValue,
     name,
     Provider,
-    ProviderStc: stc(Provider),
-  };
+  } as ComponentContext<T>;
+  Object.defineProperty(ctx, "ProviderStc", {
+    configurable: true,
+    enumerable: true,
+    get() {
+      if (_stcImpl === null) {
+        throw new Error("ProviderStc accessed before stc module initialized.");
+      }
+      const value = _stcImpl(Provider);
+      Object.defineProperty(this, "ProviderStc", {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      });
+      return value;
+    },
+  });
   (Provider as any).contextName = name;
   contextsByKey.set(id, ctx);
   return ctx;

package/src/debug/cli.browser.ts

@@ -0,0 +1,17 @@
+/**
+ * Browser stub for CLI debug utilities.
+ *
+ * Replaces `cli.ts` in browser builds so that `cli-table3` and
+ * `picocolors` (Node-only packages) are never imported.
+ * All functions are no-ops since CLI debugging is not relevant in browsers.
+ */
+
+export function debugStack(): void {}
+
+export function debugContext(): void {}
+
+export function debugTree(): void {}
+
+export function debugWatch(): void {}
+
+export function debugRender(): void {}

package/src/debug/diagnostics.test.tsx

@@ -10,7 +10,7 @@ import {
   resetDevtoolsServerForTests,
 } from "../devtools/devtools-server.js";
 import { DiagnosticsCollector } from "../diagnostics.js";
-import { renderAsync } from "../render.js";
+import { renderAsync } from "../render-output.js";
 
 let socket: WebSocket | undefined;
 

package/src/debug/effects.test.tsx

@@ -11,7 +11,7 @@ import {
   resetDevtoolsServerForTests,
 } from "../devtools/devtools-server.js";
 import { effect, memo, ref } from "../reactivity.js";
-import { renderAsync } from "../render.js";
+import { renderAsync } from "../render-output.js";
 import { flushJobsAsync } from "../scheduler.js";
 import { debug } from "./index.js";
 

package/src/debug/file-streaming.ts

@@ -0,0 +1,115 @@
+/**
+ * Throttled file-content streaming for devtools.
+ *
+ * As the render tree mutates, the debug system finds the enclosing
+ * `alloy:source-file` wrapper for the changed node and marks it dirty.
+ * When a devtools client is connected, dirty files are re-printed at
+ * most once per second so users can watch file content build up during
+ * rendering. When devtools is not connected, dirty files are flushed
+ * once at the end of render via {@link flushAllDirtyFiles}.
+ */
+
+import { isDevtoolsConnected } from "../devtools/devtools-server.js";
+import type { PrintTreeOptions } from "../output-types.js";
+import { getContextForNode } from "../render/node-context.js";
+import { ElementNode, type AlloyNode } from "../render/node.js";
+import { printNodeToString } from "../render/printer.js";
+import { updated as filesUpdated } from "./files.js";
+import { isDebugEnabled } from "./trace.js";
+
+const DEVTOOLS_FLUSH_INTERVAL_MS = 1000;
+
+const dirtyFiles = new Set<ElementNode>();
+const lastFlushTimeByFile = new Map<string, number>();
+
+/** Find the nearest alloy:source-file ancestor (inclusive). */
+function findSourceFileWrapper(node: AlloyNode): ElementNode | undefined {
+  let cur: AlloyNode | null = node;
+  while (cur !== null) {
+    if (cur instanceof ElementNode && cur.localName === "alloy:source-file") {
+      return cur;
+    }
+    cur = cur.parentNode;
+  }
+  return undefined;
+}
+
+interface SourceFileMeta {
+  path: string;
+  filetype: string;
+}
+
+function getSourceFileMeta(wrapper: ElementNode): SourceFileMeta | undefined {
+  const ctx = getContextForNode(wrapper);
+  const meta = ctx?.meta as
+    | {
+        sourceFile?: SourceFileMeta;
+        sourceFileReady?: boolean;
+        printOptions?: PrintTreeOptions;
+      }
+    | undefined;
+  if (meta?.sourceFileReady === false) return undefined;
+  return meta?.sourceFile;
+}
+
+function getPrintOptions(wrapper: ElementNode): PrintTreeOptions | undefined {
+  const ctx = getContextForNode(wrapper);
+  const meta = ctx?.meta as { printOptions?: PrintTreeOptions } | undefined;
+  return meta?.printOptions;
+}
+
+function flushFile(wrapper: ElementNode): void {
+  const sf = getSourceFileMeta(wrapper);
+  if (!sf) return;
+  const printOpts = getPrintOptions(wrapper);
+  let contents: string;
+  try {
+    contents = printNodeToString(wrapper, {
+      printWidth: printOpts?.printWidth ?? 80,
+      tabWidth: printOpts?.tabWidth ?? 2,
+      useTabs: printOpts?.useTabs ?? false,
+    }).formatted;
+  } catch {
+    // Mid-render the tree may be in an inconsistent state — skip this
+    // flush attempt and pick it up on the next mutation.
+    return;
+  }
+  if (printOpts?.insertFinalNewLine !== false && !contents.endsWith("\n")) {
+    contents += "\n";
+  }
+  filesUpdated({ path: sf.path, filetype: sf.filetype, contents });
+  lastFlushTimeByFile.set(sf.path, Date.now());
+  dirtyFiles.delete(wrapper);
+}
+
+/**
+ * Mark the source file containing `node` as dirty. When devtools is
+ * connected and at least 1s has elapsed since this file was last flushed,
+ * print and broadcast its content immediately.
+ */
+export function markFileDirtyForNode(node: AlloyNode): void {
+  if (!isDebugEnabled()) return;
+  const wrapper = findSourceFileWrapper(node);
+  if (!wrapper) return;
+  dirtyFiles.add(wrapper);
+  if (!isDevtoolsConnected()) return;
+  const sf = getSourceFileMeta(wrapper);
+  if (!sf) return;
+  const last = lastFlushTimeByFile.get(sf.path) ?? 0;
+  if (Date.now() - last < DEVTOOLS_FLUSH_INTERVAL_MS) return;
+  flushFile(wrapper);
+}
+
+/** Flush every dirty file. Called at end of render. */
+export function flushAllDirtyFiles(): void {
+  if (dirtyFiles.size === 0) return;
+  for (const wrapper of [...dirtyFiles]) {
+    flushFile(wrapper);
+  }
+}
+
+/** Reset all streaming state. Called when a new render begins. */
+export function reset(): void {
+  dirtyFiles.clear();
+  lastFlushTimeByFile.clear();
+}

package/src/debug/files.test.tsx

@@ -11,7 +11,7 @@ import {
   enableDevtools,
   resetDevtoolsServerForTests,
 } from "../devtools/devtools-server.js";
-import { renderAsync } from "../render.js";
+import { renderAsync } from "../render-output.js";
 
 let socket: WebSocket | undefined;
 
@@ -61,16 +61,20 @@ it("emits file and directory add/update/remove messages", async () => {
     type: "directory:added",
     path: "src",
   });
-  expect(initialFiles[2]).toMatchObject({
-    type: "file:added",
-    path: "src/index.ts",
-    filetype: "ts",
-  });
-  expect(initialFiles[3]).toMatchObject({
-    type: "file:updated",
-    path: "src/index.ts",
-    content: expect.any(String),
-  });
+  expect(initialFiles).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        type: "file:added",
+        path: "src/index.ts",
+        filetype: "ts",
+      }),
+      expect.objectContaining({
+        type: "file:updated",
+        path: "src/index.ts",
+        content: expect.any(String),
+      }),
+    ]),
+  );
 
   collector.stop();
 });

package/src/debug/index.ts

@@ -27,16 +27,14 @@ import {
   updated,
 } from "./files.js";
 import {
-  appendCustomContext,
-  appendFragmentChild,
-  appendPrintHook,
-  appendTextNode,
   beginComponent,
   complete,
   error,
   flushJobsComplete,
   initialize,
-  prepareMemoNode,
+  isRerenderEnabled,
+  nodeAttached,
+  nodeDetached,
 } from "./render.js";
 import {
   registerScope,
@@ -55,7 +53,11 @@ export type {
   EffectEdgeDebugInfo,
   RefDebugInfo,
 } from "./effects.js";
-export { getRenderNodeId, type RenderTreeNodeInfo } from "./render.js";
+export {
+  getRenderNodeId,
+  type RenderNodeActions,
+  type RenderTreeNodeInfo,
+} from "./render.js";
 export type {
   BeginComponentOptions,
   ComponentDebugSession,
@@ -94,12 +96,10 @@ export const debug = {
   },
   render: {
     initialize,
-    appendTextNode,
-    appendCustomContext,
-    appendPrintHook,
-    appendFragmentChild,
+    nodeAttached,
+    nodeDetached,
     beginComponent,
-    prepareMemoNode,
+    isRerenderEnabled,
     error,
     complete,
     flushJobsComplete,

package/src/debug/message-format.test.tsx

@@ -22,7 +22,7 @@ import {
   resetDevtoolsServerForTests,
 } from "../devtools/devtools-server.js";
 import { effect, ref } from "../reactivity.js";
-import { renderAsync } from "../render.js";
+import { renderAsync } from "../render-output.js";
 import { flushJobsAsync } from "../scheduler.js";
 import { debug } from "./index.js";
 
@@ -56,7 +56,10 @@ afterEach(async () => {
 describe("subscriptions", () => {
   it("only receives messages for subscribed channels", async () => {
     // Subscribe to render only — should NOT see effects, refs, etc.
-    const collector = await createMessageCollector(socket!, ["render"]);
+    const collector = await createMessageCollector(socket!, [
+      "render",
+      "components",
+    ]);
     await renderAsync(<Output>hello</Output>);
     const messages = await collector.waitForRender();
     collector.stop();
@@ -107,7 +110,10 @@ describe("subscriptions", () => {
 
 describe("render:node_added", () => {
   it("root node has null parent_id and kind 'root'", async () => {
-    const collector = await createMessageCollector(socket!, ["render"]);
+    const collector = await createMessageCollector(socket!, [
+      "render",
+      "components",
+    ]);
     await renderAsync(<Output />);
     const messages = await collector.waitForRender();
     collector.stop();
@@ -124,20 +130,22 @@ describe("render:node_added", () => {
     });
   });
 
-  it("component node has numeric id, parent_id, and name", async () => {
-    const collector = await createMessageCollector(socket!, ["render"]);
+  it("component instance has numeric id, parent_id, and name", async () => {
+    const collector = await createMessageCollector(socket!, [
+      "render",
+      "components",
+    ]);
     await renderAsync(<Output />);
     const messages = await collector.waitForRender();
     collector.stop();
 
     const output = messages.find(
-      (m) => m.type === "render:node_added" && m.name === "Output",
+      (m) => m.type === "component:added" && m.name === "Output",
     );
     expect(output).toMatchObject({
-      type: "render:node_added",
+      type: "component:added",
       id: expect.any(Number),
-      parent_id: expect.any(Number),
-      kind: "component",
+      parent_id: null,
       name: "Output",
     });
   });
@@ -156,23 +164,26 @@ describe("render:node_added", () => {
     expect(text!.parent_id).toEqual(expect.any(Number));
   });
 
-  it("non-text node has null value (not undefined)", async () => {
+  it("non-text render node has null value (not undefined)", async () => {
     const collector = await createMessageCollector(socket!, ["render"]);
     await renderAsync(<Output>hello</Output>);
     const messages = await collector.waitForRender();
     collector.stop();
 
-    const component = messages.find(
-      (m) => m.type === "render:node_added" && m.kind === "component",
+    const nonText = messages.find(
+      (m) => m.type === "render:node_added" && m.kind === "directory",
     );
-    expect(component!.value).toBeNull();
+    expect(nonText!.value).toBeNull();
   });
 });
 
 describe("render:node_removed", () => {
   it("is emitted when a reactive component removes children", async () => {
     const show = ref(true);
-    const collector = await createMessageCollector(socket!, ["render"]);
+    const collector = await createMessageCollector(socket!, [
+      "render",
+      "components",
+    ]);
 
     function Conditional() {
       return () => (show.value ? "visible" : "");
@@ -691,7 +702,10 @@ describe("debugger:info", () => {
 
 describe("null vs undefined contract", () => {
   it("nullable fields arrive as null (not undefined or missing)", async () => {
-    const collector = await createMessageCollector(socket!, ["render"]);
+    const collector = await createMessageCollector(socket!, [
+      "render",
+      "components",
+    ]);
     await renderAsync(<Output>hello</Output>);
     const messages = await collector.waitForRender();
     collector.stop();
@@ -705,14 +719,13 @@ describe("null vs undefined contract", () => {
     expect(root!.parent_id).toBeNull();
     expect("parent_id" in root!).toBe(true);
 
-    // Component node: value should be null, not undefined
+    // Component facts are not render nodes.
     const component = messages.find(
       (m: DevtoolsMessage) =>
-        m.type === "render:node_added" && m.kind === "component",
+        m.type === "component:added" && m.name === "Output",
     );
     expect(component).toBeDefined();
-    expect(component!.value).toBeNull();
-    expect("value" in component!).toBe(true);
+    expect(component!.parent_id).toBeNull();
 
     // source_file is nullable
     expect("source_file" in root!).toBe(true);

package/src/debug/render-tree-orphans.test.tsx

@@ -13,7 +13,7 @@ import {
   resetDevtoolsServerForTests,
 } from "../devtools/devtools-server.js";
 import { ref } from "../reactivity.js";
-import { renderAsync } from "../render.js";
+import { renderAsync } from "../render-output.js";
 import { flushJobsAsync } from "../scheduler.js";
 
 /**
@@ -242,28 +242,19 @@ describe("render tree node orphans", () => {
 
     expect(orphans).toEqual([]);
 
-    // No duplicate text nodes under the same parent
-    const textByParent = new Map<number, string[]>();
-    for (const [_id, node] of active) {
-      if (node.kind === "text" && node.value && node.parentId !== null) {
-        const list = textByParent.get(node.parentId) ?? [];
-        list.push(node.value);
-        textByParent.set(node.parentId, list);
-      }
-    }
-    for (const [parentId, values] of textByParent) {
-      const dupes = values.filter((v, i) => values.indexOf(v) !== i);
-      expect(dupes, `Duplicate text nodes under parent ${parentId}`).toEqual(
-        [],
-      );
-    }
+    const textValues = [...active.values()]
+      .filter((node) => node.kind === "text")
+      .map((node) => node.value);
+    expect(textValues).toEqual(expect.arrayContaining(["a", "y", "z"]));
+    expect(textValues).not.toEqual(expect.arrayContaining(["b", "c", "x"]));
 
     collector.stop();
   });
 
   it("no orphans when For with separators re-renders and keeps some items", async () => {
     // mapJoin creates separator/joiner slots between items. These separators
-    // contain printHook subtrees that are part of the cached element tree.
+    // contain nested formatter-control subtrees that are part of the cached
+    // element tree.
     // When items change, the cached subtree is re-added but separator fragments
     // from previous renders must be properly cascade-deleted.
     //
@@ -285,8 +276,8 @@ describe("render tree node orphans", () => {
     const items = ref(["a", "b", "c", "d"]);
     const collector = await createMessageCollector(socket!);
 
-    // Nested blocks simulate the deeply nested printHook trees
-    // found in real emitters (e.g., flight-instructor)
+    // Nested blocks simulate the deeply nested formatter-control trees found in
+    // real emitters (e.g., flight-instructor).
     function Item(props: { value: string }) {
       return (
         <Block>