@alloy-js/core 0.23.0-dev.12 → 0.23.0-dev.15

package/docs/debugging.md

@@ -0,0 +1,105 @@
+# Debugging
+
+## Diagnostics
+
+Alloy has a built-in diagnostic system for validation warnings and errors during rendering.
+
+- [`emitDiagnostic(input)`](api/functions/emitDiagnostic.md) — emit a diagnostic from the current component. Automatically captures the component stack.
+- [`attachDiagnosticsCollector()`](api/functions/attachDiagnosticsCollector.md) — attach a collector before rendering to capture all diagnostics.
+- [`getDiagnosticsForTree(tree)`](api/functions/getDiagnosticsForTree.md) — extract diagnostics from a rendered tree.
+- [`reportDiagnostics(diagnostics)`](api/functions/reportDiagnostics.md) — format and print diagnostics to the console.
+
+## Trace Files
+
+Set `ALLOY_DEBUG_TRACE=1` (or a custom path) to write a SQLite trace database during rendering:
+
+```sh
+ALLOY_DEBUG_TRACE=1 node my-generator.js        # writes alloy-trace.db
+ALLOY_DEBUG_TRACE=./my-trace.db node my-gen.js   # custom path
+```
+
+The trace captures the full render tree, reactive graph (refs, effects, edges), symbol/scope data, scheduler activity, and render errors.
+
+### The `alloy-trace` CLI
+
+The `@alloy-js/trace-cli` package provides `alloy-trace` for querying trace databases.
+
+**Overview:**
+
+```sh
+alloy-trace stats                    # summary with overhead analysis
+alloy-trace errors                   # render errors with component stacks
+```
+
+**Reactive graph:**
+
+```sh
+alloy-trace effect list              # all effects
+alloy-trace effect hotspots          # most-active effects
+alloy-trace effect chain <id>        # dependency/trigger chain
+alloy-trace ref list [--unused]      # all refs (--unused for dead code)
+alloy-trace ref hotspots             # refs tracked by most effects
+alloy-trace ref fanout <id>          # effects tracking a ref
+```
+
+**Render tree:**
+
+```sh
+alloy-trace component tree           # render tree hierarchy
+alloy-trace component list           # all components
+alloy-trace component stats          # component counts
+```
+
+**Symbols and output:**
+
+```sh
+alloy-trace symbol list              # all symbols
+alloy-trace scope list               # all scopes
+alloy-trace file list                # generated files
+```
+
+**Custom queries:**
+
+```sh
+alloy-trace query "SELECT * FROM effects WHERE type = 'render'"
+```
+
+### Diagnostic Workflow
+
+1. Start with `stats` for a high-level overview; check for framework vs. user effect overhead.
+2. Check `errors` for render errors.
+3. Use `effect hotspots` / `ref hotspots` to find performance bottlenecks (over-tracked refs, frequently-running effects).
+4. Use `effect chain <id>` to trace why a specific effect is running.
+5. Use `ref list --unused` to find dead reactive values.
+6. Use `query "..."` for ad-hoc SQL for deeper investigation.
+
+## Devtools
+
+For live debugging, Alloy provides a WebSocket-based devtools server that streams reactive state in real time.
+
+### Enabling
+
+```sh
+ALLOY_DEBUG=1 node my-generator.js               # auto-start on render
+ALLOY_DEBUG_PORT=9000 ALLOY_DEBUG=1 node my-gen.js  # custom port
+```
+
+Or programmatically:
+
+```ts
+import {
+  enableDevtools,
+  waitForDevtoolsConnection,
+} from "@alloy-js/core/devtools";
+
+await enableDevtools({ port: 8123 }); // start server
+await waitForDevtoolsConnection(); // block until client connects
+```
+
+### Usage
+
+Open `http://localhost:8123/` (default port) in a browser. The devtools UI connects via WebSocket and subscribes to data channels. Only one client can connect at a time.
+
+**Available channels:** render tree, effects, refs, edges, symbols, scopes, output files, directories, errors, diagnostics, effect lifecycle, scheduler jobs.
+
+The devtools display the same data as trace files but streamed live, including reactive updates after the initial render.

package/docs/formatting.md

