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

package/src/render-error.ts

@@ -0,0 +1,98 @@
+import {
+  debug,
+  getRenderNodeId,
+  type RenderTreeNodeInfo,
+} from "./debug/index.js";
+import {
+  emitDiagnostic,
+  type DiagnosticInput,
+  type DiagnosticsCollector,
+} from "./diagnostics.js";
+import { getRenderStackSnapshot, printRenderStack } from "./render-stack.js";
+
+const notifiedErrors = new WeakSet<object>();
+
+let lastRenderError: {
+  error: { name: string; message: string; stack?: string };
+  componentStack: Array<{
+    name: string;
+    props?: Record<string, unknown> | undefined;
+    propsSerialized?: string;
+    renderNodeId?: number;
+    source?: RenderTreeNodeInfo["source"];
+  }>;
+} | null = null;
+
+function normalizeRenderError(error: unknown): {
+  name: string;
+  message: string;
+  stack?: string;
+} {
+  if (error instanceof Error) {
+    return {
+      name: error.name || error.constructor?.name || "Error",
+      message: error.message || "",
+      stack: error.stack,
+    };
+  }
+  if (error && typeof error === "object") {
+    const anyError = error as {
+      name?: string;
+      message?: string;
+      stack?: string;
+    };
+    return {
+      name: anyError.name || "Error",
+      message: anyError.message || String(error),
+      stack: anyError.stack,
+    };
+  }
+  return {
+    name: "Error",
+    message: String(error),
+  };
+}
+
+export function notifyRenderError(
+  error: unknown,
+  collector?: DiagnosticsCollector,
+) {
+  if (error && typeof error === "object") {
+    if (notifiedErrors.has(error)) return;
+    notifiedErrors.add(error);
+  }
+  if (lastRenderError) return;
+
+  const { name, message, stack } = normalizeRenderError(error);
+  const componentStack = getRenderStackSnapshot().map((entry) => {
+    const renderNode = entry.context?.meta?.renderNode;
+    const renderNodeId = renderNode ? getRenderNodeId(renderNode) : undefined;
+    return {
+      name: entry.displayName,
+      props: entry.props as Record<string, unknown> | undefined,
+      renderNodeId,
+      source: entry.source,
+    };
+  });
+
+  // Output to console
+  printRenderStack(error);
+
+  // Send to devtools if enabled
+  debug.render.error({ name, message, stack }, componentStack);
+
+  // Store for diagnostics
+  lastRenderError = { error: { name, message, stack }, componentStack };
+  const lastEntry = componentStack.at(-1);
+  const diagnostic: DiagnosticInput = {
+    severity: "error",
+    message: `${name}: ${message}`,
+    source: lastEntry?.source,
+  };
+  if (collector) collector.emit(diagnostic);
+  else emitDiagnostic(diagnostic);
+}
+
+export function resetRenderErrorState() {
+  lastRenderError = null;
+}

package/src/render-output.ts

