@tylix/angular 0.0.0-stage → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mbiyrukzz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# @tylix/angular
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Angular (20 and later) for Tylix apps: signals for the session, API data
+and live channels, functional route guards, an HttpClient interceptor,
+server-side rendering, and the Vite adapter the Tylix CLI loads. Create an
+app with it:
+
+```sh
+npm create tylix@latest my-app -- --frontend angular
+```
+
+## Signals
+
+Call these in an injection context (a field initializer):
+
+```ts
+import { injectAuth, injectApi, injectChannel, injectHydrated } from '@tylix/angular'
+
+export class Dashboard {
+  protected readonly auth = injectAuth()                  // auth.user(), auth.isAuthenticated()
+  protected readonly posts = injectApi<Post[]>('/api/posts') // posts.data(), posts.loading(), posts.reload()
+  protected readonly chat = injectChannel<Message>('chat', (message) => console.log(message))
+  protected readonly hydrated = injectHydrated()
+}
+```
+
+With SSR, `injectApi` GET requests are loaded on the server and reused in
+the browser.
+
+## Guards and HttpClient
+
+```ts
+import { authGuard, guestGuard, tylixInterceptor } from '@tylix/angular'
+
+{ path: 'dashboard', component: Dashboard, canActivate: [authGuard] }
+{ path: 'login', component: Login, canActivate: [guestGuard] }
+
+provideHttpClient(withFetch(), withInterceptors([tylixInterceptor]))
+```
+
+The interceptor sends the session cookies and, after a 401, renews the
+session once and retries.
+
+## The starter's layout
+
+```
+app/frontend/
+  app.routes.ts    every page and its URL (make:page adds routes here)
+  providers/       injectable stores with data and actions (PublicPostsStore,
+                   MyPostsStore), provided per page component
+  services/        the API URLs and calls; only stores use them
+  pages/           render only
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "@tylix/angular",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.0",
+  "description": "Angular frontend for Tylix: auth and API signals, route guards, an HttpClient interceptor, plus the Vite adapter the Tylix CLI loads.",
+  "license": "MIT",
+  "author": "Mbiyrukzz",
+  "type": "module",
+  "keywords": [
+    "tylix",
+    "angular",
+    "adapter",
+    "signals",
+    "ssr",
+    "vite"
+  ],
+  "homepage": "https://github.com/Mbiyrukzz/tylix/tree/main/packages/angular#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mbiyrukzz/tylix.git",
+    "directory": "packages/angular"
+  },
+  "bugs": {
+    "url": "https://github.com/Mbiyrukzz/tylix/issues"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "sideEffects": false,
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./adapter": {
+      "types": "./src/adapter.d.ts",
+      "default": "./src/adapter.js"
+    },
+    "./server": {
+      "types": "./src/server.d.ts",
+      "default": "./src/server.js"
+    }
+  },
+  "files": [
+    "src",
+    "!**/*.test.js",
+    "!**/*.test.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test src/*.test.js"
+  },
+  "dependencies": {
+    "@tylix/client": "^0.7.0"
+  },
+  "peerDependencies": {
+    "@angular/common": ">=20.0.0",
+    "@angular/core": ">=20.0.0",
+    "@angular/router": ">=20.0.0",
+    "rxjs": "^7.4.0",
+    "@angular/platform-server": ">=20.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@angular/platform-server": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@angular/common": "^22.2.0",
+    "@angular/compiler": "^22.2.0",
+    "@angular/core": "^22.2.0",
+    "@angular/platform-browser": "^22.2.0",
+    "@angular/platform-server": "^22.2.0",
+    "@angular/router": "^22.2.0",
+    "rxjs": "^7.8.0"
+  }
+}

package/src/access.js

@@ -0,0 +1,36 @@
+// Framework-free rules shared by the guards and the app's session watcher,
+// kept apart so they can be tested without Angular.
+
+// Where to go after logging in: the ?next= path, if it stays on this site,
+// else the dashboard. "//evil.com" or "https://evil.com" would leave it.
+export function nextPath(next) {
+  if (typeof next === 'string' && next.startsWith('/') && !next.startsWith('//') && !next.startsWith('/\\')) {
+    return next
+  }
+  return '/dashboard'
+}
+
+// What to do with a page of the given access level for a session status:
+//   null             show it
+//   { login: url }   send to /login?next=url
+//   { to: path }     send somewhere else (a logged-in user on a guest page)
+// access is 'auth' (logged-in only), 'guest' (logged-out only) or absent.
+export function decideAccess(access, status, url, next) {
+  if (access === 'auth' && status !== 'authenticated') return { login: url }
+  if (access === 'guest' && status === 'authenticated') return { to: nextPath(next) }
+  return null
+}
+
+const AUTH_PATHS = new Set(['/api/login', '/api/register', '/api/auth/refresh', '/api/auth/logout'])
+
+// Whether a 401 from `url` means "access token expired, try a refresh".
+// On the auth endpoints a 401 means wrong credentials or no session.
+export function canRefreshAfter401(url) {
+  let pathname
+  try {
+    pathname = new URL(url, 'http://tylix.local').pathname
+  } catch {
+    pathname = String(url).split('?')[0]
+  }
+  return !AUTH_PATHS.has(pathname)
+}

package/src/adapter.d.ts

@@ -0,0 +1,15 @@
+export interface FrontendAdapter {
+  name: string
+  label: string
+  root: string
+  dedupe: string[]
+  requires: string[]
+  vitePlugins(context: { importFromProject(specifier: string): Promise<any>; root: string }): Promise<unknown>
+  typecheck?: { bin: string; args(tsconfig: string): string[] }
+  ssr?: boolean
+  ssrFallback?: string
+  viteConfig?: Record<string, unknown>
+}
+
+declare const adapter: FrontendAdapter
+export default adapter

package/src/adapter.js

@@ -0,0 +1,63 @@
+import path from 'node:path'
+
+// What the Tylix CLI needs to host an Angular frontend. Runs in Node,
+// inside `tylix dev`, `tylix build` and `tylix start`, never in the
+// browser. Angular is compiled by AnalogJS's Vite plugin, so it runs in the
+// same Vite host as React, Svelte and Vue (no separate Angular CLI server).
+export default {
+  name: 'angular',
+  label: 'Angular',
+  root: 'app/frontend',
+
+  // One Angular runtime (core, router, ...) and one session in the bundle.
+  dedupe: [
+    '@angular/core',
+    '@angular/common',
+    '@angular/router',
+    '@angular/forms',
+    '@angular/platform-browser',
+    // Imported by @tylix/angular/server: without this, a linked @tylix/angular
+    // would load it (and through it a second @angular/core) from its own
+    // location, and server rendering fails with NG0201.
+    '@angular/platform-server',
+    '@angular/compiler',
+    'rxjs',
+    '@tylix/client',
+    '@tylix/angular',
+  ],
+
+  requires: ['vite', '@analogjs/vite-plugin-angular', '@angular/build', '@angular/compiler-cli', '@angular/core'],
+
+  async vitePlugins({ importFromProject, root }) {
+    const { default: angular } = await importFromProject('@analogjs/vite-plugin-angular')
+    // liveReload: Angular's component HMR, so template and style edits
+    // apply in place in `tylix dev` instead of reloading the page.
+    return angular({ tsconfig: path.join(root, 'tsconfig.json'), liveReload: true })
+  },
+
+  // Bundle Angular into the server build too. Its npm packages are only
+  // partially compiled; the Vite plugin's linker finishes them when they're
+  // bundled. Left external, Node would load them unlinked, and they fail
+  // without the JIT compiler. The same goes for any Angular component
+  // library, like tylix-icons/angular; add others to frontend.vite in
+  // tylix.config (ssr.noExternal).
+  viteConfig: {
+    ssr: { noExternal: [/^@angular\//, /^tylix-icons\/angular/] },
+  },
+
+  // Server-side rendering (frontend.ssr: true): app/frontend/entry-server
+  // renders pages with renderWithData from @tylix/angular/server.
+  ssr: true,
+  // Angular's server output includes <app-root> itself, so its outlet
+  // replaces that element in index.html; this puts it back when a page is
+  // not server-rendered.
+  ssrFallback: '<app-root></app-root>',
+
+  // `tylix build`: ngc checks templates too, which plain tsc can't.
+  // --noEmit here, not in the tsconfig: the Vite plugin compiles through
+  // that same tsconfig, and noEmit there makes it produce an empty bundle.
+  typecheck: {
+    bin: 'ngc',
+    args: (tsconfig) => ['-p', tsconfig, '--noEmit'],
+  },
+}

package/src/index.d.ts

@@ -0,0 +1,75 @@
+import type { InjectionToken, Signal } from '@angular/core'
+import type { CanActivateFn } from '@angular/router'
+import type { HttpInterceptorFn } from '@angular/common/http'
+import type { ApiOptions, ApiResult, Auth, TylixUser } from '@tylix/client'
+
+export { api, auth } from '@tylix/client'
+export type { ApiOptions, ApiResult, TylixUser } from '@tylix/client'
+
+export interface InjectedAuth {
+  status: Signal<'loading' | 'authenticated' | 'guest'>
+  user: Signal<TylixUser | null>
+  /** True after a session ended because it could not be refreshed. */
+  expired: Signal<boolean>
+  loading: Signal<boolean>
+  isAuthenticated: Signal<boolean>
+  login: Auth['login']
+  register: Auth['register']
+  logout: Auth['logout']
+  reload: Auth['reload']
+  forgotPassword: Auth['forgotPassword']
+  resetPassword: Auth['resetPassword']
+}
+
+export function injectAuth(): InjectedAuth
+
+/** Resolves once the first session check is done. */
+export function sessionReady(): Promise<void>
+
+export interface InjectedApi<T> {
+  data: Signal<T | null>
+  error: Signal<string | null>
+  errors: Signal<Record<string, string[]> | null>
+  status: Signal<number | null>
+  ok: Signal<boolean>
+  loading: Signal<boolean>
+  reload(): Promise<ApiResult<T> | null>
+}
+
+/** Call in an injection context. `url` may read signals; null skips fetching. */
+export function injectApi<T = unknown>(url: string | null | (() => string | null), options?: ApiOptions): InjectedApi<T>
+
+export const authGuard: CanActivateFn
+export const guestGuard: CanActivateFn
+export const tylixInterceptor: HttpInterceptorFn
+
+/** Same-site ?next= path, else '/dashboard'. */
+export function nextPath(next: unknown): string
+
+export type AccessDecision = null | { login: string } | { to: string }
+export function decideAccess(
+  access: 'auth' | 'guest' | undefined,
+  status: 'loading' | 'authenticated' | 'guest',
+  url: string,
+  next?: unknown,
+): AccessDecision
+
+/** What a component can change about the server response during SSR. */
+export interface ServerRenderContext {
+  status: number
+  redirect: string | null
+}
+
+export const TYLIX_SERVER: InjectionToken<ServerRenderContext>
+
+/** The server render's context during SSR; null in the browser. */
+export function useServerContext(): ServerRenderContext | null
+
+/** A live channel: connects after the first browser render, reconnects, closes on destroy. Injection context. */
+export function injectChannel<T = unknown>(
+  name: string,
+  onMessage?: (data: T) => void,
+): { send(data: unknown): void; status: Signal<import('@tylix/client').ChannelStatus> }
+
+/** False on the server and during hydration, true after the first browser render. Injection context. */
+export function injectHydrated(): Signal<boolean>

package/src/index.js

@@ -0,0 +1,284 @@
+// Angular bindings for the Tylix client: signals, functional guards and an
+// HttpClient interceptor. Plain JavaScript with no decorators, so it needs
+// no Angular compilation. The session logic itself (refresh, cross-tab
+// sync) lives in @tylix/client, so every frontend behaves the same.
+import {
+  DestroyRef,
+  InjectionToken,
+  PendingTasks,
+  afterNextRender,
+  computed,
+  effect,
+  inject,
+  signal,
+  untracked,
+} from '@angular/core'
+import { Router } from '@angular/router'
+import { HttpErrorResponse } from '@angular/common/http'
+import { catchError, from, switchMap, throwError } from 'rxjs'
+import { api, auth, lazyChannel, refreshSession, resultFromResponse } from '@tylix/client'
+import { canRefreshAfter401, decideAccess, nextPath } from './access.js'
+
+export { api, auth, nextPath, decideAccess }
+
+// Provided only while a page renders on the server (see ./server.js): that
+// request's session and loader, the data loaded so far, and what the render
+// decided about the response (status, redirect).
+export const TYLIX_SERVER = new InjectionToken('tylix:server')
+
+// The server render's context while rendering on the server; null in the
+// browser or outside an injection context.
+//   const server = useServerContext()
+//   if (server) server.status = 404
+export function useServerContext() {
+  try {
+    return inject(TYLIX_SERVER, { optional: true })
+  } catch {
+    return null // not in an injection context
+  }
+}
+
+// One signal mirror of the session, shared by every injectAuth() call in
+// the browser. Never used on the server, where state is per request.
+const sessionState = signal({ status: 'loading', user: null })
+let mirrored = false
+
+function mirrorSession() {
+  if (!mirrored) {
+    mirrored = true
+    sessionState.set(auth.getState())
+    auth.subscribe((state) => sessionState.set(state))
+  }
+  return auth.init()
+}
+
+// Resolves once the first session check is done.
+export function sessionReady() {
+  return mirrorSession()
+}
+
+function sessionSignals(state) {
+  return {
+    status: computed(() => state().status),
+    user: computed(() => state().user),
+    expired: computed(() => Boolean(state().expired)),
+    loading: computed(() => state().status === 'loading'),
+    isAuthenticated: computed(() => state().status === 'authenticated'),
+  }
+}
+
+const browserSession = sessionSignals(sessionState)
+
+// The current session as signals, plus the actions that change it. On the
+// server (in an injection context) it is that request's session; in the
+// browser the shared one, which main.ts initialised from the session the
+// server put in the page, so hydration sees the same state.
+export function injectAuth() {
+  const server = useServerContext()
+  if (!server) mirrorSession()
+  const signals = server ? sessionSignals(signal(server.authState)) : browserSession
+  return {
+    ...signals,
+    login: auth.login,
+    register: auth.register,
+    logout: auth.logout,
+    reload: auth.reload,
+    forgotPassword: auth.forgotPassword,
+    resetPassword: auth.resetPassword,
+  }
+}
+
+// False on the server and while a server-rendered page is hydrating; true
+// after the first render in the browser. Before that, a form's submit
+// button would do a native submit and reload the page, losing what was
+// typed, so starter forms keep their buttons disabled until this is true.
+// Call in an injection context.
+export function injectHydrated() {
+  const hydrated = signal(false)
+  afterNextRender(() => hydrated.set(true))
+  return hydrated.asReadonly()
+}
+
+// A live channel on the channel server ("tylix channels:work"). Call in an
+// injection context (a field initializer):
+//   chat = injectChannel<Message>('chat', (message) => ...)
+//   this.chat.send({ text })   and   chat.status() in templates
+// Connects after the first render in the browser (never on the server),
+// reconnects on its own, and closes with the component.
+export function injectChannel(name, onMessage) {
+  const status = signal('connecting')
+  const live = lazyChannel(name, { onMessage: (data) => onMessage?.(data), onStatus: (next) => status.set(next) })
+  afterNextRender(() => live.open())
+  inject(DestroyRef).onDestroy(() => live.close())
+  return { send: (data) => live.send(data), status: status.asReadonly() }
+}
+
+// Data a server render loaded for `url`, embedded in the page.
+function serverRenderedData(url) {
+  const data = globalThis.__TYLIX_DATA__
+  return url != null && data && Object.hasOwn(data, url) ? data[url] : undefined
+}
+
+function isGet(options) {
+  return !options?.method || String(options.method).toUpperCase() === 'GET'
+}
+
+// Fetches `url` now and again whenever it changes. `url` is a string or a
+// function of signals (() => `/api/posts/${this.id()}`); null skips. Call
+// it in an injection context (a field initializer or constructor): the
+// request is cancelled when the component is destroyed.
+//
+//   posts = injectApi<Post[]>('/api/posts')
+//   @for (post of posts.data() ?? []; track post.id) { ... }
+//
+// With SSR, GET requests are loaded on the server as pending tasks, which
+// Angular waits for before producing the HTML; the page arrives with their
+// data and the browser reuses it instead of fetching again.
+export function injectApi(url, options) {
+  const data = signal(null)
+  const error = signal(null)
+  const errors = signal(null)
+  const status = signal(null)
+  const ok = signal(false)
+  const loading = signal(false)
+
+  const apply = (result) => {
+    data.set(result.data)
+    error.set(result.error)
+    errors.set(result.errors)
+    status.set(result.status)
+    ok.set(result.ok)
+    loading.set(false)
+  }
+
+  const urlOf = typeof url === 'function' ? url : () => url
+  const server = useServerContext()
+  const pendingTasks = server ? inject(PendingTasks) : null
+
+  let controller = null
+  let runId = 0
+
+  async function load(current) {
+    if (current == null) {
+      loading.set(false)
+      return null
+    }
+    const id = ++runId
+
+    if (server) {
+      if (!isGet(options)) return null
+      // A pending task: Angular waits for it before producing the HTML.
+      const done = pendingTasks.add()
+      try {
+        loading.set(true)
+        const { status: code, data: body } = await server.load(current)
+        const result = resultFromResponse(code, body)
+        server.data[current] = result
+        if (id === runId) apply(result)
+        return result
+      } finally {
+        done()
+      }
+    }
+
+    controller?.abort()
+    controller = new AbortController()
+    loading.set(true)
+    const response = await api(current, { ...options, signal: controller.signal })
+    if (id === runId && !response.aborted) apply(response)
+    return response
+  }
+
+  // The url whose data came with the server-rendered page: shown at once,
+  // used instead of the first fetch, then dropped so a later mount fetches.
+  let serverRenderedUrl = null
+  if (!server && typeof url !== 'function') {
+    const preloaded = serverRenderedData(url)
+    if (preloaded) {
+      apply(preloaded)
+      serverRenderedUrl = url
+    }
+  }
+
+  // Re-runs when a signal read by urlOf changes. The request itself runs
+  // untracked, so signals it sets don't loop back into this effect.
+  effect(() => {
+    const current = urlOf()
+    untracked(() => {
+      if (!server && current != null && serverRenderedUrl === null) {
+        // A url built from signals (e.g. a route input) is only known here.
+        const preloaded = serverRenderedData(current)
+        if (preloaded && data() === null) {
+          apply(preloaded)
+          serverRenderedUrl = current
+        }
+      }
+      if (current != null && current === serverRenderedUrl) {
+        if (globalThis.__TYLIX_DATA__) delete globalThis.__TYLIX_DATA__[current]
+        serverRenderedUrl = undefined
+        return
+      }
+      load(current)
+    })
+  })
+
+  inject(DestroyRef).onDestroy(() => {
+    runId++
+    controller?.abort()
+  })
+
+  return {
+    data: data.asReadonly(),
+    error: error.asReadonly(),
+    errors: errors.asReadonly(),
+    status: status.asReadonly(),
+    ok: ok.asReadonly(),
+    loading: loading.asReadonly(),
+    reload: () => load(untracked(urlOf)),
+  }
+}
+
+function guard(access) {
+  return async (route, state) => {
+    const router = inject(Router)
+    const server = useServerContext()
+    const status = server ? server.authState.status : (await sessionReady(), auth.getState().status)
+    const decision = decideAccess(access, status, state.url, route.queryParamMap.get('next'))
+    if (!decision) return true
+
+    const target = decision.login ? `/login?next=${encodeURIComponent(decision.login)}` : decision.to
+    if (server) {
+      // Answered with a 302 by the Tylix host; nothing is rendered.
+      server.redirect = target
+      return false
+    }
+    return router.parseUrl(target)
+  }
+}
+
+// canActivate: [authGuard] for pages that need a logged-in user. Waits for
+// the first session check, then sends guests to /login?next=<this page>
+// (a 302 when rendering on the server). Hides pages only; the API's
+// requireAuth protects the data.
+export const authGuard = guard('auth')
+
+// canActivate: [guestGuard] for login/register: a logged-in user goes to
+// ?next= or the dashboard.
+export const guestGuard = guard('guest')
+
+// For apps that use HttpClient: sends the session cookies, and on a 401
+// renews the session once (shared with api()) and retries the request.
+//
+//   provideHttpClient(withFetch(), withInterceptors([tylixInterceptor]))
+export function tylixInterceptor(request, next) {
+  const withCookies = request.clone({ withCredentials: true })
+  return next(withCookies).pipe(
+    catchError((err) => {
+      const retryable = err instanceof HttpErrorResponse && err.status === 401 && canRefreshAfter401(request.url)
+      if (!retryable) return throwError(() => err)
+      return from(refreshSession()).pipe(
+        switchMap((renewed) => (renewed ? next(withCookies) : throwError(() => err))),
+      )
+    }),
+  )
+}

package/src/server.d.ts

@@ -0,0 +1,22 @@
+import type { ApplicationRef } from '@angular/core'
+import type { BootstrapContext } from '@angular/platform-browser'
+import type { ApiResult, TylixUser } from '@tylix/client'
+
+export interface RenderOptions {
+  url?: string
+  session?: { user: TylixUser | null } | null
+  load?: (url: string) => Promise<{ status: number; data: unknown }>
+}
+
+export interface RenderResult {
+  html: string
+  head: string
+  status: number
+  redirect: string | null
+  data: Record<string, ApiResult>
+}
+
+export function renderWithData(
+  bootstrap: (context: BootstrapContext) => Promise<ApplicationRef>,
+  options?: RenderOptions,
+): Promise<RenderResult>

package/src/server.js

@@ -0,0 +1,62 @@
+// Server-side rendering for Tylix Angular apps. Imported only by the app's
+// entry-server file, so @angular/platform-server never reaches the browser.
+import { renderApplication } from '@angular/platform-server'
+import { TYLIX_SERVER } from './index.js'
+
+// Angular skips browser-only work (event replay, which touches `window`)
+// when ngServerMode is set. The Angular CLI defines it for server bundles;
+// Vite doesn't, so it is set here. This module only ever runs in the
+// server process, never in a browser.
+globalThis.ngServerMode = true
+
+// Angular renders a whole document. This minimal one only hosts the app;
+// the head and body it produces go into the app's own index.html.
+const DOCUMENT = '<!doctype html><html><head></head><body><app-root></app-root></body></html>'
+
+function between(html, open, close) {
+  const start = html.search(open)
+  if (start === -1) return ''
+  const from = html.indexOf('>', start) + 1
+  const end = html.lastIndexOf(close)
+  return end > from ? html.slice(from, end) : ''
+}
+
+// The per-request context, provided to the app as TYLIX_SERVER.
+export function createServerContext({ session = null, load } = {}) {
+  return {
+    authState: session?.user
+      ? { status: 'authenticated', user: session.user }
+      : { status: 'guest', user: null },
+    load: load ?? (async () => ({ status: 404, data: { error: 'Not found' } })),
+    data: {},
+    status: 200,
+    redirect: null,
+  }
+}
+
+// Renders the app for one request. `bootstrap` is the app's server
+// bootstrap: (context) => bootstrapApplication(App, config, context).
+// Every injectApi GET is loaded as a pending task, which Angular waits for,
+// so one pass renders the page with its data.
+//
+// Resolves { html, head, status, redirect, data } for the Tylix host: html
+// is the <app-root> element plus Angular's hydration state script, head is
+// what Angular put in <head> (component styles), and data is embedded in
+// the page so the browser's first render reuses it.
+export async function renderWithData(bootstrap, { url = '/', session = null, load } = {}) {
+  const context = createServerContext({ session, load })
+  const document = await renderApplication(bootstrap, {
+    document: DOCUMENT,
+    url,
+    platformProviders: [{ provide: TYLIX_SERVER, useValue: context }],
+  })
+
+  if (context.redirect) return { html: '', head: '', status: 302, redirect: context.redirect, data: {} }
+  return {
+    html: between(document, /<body[\s>]/i, '</body>'),
+    head: between(document, /<head[\s>]/i, '</head>'),
+    status: context.status,
+    redirect: null,
+    data: context.data,
+  }
+}