@@ -0,0 +1,99 @@
+# Formatting
+
+Alloy uses [Prettier's document IR](https://github.com/prettier/prettier/blob/main/commands.md) as its layout engine.
+
+Format options ([`printWidth`, `tabWidth`, `useTabs`](api/types/CommonFormatOptions.md)) are set on [`<Output>`](api/components/Output.md) and overridable per [`<SourceFile>`](api/components/SourceFile.md).
+
+## Intrinsic Formatting Elements
+
+### Line Breaks
+
+| Element   | Alias             | Behavior                                                                                         |
+| --------- | ----------------- | ------------------------------------------------------------------------------------------------ |
+| `<hbr />` | `<hardline />`    | Always breaks. Forces all parent groups to break.                                                |
+| `<sbr />` | `<softline />`    | Breaks if group is broken, otherwise nothing.                                                    |
+| `<br />`  | `<line />`        | Breaks if group is broken, otherwise a space.                                                    |
+| `<lbr />` | `<literalline />` | Always breaks, resets indentation, preserves trailing whitespace. Forces parent groups to break. |
+
+### Groups
+
+`<group>` tries to fit children on one line. If it exceeds `printWidth`, all line breaks in the group break. Groups nest — outermost breaks first.
+
+```tsx
+<group>
+  {"foo,"}
+  <br />
+  {"bar,"}
+  <br />
+  {"baz"}
+</group>
+// Fits: "foo, bar, baz"
+// Doesn't fit: each on its own line
+```
+
+A group breaks if it contains `<hbr />`, `<lbr />`, `<breakParent />`, or has `shouldBreak`.
+
+- **`id`** — names the group for `<ifBreak>` / `<indentIfBreak>`.
+- **`<breakParent />`** — forces all parent groups to break.
+
+### Indentation
+
+- **`<indent>`** — increases indent level. Takes effect at the next line break within.
+- **`<dedent>`** — decreases indent level (each `<align>` counts as one level).
+- **`<dedentToRoot />`** — resets to the level marked by `<markAsRoot>`.
+- **`<markAsRoot>`** — marks current indentation as root for `<dedentToRoot>` and `<lbr />`.
+- **`<align width={n}>`** — increases indentation by a fixed number of spaces. Trailing alignments remain spaces when `useTabs` is enabled.
+
+### Conditional Formatting
+
+- **`<ifBreak>`** — if `groupId` is omitted, responds to the nearest enclosing group; if specified, targets a named group. `flatContents` for the non-broken case.
+- **`<indentIfBreak groupId="id">`** — indents if the group is broken. `negate` reverses. `groupId` required.
+
+### Fill
+
+`<fill>` wraps like text — breaks before items that exceed `printWidth`, not all-or-nothing. Children must alternate content and line breaks.
+
+### Line Suffixes
+
+- **`<lineSuffix>`** — buffers content, flushes at end of line. For trailing comments.
+- **`<lineSuffixBoundary />`** — flushes the `<lineSuffix>` buffer explicitly.
+
+## The [`code`](api/functions/code.md) Template Tag
+
+Preserves line structure and auto-detects indentation:
+
+```ts
+const result = code`
+  function foo() {
+    return ${expr};
+  }
+`;
+```
+
+- Line breaks → `<hbr />`. Indentation increases → `<indent>`. Expressions interpolated as [`Children`](api/types/Children.md). Leading/trailing blank lines trimmed.
+
+## The [`text`](api/functions/text.md) Template Tag
+
+Collapses whitespace like JSX — newlines become spaces, leading/trailing whitespace trimmed.
+
+## Layout Components
+
+- [**`<Indent>`**](api/components/Indent.md) — wraps `<indent>` with a line break before content (default: hardline) and optional `trailingBreak`. Configure with `line`, `softline`, `hardline`, or `nobreak`.
+- [**`<Block>`**](api/components/Block.md) — indented block with opener/closer (default `{}`). Omits block if empty. Supports inline mode.
+- [**`<List>`**](api/components/List.md) — children with joiners. Supports `comma`, `semicolon`, `hardline`, `softline`, `space`, custom `joiner`/`ender`.
+- [**`<StatementList>`**](api/components/StatementList.md) — statements with line breaks between them.
+- [**`<Prose>`**](api/components/Prose.md) — fill-mode line breaking for text.
+
+## Content Slots
+
+[`createContentSlot()`](api/functions/createContentSlot.md) creates a reactive slot tracking whether it has content. Enables components like [`<Block>`](api/components/Block.md) and [`<List>`](api/components/List.md) to handle semantically empty children — lists skip separators, blocks collapse.
+
+```tsx
+const MySlot = createContentSlot();
+<MySlot>{/* children */}</MySlot>
+
+MySlot.isEmpty;       // boolean getter
+MySlot.hasContent;    // boolean getter
+<MySlot.WhenEmpty>fallback</MySlot.WhenEmpty>
+<MySlot.WhenHasContent>has stuff</MySlot.WhenHasContent>
+```