@@ -0,0 +1,243 @@
+/**
+ * Top-level render entry points.
+ *
+ * `render` and `renderAsync` take a `Children` tree, insert it into a
+ * fresh root `ElementNode`, flush the scheduler, and walk the result
+ * to assemble an {@link OutputDirectory}. The walker recognizes
+ * marker `localName`s (`alloy:directory`, `alloy:source-file`,
+ * `alloy:copy-file`) stamped on the AlloyNode by `<SourceDirectory>`,
+ * `<SourceFile>`, and `<CopyFile>` (see `components/`), reading
+ * each marker's owning Context for path/filetype metadata.
+ */
+
+import { debug, isDevtoolsEnabled } from "./debug/index.js";
+import { closeTrace } from "./debug/trace-writer.js";
+import { isTraceEnabled } from "./debug/trace.js";
+import {
+  attachDiagnosticsCollector,
+  DiagnosticsCollector,
+  emitDiagnosticForTree,
+  registerDiagnosticsForTree,
+  reportDiagnosticsForTree,
+} from "./diagnostics.js";
+import type {
+  ContentOutputFile,
+  CopyOutputFile,
+  OutputDirectory,
+  PrintTreeOptions,
+} from "./output-types.js";
+import { root as createRoot, type Context } from "./reactivity.js";
+import { notifyRenderError, resetRenderErrorState } from "./render-error.js";
+import { getContextForNode } from "./render/node-context.js";
+import { AlloyNode, createElement, ElementNode } from "./render/node.js";
+import { printNodeToString } from "./render/printer.js";
+import type { Children } from "./runtime/component.js";
+import { insert } from "./runtime/insert.js";
+import { flushJobs, flushJobsAsync, waitForSignal } from "./scheduler.js";
+
+/** Render a component tree to an {@link OutputDirectory}. */
+export function render(
+  children: Children,
+  options?: PrintTreeOptions,
+): OutputDirectory {
+  debug.assertReadyForSyncRender();
+  resetRenderErrorState();
+  const root = createElement("alloy:root");
+  const collector = new DiagnosticsCollector();
+  registerDiagnosticsForTree(root, collector);
+  debug.render.initialize(root);
+  let output: OutputDirectory | undefined;
+  try {
+    createRoot(() => {
+      attachDiagnosticsCollector(collector);
+      insert(root, children);
+    });
+    flushJobs();
+    output = sourceFilesForTree(root, options);
+  } catch (error) {
+    notifyRenderError(error, collector);
+    throw error;
+  } finally {
+    try {
+      reportDiagnosticsForTree(root);
+    } finally {
+      try {
+        debug.render.complete();
+      } finally {
+        // Close trace DB only if devtools is NOT running. With devtools active the
+        // DB must remain open for post-render reactive updates streamed to clients.
+        if (isTraceEnabled() && !isDevtoolsEnabled()) closeTrace();
+      }
+    }
+  }
+  if (isDevtoolsEnabled()) {
+    void waitForSignal();
+  }
+  return output!;
+}
+
+/**
+ * Async variant — awaits any scheduled async jobs (e.g. produced by
+ * `<Output>` consumers that read external data) before walking the
+ * tree.
+ */
+export async function renderAsync(
+  children: Children,
+  options?: PrintTreeOptions,
+): Promise<OutputDirectory> {
+  await debug.prepare();
+  resetRenderErrorState();
+  const root = createElement("alloy:root");
+  const collector = new DiagnosticsCollector();
+  registerDiagnosticsForTree(root, collector);
+  debug.render.initialize(root);
+  let output: OutputDirectory | undefined;
+  try {
+    createRoot(() => {
+      attachDiagnosticsCollector(collector);
+      insert(root, children);
+    });
+    await flushJobsAsync();
+    output = sourceFilesForTree(root, options);
+  } catch (error) {
+    notifyRenderError(error, collector);
+    throw error;
+  } finally {
+    try {
+      reportDiagnosticsForTree(root);
+    } finally {
+      try {
+        debug.render.complete();
+      } finally {
+        if (isTraceEnabled() && !isDevtoolsEnabled()) closeTrace();
+      }
+    }
+  }
+  return output!;
+}
+
+/**
+ * Walk the AlloyNode tree, collecting `<SourceDirectory>`,
+ * `<SourceFile>`, and `<CopyFile>` markers into an
+ * {@link OutputDirectory}.
+ */
+export function sourceFilesForTree(
+  rootNode: AlloyNode,
+  opts?: PrintTreeOptions,
+): OutputDirectory {
+  let result: OutputDirectory | undefined;
+  walk(rootNode, undefined);
+  if (!result) {
+    emitDiagnosticForTree(rootNode, {
+      severity: "error",
+      message:
+        "No root directory found. Make sure you are using the Output component.",
+    });
+    return { kind: "directory", path: "", contents: [] };
+  }
+  return result;
+
+  function walk(node: AlloyNode, cwd: OutputDirectory | undefined): void {
+    if (node instanceof ElementNode) {
+      const ctx = getContextForNode(node);
+      if (node.localName === "alloy:directory") {
+        const dirMeta = ctx?.meta?.directory as { path: string } | undefined;
+        const dir: OutputDirectory = {
+          kind: "directory",
+          path: dirMeta?.path ?? "",
+          contents: [],
+        };
+        if (cwd) cwd.contents.push(dir);
+        else result = dir;
+        for (let c = node.firstChild; c !== null; c = c.nextSibling) {
+          walk(c, dir);
+        }
+        return;
+      }
+      if (node.localName === "alloy:source-file") {
+        const sf = ctx?.meta?.sourceFile as
+          | { path: string; filetype: string }
+          | undefined;
+        if (sf) {
+          if (!cwd) {
+            throw new Error(
+              "Source file doesn't have parent directory. Make sure you have used the Output component.",
+            );
+          }
+          const printOpts = ctx!.meta!.printOptions as
+            | PrintTreeOptions
+            | undefined;
+          const file: ContentOutputFile = {
+            kind: "file",
+            path: sf.path,
+            filetype: sf.filetype,
+            contents: printNode(node, {
+              printWidth: opts?.printWidth ?? printOpts?.printWidth,
+              tabWidth: opts?.tabWidth ?? printOpts?.tabWidth,
+              useTabs: opts?.useTabs ?? printOpts?.useTabs,
+              insertFinalNewLine:
+                opts?.insertFinalNewLine ??
+                printOpts?.insertFinalNewLine ??
+                true,
+            }),
+          };
+          cwd.contents.push(file);
+          debug.files.updated({
+            path: sf.path,
+            filetype: sf.filetype,
+            contents: file.contents,
+          });
+        }
+        return;
+      }
+      if (node.localName === "alloy:copy-file") {
+        const cf = ctx?.meta?.copyFile as
+          | { path: string; sourcePath: string }
+          | undefined;
+        if (cf) {
+          if (!cwd) {
+            throw new Error(
+              "Copy file doesn't have parent directory. Make sure you have used the Output component.",
+            );
+          }
+          const file: CopyOutputFile = {
+            kind: "file",
+            path: cf.path,
+            sourcePath: cf.sourcePath,
+          };
+          cwd.contents.push(file);
+        }
+        return;
+      }
+    }
+    for (let c = node.firstChild; c !== null; c = c.nextSibling) {
+      walk(c, cwd);
+    }
+  }
+}
+
+export { getContextForNode } from "./render/node-context.js";
+
+/**
+ * @deprecated Use {@link getContextForNode}. Render tree nodes are now
+ * represented by AlloyNode objects directly.
+ */
+export function getContextForRenderNode(node: AlloyNode): Context | undefined {
+  return getContextForNode(node);
+}
+
+/**
+ * Print an AlloyNode subtree with the given options. Used internally
+ * by `sourceFilesForTree` to format each `<SourceFile>` body and
+ * exposed for testing helpers.
+ */
+export function printNode(node: AlloyNode, opts?: PrintTreeOptions): string {
+  const merged = {
+    printWidth: opts?.printWidth ?? 80,
+    tabWidth: opts?.tabWidth ?? 2,
+    useTabs: opts?.useTabs ?? false,
+  };
+  let formatted = printNodeToString(node, merged).formatted;
+  if (opts?.insertFinalNewLine && !formatted.endsWith("\n")) formatted += "\n";
+  return formatted;
+}

