sygnal 6.6.0 → 7.1.0

package/CHANGELOG.md

@@ -2,6 +2,264 @@
 
 All notable changes to Sygnal are listed here. Versions follow [semantic versioning](https://semver.org). Releases before 5.4.0 are described in the [GitHub releases](https://github.com/tpresley/sygnal/releases) and tags.
 
+## 7.1.0 — 2026-10-20
+
+Fixes and additions from building an app (Temper's Tune UI) on 7.0 ([PLAN-13](dev-plans/PLAN-13.md)):
+an invalidation / navigation race, declaration statics that see the context, per-page Switchable
+state, SSE resume and dead-stream detection, reply helpers for hand-written drivers, and more
+precise `sygnal-check` findings. All additive.
+
+**Measured impact.** Size: the kanban gate is (a) 42,982 B with `nativeGlobalThis: false` (7.0.0:
+42,844 B; budget 43,000 B, 18 B headroom) and (b) 38,987 B by default. Statics with context cost
+19 B and the per-page Switchable map 126 B (it reuses the owner's binding watch for a page whose
+record is deleted); everything else is in drivers, the dev diagnostics entry, the test helper or
+`sygnal-check`, and adds nothing to an app that doesn't use it. The perf count gate is within its
+limits.
+
+**Companion packages.**
+- **`sygnal-check` 0.12.0:** SYG117 (`next()` to an action with no entry here), SYG302 (`import xs
+  from 'xstream'`, with `--fix`), SYG429 (a Switchable state map key that names no page); reply names
+  through request helpers and consts; SYG256 sees past helper calls in other fields; `next` followed
+  into helpers, imported ones included; context reads in the statics count for SYG170; `replyKeys`
+  in the config file. Its caret range doesn't reach 0.12.0 from `^0.11.0`, so update the dev
+  dependency.
+- **`create-sygnal-app` 2.10.0:** templates depend on `sygnal` ^7.1.0 and `sygnal-check` ^0.12.0, use
+  a system font stack (no Google Fonts) and scaffold a `.gitignore`.
+- **VS Code extension 0.9.0:** bundles `sygnal-check` 0.12.0.
+- **Claude Code plugin 0.2.1:** the `sygnal-dev` skill covers 7.1 (statics with context, per-page
+  Switchable state, SSE resume, reply helpers, `import { xs } from 'sygnal'`).
+
+### Added
+
+- **SYG117: `next()` to an action the component has no entry for (PLAN-13 N-1).** `next('X')`
+  reaches only its own component's model, so a child's `next('ENTER')` for an action only its
+  parent handles silently did nothing. The dev checks (`sygnal/diagnostics`, 0 production bytes)
+  warn on the first such `next()` per component and name, naming the ancestor that handles it and
+  the fix (send it up with `PARENT` or `EVENTS`), or the closest entry for a typo. `sygnal-check`
+  reports a literal `next('X')` with no entry `X` in the same component (with a rename fix for a typo).
+
+- **sygnal-check reads reply names through request helpers and consts (PLAN-13 C-1).** An object
+  argument with a reply key of a call a sink returns is a request (`req('/a', { ok: 'GOT_A' })`,
+  `api.get_run(args, { ok: 'RUN' })`, any callee), a returned const is followed (`HTTP: () => SNAP`),
+  and so are `connections` specs and SSE `events` maps held in consts. SYG102 no longer reports
+  their reply actions as unreachable, SYG112 checks the names, SYG152 and `--graph` see the requests.
+
+- **SYG256 sees past helper calls in other fields (PLAN-13 C-2).** A call in the STATE reducer
+  stopped the proof, so a leave-guard like `EDIT: { STATE: (s, d) => ({ ...s, dirty: true, edit:
+  { ...s.edit, [keyOf(s)]: d } }), ROUTER: (s) => s.dirty ? ABORT : … }` went unreported. A call
+  (or a function) inside a plain field's value now only makes that field unknown; calls in a test,
+  a spread or a computed key of the written object, and any assignment, still keep the check out.
+
+- **create-sygnal-app: no Google Fonts, and a `.gitignore` (PLAN-13 T-1).** The vite, vite-pwa and
+  astro templates loaded Inter from Google Fonts; every template now uses a system font stack and
+  loads nothing remote. No template wrote a `.gitignore` (npm leaves it out of the package): each
+  ships `gitignore`, scaffolded as `.gitignore` (`node_modules`, `dist`, `.vite`, `.astro`,
+  `*.local`, `dev-dist` for the PWA). The release smoke checks both.
+
+- **SYG302: `import xs from 'xstream'` (PLAN-13 X-1).** Under Node ESM and Vite 8 (a `"type":
+  "module"` package) xstream's CommonJS default import is the module object, so a custom driver's
+  `xs.create` is undefined. The docs, llms.txt and the skill use `import { xs } from 'sygnal'`
+  (the accessibility guide's sample was the last default import), the custom-drivers guide says
+  why, and `sygnal-check` reports the default import (info) with a `--fix`.
+
+- **`makeReplies()` and `senderOf()` for drivers you write (PLAN-13 D-1).** The reply-action
+  protocol `makeFetchDriver`, `driverFromAsync` and the socket driver use is exported and typed
+  (`ReplySender`, `ReplyChannel`): spread `replies` into the source, `reply(senderOf(req), type,
+  data)` as often as needed (progress, then a result), and abort a disposed sender's work in
+  `onStop`. The custom-drivers guide has an upload driver that replies more than once.
+
+- **SSE event ids, resuming and dead streams (PLAN-13 S-1).** On a `connections` spec: `meta:
+  true` gives SSE `message` / `events` actions `{ data, id, event }`; `resume: true | 'param'`
+  keeps the last event id and makes a reconnect the driver makes (after EventSource gave up, e.g. a
+  proxy 502, or a non-2xx on the `headers` path) resume from it, as `Last-Event-ID` over fetch or
+  `?lastEventId=` (or `?param=`) on the EventSource URL; `staleAfterMs` (SSE and WebSocket) closes
+  a connection that stays silent that long as a drop (`close` gets `stale: true`) so the reconnect
+  policy applies; over fetch, heartbeat comments count. `t.push(sink, data, { id })` gives a test
+  event its id. No bytes for apps without a socket driver.
+
+- **Declaration statics see the context (PLAN-13 F-1).** `resources`, `timers`, `connections`,
+  `head` and `browser` get `(state, context)` and are computed again when the component's context
+  changes (by identity, D603; an unrelated write re-runs nothing). A routed page reads `route` from
+  context (`App.context = { route: (s) => s.route }`, `TaskPage.resources = { task: (s, { route })
+  => … }`) instead of keeping a copy of the params in its own state. Server rendering passes the
+  context to `resources` and `head` too; the types take it as the second parameter; `sygnal-check`
+  counts context reads in the statics for SYG170. Core: +19 B (kanban gzip).
+
+- **Per-page Switchable state (PLAN-13 F-3).** `state` takes a map from page names to bindings
+  (`state={{ projects: 'pages.projects', settings: byId('teams', state.teamId) }}`): each listed
+  page binds its own key, path, lens or byId selection with a tag child's lifetime rules (another
+  target makes only that page again; a deleted target disposes it on its last state), and the
+  pages not listed share the owner's state. A key that names no page is the new **SYG429** (dev
+  checks and `sygnal-check`, with a rename fix). Types infer the page names from `of`. Core:
+  +126 B (kanban gzip), leaving 18 B of the 43,000 B budget with F-1.
+
+- **Deep-link tests start on their route (PLAN-13 F-2).** `renderComponent(App, { router, url })`
+  applies the root's `route` entry's STATE reducer to the initial state with the `url`'s route
+  before the first render: `initialState`'s `router.current()` ran at module load, so a test used
+  to render `/` first and send its requests. The entry's other sinks (a guard's redirect) still run
+  once, when the router answers. Tests only; no core change.
+
+- **sygnal-check follows `next` into helpers (PLAN-13 C-3).** A model that passes `next` to a
+  function (`advance(state, next)`), imported or in the same file and with any parameter name, has
+  that function's `next('X')` calls counted as its own, 3 calls deep: SYG102 sees the targets, and
+  SYG117 reports a bad one in the helper's file. A helper it can't read (a package) makes the
+  targets unknown, so SYG102 drops to info. The language server re-checks the component when the
+  helper changes.
+
+- **`replyKeys` in sygnal-check's config (PLAN-13 C-4).** A custom driver's own reply keys
+  (`cancelled: 'UP_CANCELLED'`) can be listed in `sygnal-check.config.json`, for every sink
+  (`["cancelled"]`) or per sink (`{ "UPLOAD": ["progress", "cancelled"] }`): their actions count for
+  SYG102 and are checked by SYG112. Without the setting, a request key the checker doesn't know
+  whose value names a model entry makes that entry's SYG102 info, pointing at `replyKeys`.
+
+### Fixed
+
+- **Follow-ups from trying the PLAN-13 build in Temper.** A Switchable page with a per-page
+  `state` map no longer reports SYG106 for the Switchable's own `state` prop (every page did, so
+  `expectNoDiagnostics()` failed). The `sygnal-check` command line reads `replyKeys` (check,
+  `--fix`, `--graph`, `--base`; the API and the language server already did). SSE `resume` replaces
+  an id parameter the URL already has instead of adding a second one. An `every` timer ticks once
+  per interval under a test clock that freezes `Date.now()` while timers run (Playwright's
+  `setFixedTime()`): its drift-free delays had grown by one interval per tick (1, 3, 6, 10 s).
+- **An invalidation no longer resends a resource's old request after a navigation (PLAN-13 R-1).**
+  When a write's `ok` action navigated (`ROUTER`) and its `invalidates` (a URL prefix or a tag)
+  matched a resource of a lens- or key-bound page, the page's new request was sent and then the
+  invalidation sent the old one in the same lane, cancelling the new one: the new page showed the
+  old record. A load now stops when the resource's request changed (or it was paused) while it
+  wrote its loading state; refresh, polling and focus refetches go through the same path.
+
+## 7.0.0 — 2026-10-19
+
+**Read [Migrating to 7.0](https://sygnal.js.org/guide/migrating-to-7/) before upgrading.** 7.0
+has one reducer timing contract and no option to switch back; apps that aren't ready stay on 6.x.
+
+**Measured impact.** Size: the kanban gate is (a) 42,844 B with `nativeGlobalThis: false` (6.6.0:
+42,495 B; budget raised from 42,700 B to 43,000 B for the binding lifetimes) and (b) 38,834 B by
+default. Most of the growth is the binding-lifetime bookkeeping; the single timing contract is
+smaller than the opt-in switch it replaced (−181 B against the 7.0 candidate). The timing audit is
+in the dev diagnostics entry (0 production bytes), and the upload, SSE, form and `tooltips()`
+features add nothing to an app that doesn't use them. The perf count gate is within its limits.
+
+**Companion packages.**
+- **`sygnal-check` 0.11.0:** checks reducer timing and binding changes against the Sygnal version
+  installed for each source package (7: every output gets the committed state, changed known
+  targets remount; 6: the 6.x contracts). New **SYG256** (an output guard that rejects the state
+  its own action writes, in a Sygnal 7 project); **SYG454** (an unkeyed dynamic `byId` selection)
+  only for an installed Sygnal 6. SYG731 accepts state announced through text, `aria-label`,
+  `aria-live` or `role="status"`; SYG609 also reports intent sources with no driver; `progress`
+  counts as a reply-action key (SYG102 / SYG112). Explanations for SYG257 and SYG636. Its caret
+  range doesn't reach 0.11.0 from `^0.10.0`, so update the dev dependency.
+- **`create-sygnal-app` 2.9.0:** every template depends on `sygnal` ^7.0.0 and `sygnal-check`
+  ^0.11.0 and has `npm run check` (TypeScript templates: sygnal-check and `tsc --noEmit`).
+  Scaffolding into a directory that holds only `.git` and/or `.DS_Store` keeps that metadata, and
+  `.` gets a valid package name from the directory.
+- **VS Code extension 0.8.0:** bundles `sygnal-check` 0.11.0 for Sygnal 7 and existing Sygnal 6
+  apps; workspace checkers need 0.11.0 or later (earlier ones fall back to the bundled checker).
+- **Claude Code plugin 0.2.0:** the `sygnal-dev` skill describes Sygnal 7; a project's
+  `sygnal-check` older than 0.11.0 is refused only when the project has Sygnal 7.
+
+### Breaking: STATE runs first, and output sinks see its result
+
+In every model entry STATE now runs first, whatever the key order, and every other sink (EFFECT,
+EVENTS, PARENT, ELEMENT, HTTP and other drivers) gets the committed state, calculated fields
+included, as `state` and `props.state`. The new `props.previousState` (fourth argument) is the
+state from before the action; a STATE reducer gets the old state in both. 6.x gave every reducer
+the state from before the action.
+
+- An output that computed the update itself now applies it twice: in
+  `INC: { STATE: s => ({ ...s, n: s.n + 1 }), PARENT: s => ({ n: s.n + 1 }) }`, PARENT becomes
+  `s => ({ n: s.n })`.
+- A value STATE clears or deletes (a submitted draft, a removed record) is read from
+  `previousState`.
+- A guard that admits the action (a loading or status flag STATE sets) tests `previousState`.
+  Keep the output guard: STATE returning `ABORT` doesn't cancel the other sinks.
+- When STATE returns `ABORT` or the same state, or throws, the other sinks still run, with
+  `state === previousState`.
+- When STATE removes the component's own state (`STATE: () => undefined` in a Collection item, or
+  a child bound with `state="x"` / `byId()` deleting its record), the other sinks get its last
+  state, so `REMOVE: { STATE: () => undefined, EVENTS: event('REMOVED', (s) => s.id) }` works as
+  before.
+- Behaviors: the first argument is the slice after STATE, `props.state` the host state after
+  STATE, `props.previousState` the host state before the action; the old slice is
+  `props.previousState[key]`. Every built-in behavior (form, chat, compose, commandBar, undo,
+  pager, selection, sortable, and the `sygnal/ui` dialog, popover, tooltip, tabs, accordion and
+  disclosure) is on this contract.
+- Libraries that support 6 and 7 read old values as `props.previousState ?? state`.
+
+### New: the timing audit (SYG257)
+
+An opt-in dev check for upgrading 6.x code: with `renderComponent(C, { timingAudit: true })`,
+`sygnal({ diagnostics: { timingAudit: true } })` in `vite.config`, `configureTimingAudit(true)`
+from `'sygnal/diagnostics'` or `globalThis.__SYGNAL_TIMING_AUDIT__ = true`, every output sink that
+reads a top-level state field its action's STATE changed reports **SYG257** (info, once per
+component, action, sink and field). Keep `state` where the new value is meant; read
+`previousState` where the old one was. It is off by default because in code written for 7.0
+reading the new value is the intent, and it adds nothing to production builds.
+
+sygnal-check's **SYG256** (warning) reports an output guard that contradicts the same action's
+literal STATE write, the loading/admission pitfall above. sygnal-check reads the installed
+Sygnal version per package; **SYG454** (a `byId()` selection without a key) applies only to
+Sygnal 6.
+
+### Breaking: a child follows the record its state binding points at
+
+When a child's `state` path, or its `byId()` field, id or idKey, changes, Sygnal disposes the old
+child and mounts a new one: `DISPOSE` runs with the last state, pending requests, delayed `next()`
+actions and subscriptions are cancelled, initialization reruns and local state starts from its
+defaults. The child's DOM is replaced, so focus, caret, scroll position and in-progress input
+inside it are lost. The same applies to Collection/VirtualCollection `from` and Switchable
+`state` (all items or pages, hidden ones included, even when ids overlap). Deleting the bound
+record disposes the child too, after the deleting action's outputs; re-adding the same id gets a
+new child, never the old pending work. A new `byId()` call with the same arguments, field edits
+and reordering keep the child. `key={selected.id}` is no longer needed for a selection.
+
+**A stable explicit key no longer keeps a child across a target change**: lift state that must
+survive the change into the parent. A child with a custom lens keeps its binding until its key
+changes.
+
+### New: uploads, SSE auth, form files and types, `tooltips()`
+
+- **Upload and download progress** on `makeFetchDriver` requests: `progress: 'UPLOADING'` (a reply
+  action) or `progress: true` (`HTTP.progress(category)`) sends `{ phase, loaded, total, fraction }`
+  steps, throttled to one every 50 ms per phase. Such a request goes over XMLHttpRequest, the only
+  way to see upload progress in every browser; fetch-only `init` options it can't honour are
+  SYG636. Tests: `t.progress('HTTP', { loaded, total }, 'UPLOADING')`.
+- **`multipart: { file, title }`** on a request: the multipart/form-data body as data, the way
+  `json` is; a model never builds a `FormData`.
+- **The `form` behavior** takes file inputs (a field's value is its `File`, `multiple` an array,
+  validated by the schema), keeps the submit's progress in `state.form.progress`
+  (`progress: 'form.PROGRESS'`) and counts start-overs in `state.form.resets` (key a file input
+  with it). `request: { url }` (or `(data, state) => request`) sends a valid submit itself, as
+  JSON or multipart, with `form.DONE` / `form.ERRORS` wired: the common save needs no model entry.
+  `form.RESET` from a click goes back to the start values (it used to take the event as values).
+- **Form types from the schema**: a typed Standard Schema (zod, valibot, arktype) types
+  `state.form.values` and `fields.x.value`; `FormOutput<typeof uses.form>` is the submit data.
+- **SSE connections take `headers`** (`{ authorization: 'Bearer ' + state.token }`): such a stream
+  is read with fetch (`Last-Event-ID`, `retry`), since EventSource can't send headers.
+- **`tooltips()`** in `sygnal/ui`: one behavior and one state slice for every tooltip of a
+  component (glossary terms, icon toolbars), one tip at a time.
+- `Component<State, any>` keeps `state` typed; SYG731 accepts state announced through text,
+  `aria-label`, `aria-live` or `role="status"`; sygnal-check's SYG609 also reports intent sources
+  with no driver; a test wait that times out on the fake clock names the pending timer; every
+  create-sygnal-app template has `npm run check` (TypeScript: sygnal-check and `tsc --noEmit`).
+
+### Also included
+
+- A child that fails to instantiate is no longer retried on every parent render.
+- State-wait timeout messages report queued simulated inputs; the testing guide separates
+  serialized simulated input from synchronous native bursts.
+- TypeScript tests can use `t.query<HTMLInputElement>(selector)` and `t.queryAll<…>(selector)`
+  (type assertions, not runtime checks); typed control tokens keep their inference.
+- The combined Rollup build exits normally (compiler watcher lifecycle fix).
+- The release workflow checks the CHANGELOG headings of the new versions before the gates and
+  any publish.
+
+### Changed
+
+- **The app graph's banner line says why it's missing.** When the dev server's graph route is on but the project has no `sygnal-check` 0.10.0 or later, `sygnal/vite` prints `➜  Sygnal graph: needs sygnal-check 0.10.0 or later in this project (npm i -D sygnal-check)` instead of nothing (the URL already answered 404 with the same hint).
+- **`astro dev` prints the graph page's address** under Astro's own banner (Astro never runs Vite's URL printing), and the Astro integration takes the `graph` option (`sygnal({ graph: false })`).
+- **The repository's examples link `sygnal-check`** (`file:../../sygnal-check`, as they link `sygnal`), so `npm run dev` in any of them serves the app graph; `examples/mcp-app` moves off `sygnal-check` ^0.7.0.
+
 ## 6.6.0 — 2026-10-16
 
 The app graph as an interactive page: `sygnal-check --graph=html`, live with `--watch` or at `/__sygnal/graph` in the Vite dev server, in a VS Code panel and in Sygnal DevTools. See [The App Graph](https://sygnal.js.org/guide/app-graph/).

package/README.md

@@ -9,6 +9,8 @@ A reactive component framework with pure functions, zero side effects, and autom
 
 ---
 
+> **Upgrading from 6.x?** Sygnal 7.0 changes reducer timing: output sinks (EFFECT, EVENTS, PARENT, HTTP, ...) now see the state after the action's STATE update. See [Migrating to 7.0](https://sygnal.js.org/guide/migrating-to-7/).
+
 ## Why Sygnal?
 
 - **Pure components** — Views are plain functions. All side effects are handled by drivers, outside your code.

package/dist/astro/index.cjs.js

@@ -867,17 +867,25 @@ function graphMiddleware(server, root, engine, ping = 25000) {
         res.end(req.method === 'HEAD' ? undefined : body);
     };
 }
-/** Adds the page's URL under Vite's own when the dev server prints them. */
-function printGraphUrl(server) {
+/** The banner line when the project has no sygnal-check with the graph page (it used to print nothing). */
+const GRAPH_MISSING_LINE = '  ➜  Sygnal graph: needs sygnal-check 0.10.0 or later in this project (npm i -D sygnal-check)';
+/**
+ * Adds the page's URL under Vite's own when the dev server prints them, or, when the project's
+ * sygnal-check is missing or too old for the page (`available` false), a line saying what to install.
+ */
+function printGraphUrl(server, available = true) {
     const print = server?.printUrls;
     if (typeof print !== 'function')
         return;
     server.printUrls = function (...args) {
         const out = print.apply(this, args);
         try {
+            const logger = server.config?.logger || console;
             const local = server.resolvedUrls?.local?.[0];
-            if (local)
-                (server.config?.logger || console).info(`  ➜  Sygnal graph: ${new URL(local).origin}${GRAPH_PATH}`);
+            if (!available)
+                logger.info(GRAPH_MISSING_LINE);
+            else if (local)
+                logger.info(`  ➜  Sygnal graph: ${new URL(local).origin}${GRAPH_PATH}`);
         }
         catch (_) { }
         return out;
@@ -1016,7 +1024,8 @@ function printGraphUrl(server) {
  *      skipped silently when missing; a sygnal-check without the page keeps the checker as in 5)
  *      builds it with createLiveProject on start and after each change: one build gives the page,
  *      the check overlay / console findings of 5, and the component stamps. Its URL is printed
- *      under Vite's ("➜  Sygnal graph: http://localhost:5173/__sygnal/graph"). The modules of the
+ *      under Vite's ("➜  Sygnal graph: http://localhost:5173/__sygnal/graph"; without a sygnal-check
+ *      0.10.0+ in the project, a line saying so instead). The modules of the
  *      scanned files get a tail setting a non-enumerable `__sygnalKey` (the static 'file#name'
  *      key, D521) on each top-level component function, which the runtime inspect() reports as
  *      `key`; with DevTools on, the dev entries also import 'virtual:sygnal/graph'
@@ -1084,7 +1093,7 @@ function sygnal(options = {}) {
     // Files whose `import ... from 'sygnal'` resolves to the run() wrapper
     const runtimeImporters = new Set();
     // Statements run before the app starts: dev flag (+ strict flag)
-    const flags = DEV_FLAG + (diagnostics.strict ? STRICT_FLAG : '');
+    const flags = DEV_FLAG + (diagnostics.strict ? STRICT_FLAG : '') + (diagnostics.timingAudit ? AUDIT_FLAG : '');
     const devImports = `import 'sygnal/diagnostics';import '${DEV_CLIENT}';`;
     // D77: the DevTools bridge, dev only. First, so the diagnostics entry finds it.
     // E-1: the MCP endpoint needs the bridge, so `mcp` turns it on
@@ -1282,8 +1291,7 @@ function sygnal(options = {}) {
             // W-2 (D543): the page and its stream, behind the MCP endpoint's guard; its URL in the banner
             if (graphOn && server?.middlewares) {
                 server.middlewares.use(graphMiddleware(server, root, engine));
-                if (graphAvailable(root))
-                    printGraphUrl(server);
+                printGraphUrl(server, graphAvailable(root));
             }
         },
         transform(code, id, opts) {
@@ -1568,7 +1576,7 @@ function normalizeDiagnostics(value) {
     if (!MODES.includes(mode)) {
         throw new Error(`[vite-plugin-sygnal] diagnostics mode must be one of ${MODES.map(m => `'${m}'`).join(', ')}; got ${JSON.stringify(mode)}`);
     }
-    return { mode, strict: !!o.strict, ignore: Array.isArray(o.ignore) ? o.ignore.map(String) : [] };
+    return { mode, strict: !!o.strict, timingAudit: !!o.timingAudit, ignore: Array.isArray(o.ignore) ? o.ignore.map(String) : [] };
 }
 /** Module id without a query or hash. */
 function cleanId(id) {
@@ -1946,6 +1954,8 @@ function startChecker(server, root, mod, setup, opts, engine) {
 }
 const DEV_FLAG = 'if (globalThis.__SYGNAL_DEV__ === undefined) globalThis.__SYGNAL_DEV__ = true;';
 const STRICT_FLAG = 'if (globalThis.__SYGNAL_STRICT__ === undefined) globalThis.__SYGNAL_STRICT__ = true;';
+// 7.0: the opt-in timing audit (SYG257, 'sygnal/diagnostics' checks/timingAudit.ts)
+const AUDIT_FLAG = 'if (globalThis.__SYGNAL_TIMING_AUDIT__ === undefined) globalThis.__SYGNAL_TIMING_AUDIT__ = true;';
 // A top-level (column 0) run(Component, ...) statement: bare, or declaring a
 // new binding. Assignments to existing variables, nested calls and indented
 // calls (e.g. inside a function or test callback) do not match (B-007). It is
@@ -2084,10 +2094,12 @@ const rootDir = (root) =>
 // @ts-ignore — Node's process
 !root ? process.cwd() : typeof root === 'string' ? root : node_url.fileURLToPath(root);
 function sygnalAstroIntegration(options = {}) {
+    let projectRoot;
     return {
         name: SYGNAL_RENDERER_NAME,
         hooks: {
             'astro:config:setup': ({ addRenderer, updateConfig, command, config }) => {
+                projectRoot = rootDir(config?.root);
                 addRenderer({
                     name: SYGNAL_RENDERER_NAME,
                     clientEntrypoint: 'sygnal/astro/client',
@@ -2117,6 +2129,7 @@ function sygnalAstroIntegration(options = {}) {
                             check: options.check,
                             nativeGlobalThis: options.nativeGlobalThis,
                             devtools: options.devtools,
+                            graph: options.graph,
                         })];
                 }
                 else if (options.nativeGlobalThis !== false) {
@@ -2129,6 +2142,16 @@ function sygnalAstroIntegration(options = {}) {
                 vite.plugins = [...(vite.plugins || []), onErrorPlugin(hook)];
                 updateConfig({ vite });
             },
+            // W-2: Astro prints its own banner (Vite's printUrls never runs), so the graph page's line goes here
+            'astro:server:start': ({ address, logger }) => {
+                if (options.graph === false || !projectRoot)
+                    return;
+                const print = (msg) => (logger ? logger.info(msg.replace(/^\s*➜\s*/, '')) : console.log(msg));
+                if (!graphAvailable(projectRoot))
+                    print(GRAPH_MISSING_LINE);
+                else if (address?.port)
+                    print(`  ➜  Sygnal graph: http://localhost:${address.port}${GRAPH_PATH}`);
+            },
         },
     };
 }