package/src/runtime/component.ts

@@ -1,7 +1,7 @@
 import { Ref } from "@vue/reactivity";
 import { CustomContext } from "../reactivity.js";
 import { Refkey, RefkeyableObject } from "../refkey.js";
-import { IntrinsicElement } from "./intrinsic.js";
+import type { AlloyNode } from "../render/node.js";
 
 export const RENDERABLE = Symbol.for("Alloy.CustomElement");
 
@@ -46,7 +46,7 @@ export type Child =
   | Ref
   | Refkey
   | CustomContext
-  | IntrinsicElement;
+  | AlloyNode;
 
 export type Children = Child | Children[];
 export type Props = Record<string, any>;

package/src/runtime/create-intrinsic.ts

@@ -0,0 +1,56 @@
+/**
+ * `createIntrinsic("name", props)` — runtime version.
+ *
+ * The babel-emitted compiled output of a JSX intrinsic such as
+ * `<group shouldBreak>{...}</group>` calls this with the tag name and
+ * props. It allocates an `ElementNode` whose `localName` is the
+ * intrinsic kind and stores the non-`children` props on `data`, then
+ * eagerly inserts the children via the polymorphic {@link insert}
+ * helper. The set of recognized localNames matches the cases handled
+ * by the direct printer (`group`, `indent`, `line`, `softline`, `hardline`,
+ * `ifBreak`, ...); unknown names pass through as transparent
+ * containers.
+ *
+ * Examples:
+ *
+ *   <group shouldBreak={true}>...</group>
+ *     ─→ createIntrinsic("group", { shouldBreak: true, children: [...] })
+ *     ─→ ElementNode { localName: "group", data: { shouldBreak: true } }
+ */
+
+import { createElement, type ElementNode } from "../render/node.js";
+import type { Children, Props } from "./component.js";
+import { insert } from "./insert.js";
+
+/**
+ * Create an intrinsic ElementNode and insert its children eagerly.
+ */
+export function createIntrinsic(
+  name: string,
+  props?: Props & { children?: Children },
+): ElementNode {
+  let data: Record<string, unknown> | undefined;
+  let children: Children | undefined;
+  let flatContents: Children | undefined;
+  if (props !== undefined) {
+    for (const key in props) {
+      if (key === "children") {
+        children = props.children;
+      } else if (key === "flatContents" && name === "ifBreak") {
+        flatContents = props[key] as Children;
+      } else {
+        if (data === undefined) data = {};
+        data[key] = props[key];
+      }
+    }
+  }
+  if (flatContents !== undefined) {
+    const flatNode = createElement("alloy:if-break-flat");
+    insert(flatNode, flatContents);
+    if (data === undefined) data = {};
+    data.flatNode = flatNode;
+  }
+  const node = createElement(name, data);
+  if (children !== undefined) insert(node, children);
+  return node;
+}

package/src/runtime/fragment.ts

@@ -0,0 +1,22 @@
+/**
+ * `Fragment` component.
+ *
+ * Compiles `<>...</>` into `createComponent(Fragment, { children: [...] })`.
+ * When invoked, returns a `FragmentNode` whose children are eagerly
+ * inserted via the polymorphic {@link insert}. `FragmentNode` has
+ * DocumentFragment splice-on-insert semantics — inserting a fragment
+ * into a parent moves its children into the parent and leaves the
+ * fragment empty.
+ */
+
+import { createFragment, type FragmentNode } from "../render/node.js";
+import type { Children } from "./component.js";
+import { insert } from "./insert.js";
+
+export function Fragment(props: { children?: Children }): FragmentNode {
+  const node = createFragment();
+  if (props.children !== undefined) {
+    insert(node, props.children);
+  }
+  return node;
+}

package/src/runtime/index.ts

@@ -0,0 +1,12 @@
+/**
+ * runtime — narrow surface used by JSX-compiled output and tests
+ * exercising the AlloyNode renderer directly.
+ */
+
+export { mergeProps } from "../props-combinators.js";
+export { effect, memo } from "../reactivity.js";
+export { render, renderAsync } from "../render-output.js";
+export { createComponent } from "./component.js";
+export { createIntrinsic } from "./create-intrinsic.js";
+export { Fragment } from "./fragment.js";
+export { insert } from "./insert.js";