@webjsdev/core 0.7.6 → 0.7.8

package/index-browser.js

@@ -48,8 +48,16 @@ export { WebjsFrame } from './src/webjs-frame.js';
 // Signals (TC39 Stage-1 shape), also available via '@webjsdev/core/signals'
 export { signal, computed, effect, batch, isSignal, Signal } from './src/signal.js';
 
-// Directives, also available via '@webjsdev/core/directives'
-export { unsafeHTML, isUnsafeHTML, live, isLive } from './src/directives.js';
+// Directives, also available via '@webjsdev/core/directives'. The full
+// lit-html-parity set is re-exported here so the dist browser bundle (which
+// the `@webjsdev/core/directives` subpath collapses onto in dist mode) carries
+// every directive, matching what src/directives.js exports in dev.
+export {
+  unsafeHTML, isUnsafeHTML, live, isLive, keyed, isKeyed, guard, isGuard,
+  templateContent, isTemplateContent, ref, isRef, createRef, cache, isCache,
+  until, isUntil, asyncAppend, isAsyncAppend, asyncReplace, isAsyncReplace,
+  watch, isWatch,
+} from './src/directives.js';
 
 // Context Protocol, also available via '@webjsdev/core/context'
 export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from './src/context.js';

package/index.d.ts

@@ -9,6 +9,50 @@
  */
 
 export * from './src/component.d.ts';
+export type {
+  Metadata,
+  MetadataContext,
+  TitleMetadata,
+  ViewportMetadata,
+  RobotsMetadata,
+  AlternatesMetadata,
+  VerificationMetadata,
+  OpenGraphMetadata,
+  TwitterMetadata,
+  AppleWebAppMetadata,
+  IconsMetadata,
+  IconDescriptor,
+  AuthorMetadata,
+  PreloadDescriptor,
+  JsonLd,
+} from './src/metadata.d.ts';
+
+// Typed route props + the opt-in generated route union (#258). The
+// `WebjsRoutes` / `RouteParamMap` interfaces are exported as VALUES-of-types
+// (interfaces) so app code and the generated `.webjs/routes.d.ts` can augment
+// them via `declare module '@webjsdev/core'`.
+export type {
+  Route,
+  RouteParams,
+  PageProps,
+  LayoutProps,
+  RouteHandlerContext,
+  WebjsRoutes,
+  RouteParamMap,
+} from './src/routes.d.ts';
+
+// The package.json `webjs` config block (#259). Typed reference for the
+// elide / headers / redirects / trailingSlash / csp / ingress-limit knobs;
+// the companion JSON Schema (packages/server/webjs-config.schema.json) gives
+// editors native validation of package.json itself.
+export type {
+  WebjsConfig,
+  WebjsHeaderRule,
+  WebjsHeaderDirective,
+  WebjsRedirectRule,
+  WebjsTrailingSlash,
+  WebjsCspConfig,
+} from './src/webjs-config.d.ts';
 
 export { html, isTemplate, MARKER } from './src/html.js';
 export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
@@ -22,7 +66,14 @@ export { repeat, isRepeat } from './src/repeat.js';
 export { Suspense, isSuspense } from './src/suspense.js';
 export { connectWS } from './src/websocket-client.js';
 export { richFetch } from './src/rich-fetch.js';
-export { enableClientRouter, disableClientRouter, navigate } from './src/router-client.js';
+export { enableClientRouter, disableClientRouter } from './src/router-client.js';
+
+// `navigate` is typed against the generated `Route` union (#258) rather than
+// the JSDoc `string`. Until an app runs `webjs types`, `Route` resolves to
+// `string`, so this is non-breaking; once generated, a bogus in-app path is a
+// tsserver error. The runtime is the same async function in router-client.js.
+import type { Route } from './src/routes.d.ts';
+export function navigate(url: Route, opts?: { replace?: boolean }): Promise<void>;
 export { unsafeHTML, isUnsafeHTML, live, isLive } from './src/directives.js';
 export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from './src/context.js';
 export { Task, TaskStatus } from './src/task.js';

package/index.js

@@ -30,8 +30,15 @@ export { WebjsFrame } from './src/webjs-frame.js';
 // Signals (TC39 Stage-1 shape), also available via '@webjsdev/core/signals'
 export { signal, computed, effect, batch, isSignal, Signal } from './src/signal.js';
 
-// Directives, also available via '@webjsdev/core/directives'
-export { unsafeHTML, isUnsafeHTML, live, isLive } from './src/directives.js';
+// Directives, also available via '@webjsdev/core/directives'. The full
+// lit-html-parity set is re-exported so the bare specifier exposes the same
+// directive surface in Node as the browser bundle does.
+export {
+  unsafeHTML, isUnsafeHTML, live, isLive, keyed, isKeyed, guard, isGuard,
+  templateContent, isTemplateContent, ref, isRef, createRef, cache, isCache,
+  until, isUntil, asyncAppend, isAsyncAppend, asyncReplace, isAsyncReplace,
+  watch, isWatch,
+} from './src/directives.js';
 
 // Context Protocol, also available via '@webjsdev/core/context'
 export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from './src/context.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "type": "module",
   "description": "webjs core runtime - html/css tags, WebComponent base, isomorphic renderers",
   "types": "./index.d.ts",

package/src/component.js

@@ -260,6 +260,96 @@ class ServerElement {
     return [...this.__ssrAttrs.keys()];
   }
 
+  /**
+   * Minimal `Element.closest()` for SSR. The SSR walker threads the chain
+   * of enclosing custom-element instances into each instance
+   * (`__ssrAncestors`); this walks self-then-ancestors and returns the
+   * nearest whose tag matches. Only bare tag-name selectors are supported
+   * server-side (`closest('ui-tabs')`), which is what compound components
+   * need to read parent state for a correct first paint; anything more
+   * specific (class, attribute, or descendant selectors) returns null,
+   * matching the pre-shim behaviour. The browser runs the real `closest()`
+   * on hydration.
+   * @param {string} selector
+   * @returns {any}
+   */
+  closest(selector) {
+    const sel = String(selector).trim().toLowerCase();
+    // Tag-name selectors only at SSR; bail (null) on anything else.
+    if (!/^[a-z][a-z0-9-]*$/.test(sel)) return null;
+    if (this.__ssrTag === sel) return this;
+    const chain = this.__ssrAncestors;
+    if (!Array.isArray(chain)) return null;
+    for (let i = chain.length - 1; i >= 0; i--) {
+      if (chain[i] && chain[i].__ssrTag === sel) return chain[i];
+    }
+    return null;
+  }
+
+  /**
+   * `HTMLElement.dataset`: a live view over the element's `data-*`
+   * attributes, backed by the SSR attribute Map. Reading / writing
+   * `el.dataset.fooBar` maps to the `data-foo-bar` attribute (camelCase
+   * to kebab-case), so a `render()` that sets `this.dataset.state = 'on'`
+   * surfaces `data-state="on"` in the SSR'd host tag instead of crashing
+   * on an undefined `dataset`.
+   * @returns {Record<string, string>}
+   */
+  get dataset() {
+    if (this.__dataset) return this.__dataset;
+    const el = this;
+    const toAttr = (p) => 'data-' + String(p).replace(/[A-Z]/g, (m) => '-' + m.toLowerCase());
+    this.__dataset = new Proxy(/** @type {Record<string,string>} */ ({}), {
+      get(_t, prop) {
+        if (typeof prop !== 'string') return undefined;
+        const v = el.getAttribute(toAttr(prop));
+        return v === null ? undefined : v;
+      },
+      set(_t, prop, value) {
+        if (typeof prop === 'string') el.setAttribute(toAttr(prop), value);
+        return true;
+      },
+      has(_t, prop) {
+        return typeof prop === 'string' && el.hasAttribute(toAttr(prop));
+      },
+      deleteProperty(_t, prop) {
+        if (typeof prop === 'string') el.removeAttribute(toAttr(prop));
+        return true;
+      },
+      ownKeys() {
+        return el.getAttributeNames()
+          .filter((n) => n.startsWith('data-'))
+          .map((n) => n.slice(5).replace(/-([a-z])/g, (_m, c) => c.toUpperCase()));
+      },
+      getOwnPropertyDescriptor(_t, prop) {
+        if (typeof prop === 'string' && el.hasAttribute(toAttr(prop))) {
+          return { enumerable: true, configurable: true, value: el.getAttribute(toAttr(prop)) };
+        }
+        return undefined;
+      },
+    });
+    return this.__dataset;
+  }
+
+  // IDL properties that reflect to a content attribute. A render() that
+  // mutates these on the host (a light-DOM compound-component pattern, e.g.
+  // `this.className = ...`, `this.hidden = !active`) then surfaces the
+  // matching attribute in the SSR'd host tag, matching the browser.
+  get className() { return this.getAttribute('class') ?? ''; }
+  set className(v) { this.setAttribute('class', v); }
+  get hidden() { return this.hasAttribute('hidden'); }
+  set hidden(v) { this.toggleAttribute('hidden', !!v); }
+  get id() { return this.getAttribute('id') ?? ''; }
+  set id(v) { this.setAttribute('id', v); }
+  get title() { return this.getAttribute('title') ?? ''; }
+  set title(v) { this.setAttribute('title', v); }
+  get slot() { return this.getAttribute('slot') ?? ''; }
+  set slot(v) { this.setAttribute('slot', v); }
+  get role() { return this.getAttribute('role'); }
+  set role(v) { v == null ? this.removeAttribute('role') : this.setAttribute('role', v); }
+  get tabIndex() { const v = this.getAttribute('tabindex'); return v === null ? -1 : (Number.parseInt(v, 10) || 0); }
+  set tabIndex(v) { this.setAttribute('tabindex', String(v)); }
+
   // No server event loop: listeners never fire at SSR. The no-op keeps a
   // constructor that wires delegated listeners (a common lit pattern) from
   // crashing; the browser re-runs the constructor on hydration where the
@@ -282,6 +372,30 @@ class ServerElement {
   }
 }
 
+// ARIAMixin IDL reflections (`el.ariaPressed = 'true'` writes aria-pressed).
+// A render() that sets ARIA state via the IDL properties then surfaces the
+// matching aria-* attribute in the SSR'd host tag, matching the browser. The
+// IDL name maps to the content attribute by lowercasing the part after
+// `aria` and prefixing `aria-` (ariaPressed -> aria-pressed).
+const ARIA_IDL_PROPS = [
+  'ariaAtomic', 'ariaAutoComplete', 'ariaBusy', 'ariaChecked', 'ariaColCount',
+  'ariaColIndex', 'ariaColSpan', 'ariaCurrent', 'ariaDescription', 'ariaDisabled',
+  'ariaExpanded', 'ariaHasPopup', 'ariaHidden', 'ariaInvalid', 'ariaKeyShortcuts',
+  'ariaLabel', 'ariaLevel', 'ariaLive', 'ariaModal', 'ariaMultiLine',
+  'ariaMultiSelectable', 'ariaOrientation', 'ariaPlaceholder', 'ariaPosInSet',
+  'ariaPressed', 'ariaReadOnly', 'ariaRequired', 'ariaRoleDescription',
+  'ariaRowCount', 'ariaRowIndex', 'ariaRowSpan', 'ariaSelected', 'ariaSetSize',
+  'ariaSort', 'ariaValueMax', 'ariaValueMin', 'ariaValueNow', 'ariaValueText',
+];
+for (const idl of ARIA_IDL_PROPS) {
+  const attr = 'aria-' + idl.slice(4).toLowerCase();
+  Object.defineProperty(ServerElement.prototype, idl, {
+    configurable: true,
+    get() { return this.getAttribute(attr); },
+    set(v) { v == null ? this.removeAttribute(attr) : this.setAttribute(attr, String(v)); },
+  });
+}
+
 // Base class choice: real HTMLElement on the browser, the shim on the server.
 const Base = isBrowser ? HTMLElement : /** @type {any} */ (ServerElement);
 

package/src/directives.js

@@ -12,11 +12,17 @@
  * } from '@webjsdev/core/directives';
  * ```
  *
- * `repeat()` lives in `./repeat.js` (re-exported from the package root).
+ * `repeat()` is implemented in `./repeat.js`; it is re-exported here so the
+ * `@webjsdev/core/directives` subpath exposes the whole documented directive
+ * table in src/dev mode too (the dist browser bundle already carries it).
  *
  * @module directives
  */
 
+// Re-export so the `/directives` subpath surface matches the documented table
+// in both src and dist mode. The implementation stays in repeat.js.
+export { repeat, isRepeat } from './repeat.js';
+
 /* ================================================================
  * unsafeHTML
  * ================================================================ */

package/src/metadata.d.ts

@@ -0,0 +1,279 @@
+/**
+ * TypeScript overlay for the `metadata` / `generateMetadata` return shape.
+ *
+ * A page or layout exports `metadata` (static) or `generateMetadata(ctx)`
+ * (request-scoped). Both return a plain object that the SSR pipeline
+ * (packages/server/src/ssr.js) reads field by field and emits into the
+ * document `<head>`. This file types that object so authors get
+ * autocomplete and typo checking:
+ *
+ *     import type { Metadata } from '@webjsdev/core';
+ *     export const metadata: Metadata = { title: 'Home', description: '…' };
+ *     export async function generateMetadata(ctx: MetadataContext): Promise<Metadata> { … }
+ *
+ * The shape mirrors what ssr.js actually consumes (and agent-docs/metadata.md
+ * documents), NOT Next.js's full superset. Every field is optional. Zero
+ * runtime cost: nothing in this file ships to the browser.
+ */
+
+/** A URL or relative path. Relative values resolve against `metadataBase`. */
+type MetadataUrl = string;
+
+/** `title` accepts a plain string or the template object Next.js uses. */
+export type TitleMetadata =
+  | string
+  | {
+      /** Wraps a deeper plain-string title via the `%s` placeholder. */
+      template?: string;
+      /** Title used when a deeper layer supplies none. */
+      default?: string;
+      /** Bypasses the inherited template entirely for this layer. */
+      absolute?: string;
+    };
+
+/** An author entry: a bare name, or `{ name, url? }`. */
+export type AuthorMetadata = string | { name?: string; url?: MetadataUrl };
+
+/** `viewport` object form (Next.js 14+ split-export shape). */
+export interface ViewportMetadata {
+  width?: string | number;
+  height?: string | number;
+  initialScale?: number;
+  minimumScale?: number;
+  maximumScale?: number;
+  /** `false` emits `user-scalable=no`, `true` emits `yes`. */
+  userScalable?: boolean;
+  viewportFit?: 'auto' | 'contain' | 'cover';
+  interactiveWidget?: 'resizes-visual' | 'resizes-content' | 'overlays-content';
+  /** May also carry `themeColor` / `colorScheme` on the split `viewport` export. */
+  themeColor?: string;
+  colorScheme?: string;
+}
+
+/** `robots` object form (a bare string is also accepted). */
+export interface RobotsMetadata {
+  index?: boolean;
+  follow?: boolean;
+  noarchive?: boolean;
+  nosnippet?: boolean;
+  noimageindex?: boolean;
+  /** Emitted verbatim as `<meta name="googlebot">`. */
+  googleBot?: string;
+}
+
+/** `alternates`: canonical + i18n / media / type alternates. */
+export interface AlternatesMetadata {
+  canonical?: MetadataUrl;
+  /** hreflang -> URL, e.g. `{ 'es-ES': '/es' }`. */
+  languages?: Record<string, MetadataUrl>;
+  /** media query -> URL, e.g. `{ '(max-width: 600px)': '/mobile' }`. */
+  media?: Record<string, MetadataUrl>;
+  /** MIME type -> URL, e.g. `{ 'application/rss+xml': '/rss.xml' }`. */
+  types?: Record<string, MetadataUrl>;
+}
+
+/** Site-verification tokens. Each value is a token or list of tokens. */
+export interface VerificationMetadata {
+  google?: string | string[];
+  yandex?: string | string[];
+  yahoo?: string | string[];
+  /** IndieAuth / personal `<meta name="me">`. */
+  me?: string | string[];
+  /** Arbitrary `<meta name="…">` verification entries. */
+  other?: Record<string, string | string[]>;
+}
+
+/** A single icon descriptor. */
+export type IconDescriptor =
+  | MetadataUrl
+  | { url: MetadataUrl; sizes?: string; type?: string };
+
+/** `icons`: a bare URL, a list, or the bucketed object form. */
+export type IconsMetadata =
+  | MetadataUrl
+  | IconDescriptor[]
+  | {
+      icon?: IconDescriptor | IconDescriptor[];
+      apple?: IconDescriptor | IconDescriptor[];
+      shortcut?: IconDescriptor | IconDescriptor[];
+      /** Catch-all: each entry carries its own `rel`. */
+      other?:
+        | { rel: string; url: MetadataUrl; sizes?: string; type?: string }
+        | Array<{ rel: string; url: MetadataUrl; sizes?: string; type?: string }>;
+    };
+
+/**
+ * `openGraph`. Each key is emitted as `<meta property="og:<key>">`, so the
+ * indexer carries the documented keys plus an open-ended fallback for the
+ * `og:image:width` / `image:height` / `image:alt` style entries.
+ */
+export interface OpenGraphMetadata {
+  type?: string;
+  title?: string;
+  description?: string;
+  url?: MetadataUrl;
+  image?: MetadataUrl;
+  site_name?: string;
+  [key: string]: string | undefined;
+}
+
+/** `twitter` card. Each key is emitted as `<meta name="twitter:<key>">`. */
+export interface TwitterMetadata {
+  card?: 'summary' | 'summary_large_image' | 'app' | 'player';
+  title?: string;
+  description?: string;
+  image?: MetadataUrl;
+  site?: string;
+  creator?: string;
+  [key: string]: string | undefined;
+}
+
+/** A startup-image entry for `appleWebApp.startupImage`. */
+export type AppleStartupImage =
+  | MetadataUrl
+  | { url: MetadataUrl; media?: string };
+
+/** `appleWebApp`: `true` (capable) or the descriptor object. */
+export type AppleWebAppMetadata =
+  | boolean
+  | {
+      capable?: boolean;
+      title?: string;
+      statusBarStyle?: 'default' | 'black' | 'black-translucent';
+      startupImage?: AppleStartupImage | AppleStartupImage[];
+    };
+
+/**
+ * A single JSON-LD structured-data object (schema.org). The author owns the
+ * shape (Article, Product, BreadcrumbList, Organization, FAQPage, etc.), so
+ * this is intentionally permissive. The framework serializes it with
+ * `JSON.stringify` and HTML-safe-escapes the output into a
+ * `<script type="application/ld+json">` block.
+ */
+export type JsonLd = Record<string, unknown>;
+
+/** A `metadata.preload` link descriptor (emitted as `<link rel="preload">`). */
+export interface PreloadDescriptor {
+  href: MetadataUrl;
+  as?: string;
+  type?: string;
+  crossorigin?: string;
+  media?: string;
+  [attr: string]: string | undefined;
+}
+
+/**
+ * The return shape of `metadata` / `generateMetadata`.
+ *
+ * Mirrors exactly what packages/server/src/ssr.js consumes. Every field is
+ * optional. Where the framework accepts a string OR an object (`title`,
+ * `viewport`, `robots`, `appleWebApp`, `icons`), the type is a union.
+ *
+ * @see agent-docs/metadata.md for the field-by-field emission reference.
+ */
+export interface Metadata {
+  /** -> `<title>`. Plain string or `{ template, default, absolute }`. */
+  title?: TitleMetadata;
+  /** -> `<meta name="description">`. */
+  description?: string;
+  /** -> `<meta name="keywords">`. A list is comma-joined. */
+  keywords?: string | string[];
+  /** -> `<meta name="author">` (+ optional `<link rel="author">`). */
+  authors?: AuthorMetadata | AuthorMetadata[];
+  /** -> `<meta name="creator">`. */
+  creator?: string;
+  /** -> `<meta name="publisher">`. */
+  publisher?: string;
+  /** -> `<meta name="application-name">`. */
+  applicationName?: string;
+  /** -> `<meta name="generator">`. */
+  generator?: string;
+  /** -> `<meta name="referrer">`. */
+  referrer?: string;
+
+  /** Base for resolving every relative URL in this object. */
+  metadataBase?: string;
+
+  /** -> `<meta name="viewport">`. String form OR object form. */
+  viewport?: string | ViewportMetadata;
+  /** -> `<meta name="theme-color">`. */
+  themeColor?: string;
+  /** -> `<meta name="color-scheme">`. */
+  colorScheme?: string;
+
+  /** -> `<meta name="robots">`. A string OR the object form. */
+  robots?: string | RobotsMetadata;
+  /** Canonical + i18n / media / type alternates. */
+  alternates?: AlternatesMetadata;
+  /** Site-verification tokens. */
+  verification?: VerificationMetadata;
+
+  /** Icon links. Bare URL, list, or bucketed object. */
+  icons?: IconsMetadata;
+  /** -> `<link rel="manifest">`. */
+  manifest?: string;
+
+  /** Open Graph tags (`<meta property="og:*">`). */
+  openGraph?: OpenGraphMetadata;
+  /** Twitter card tags (`<meta name="twitter:*">`). */
+  twitter?: TwitterMetadata;
+
+  /** iOS web-app meta. `true` (capable) or the descriptor object. */
+  appleWebApp?: AppleWebAppMetadata;
+  /** -> `<meta name="format-detection">`. Each value is a boolean. */
+  formatDetection?: Record<string, boolean>;
+  /** -> `<meta name="apple-itunes-app">`. */
+  itunes?: { appId: string; appArgument?: string };
+
+  /** -> `<meta name="category">`. */
+  category?: string;
+  /** -> `<meta name="classification">`. */
+  classification?: string;
+  /** -> `<meta name="abstract">`. */
+  abstract?: string;
+  /** -> `<link rel="archives">`. */
+  archives?: string | string[];
+  /** -> `<link rel="assets">`. */
+  assets?: string | string[];
+  /** -> `<link rel="bookmark">`. */
+  bookmarks?: string | string[];
+
+  /**
+   * Response `Cache-Control` header (NOT a `<meta>` tag). Pages default to
+   * `no-store`; a public value (e.g. `public, max-age=60`) also enables
+   * conditional GET on the page.
+   */
+  cacheControl?: string;
+  /** `<link rel="preload">` hints (fonts, images, etc.). */
+  preload?: PreloadDescriptor[];
+
+  /**
+   * JSON-LD structured data (schema.org), emitted as one or more
+   * `<script type="application/ld+json">` blocks in `<head>`. A single
+   * object emits ONE script; an array emits one script PER element. The
+   * author owns the schema.org shape; the framework serializes with
+   * `JSON.stringify` and HTML-safe-escapes the output automatically (a
+   * value containing `</script>` can never break out of the tag). Works in
+   * `generateMetadata(ctx)` for per-request data (a per-post Article, etc.).
+   */
+  jsonLd?: JsonLd | JsonLd[];
+
+  /** Catch-all `<meta name="…">` entries. Value may be a list. */
+  other?: Record<string, string | number | Array<string | number>>;
+}
+
+/**
+ * The argument `generateMetadata(ctx)` receives. Mirrors the page context
+ * (the same `{ params, searchParams, url, actionData }` a page function gets).
+ */
+export interface MetadataContext {
+  params: Record<string, string>;
+  searchParams?: Record<string, string | string[]>;
+  url: string;
+  /**
+   * Present only on the re-render after a failed page `action` submission.
+   * `undefined` on a normal GET render. Read it to vary the title on a
+   * validation-error re-render.
+   */
+  actionData?: unknown;
+}

package/src/render-server.js

@@ -362,7 +362,7 @@ function browserMemberHint(e) {
  * @param {SuspenseCtx} [ctx]
  * @returns {Promise<string>}
  */
-async function injectDSD(html, ctx) {
+async function injectDSD(html, ctx, ancestors = []) {
   const tags = allTags();
   if (!tags.length) return html;
   // Sort longest tag name first so the regex alternation tries the most
@@ -391,6 +391,12 @@ async function injectDSD(html, ctx) {
     try {
       const isShadow = /** @type any */ (Cls).shadow === true;
       const instance = new /** @type any */ (Cls)();
+      // Thread the ancestor chain (the enclosing custom-element instances)
+      // so the server element shim's closest() can resolve a parent at SSR.
+      // Set before performServerUpdate so a willUpdate() that reads a parent
+      // via closest() sees the chain. Each child recursion below extends it.
+      instance.__ssrTag = tag;
+      instance.__ssrAncestors = ancestors;
       const attrMap = parseAttrs(attrs);
       // Decode `data-webjs-prop-*` attributes first (rich-typed values
       // emitted for `.prop=${val}` bindings in the parent template),
@@ -416,13 +422,16 @@ async function injectDSD(html, ctx) {
       // SSR. WebComponent instances expose performServerUpdate; bare
       // Base-extending kit components (no lifecycle) do not, so it is guarded.
       if (typeof instance.performServerUpdate === 'function') instance.performServerUpdate();
-      // Surface attributes the component set before render (reflected
-      // reflect:true props, or an explicit this.setAttribute in the
-      // constructor / willUpdate) that were not already in the source tag.
-      // Appending keeps the original tag byte-identical when nothing changed.
-      opening = appendReflectedAttrs(opening, instance, presentAttrNames);
       let tpl = instance.render ? instance.render() : '';
       if (tpl && typeof tpl.then === 'function') tpl = await tpl;
+      // Surface attributes the component set up to and including render()
+      // that were not already in the source tag: reflected reflect:true
+      // props, an explicit this.setAttribute in the constructor / willUpdate,
+      // or a host-attribute mutation inside render() itself (a light-DOM
+      // compound-component pattern, e.g. this.dataset.state / this.className /
+      // this.hidden on the host). Reading after render() captures all three.
+      // Appending keeps the original tag byte-identical when nothing changed.
+      opening = appendReflectedAttrs(opening, instance, presentAttrNames);
       // Render the template to HTML. injectDSD recurses on the result so
       // nested custom elements (e.g. <theme-toggle> inside <blog-shell>)
       // get their own DSD pass.
@@ -432,7 +441,7 @@ async function injectDSD(html, ctx) {
         // Shadow DOM: native <slot> stays as-is in the DSD template. The
         // browser handles projection from the host's light-DOM children
         // into the shadow tree natively. No framework substitution here.
-        const innerProcessed = await injectDSD(rawInner, ctx);
+        const innerProcessed = await injectDSD(rawInner, ctx, [...ancestors, instance]);
         const rawStyles = /** @type any */ (Cls).styles;
         const styleList = Array.isArray(rawStyles) ? rawStyles : rawStyles && isCSS(rawStyles) ? [rawStyles] : [];
         const styleStr = stylesToString(styleList);
@@ -495,7 +504,7 @@ async function injectDSD(html, ctx) {
         }
         const partitioned = partitionAuthoredBySlot(authoredInner);
         const innerWithSlots = substituteSlotsInRender(rawInner, partitioned);
-        const innerProcessed = await injectDSD(innerWithSlots, ctx);
+        const innerProcessed = await injectDSD(innerWithSlots, ctx, [...ancestors, instance]);
         edits.push({
           start: m.index,
           end: closeEnd,
@@ -523,6 +532,11 @@ async function injectDSD(html, ctx) {
   // independently against the original html, but those inner elements
   // are processed by the recursive injectDSD call on innerWithSlots.
   // Keeping both edits would double-process them and corrupt the output.
+  // A consequence: a nested instance's render() runs once per chain depth
+  // (the discarded top-level pass sees an empty ancestor chain, so its
+  // closest() reads null; the kept recursive pass has the real chain). The
+  // kept pass is the only output, and closest() is a read, so render() must
+  // stay pure at SSR (the standard SSR contract), not branch on side effects.
   edits.sort((a, b) => a.start - b.start);
   /** @type {{start:number, end:number, text:string}[]} */
   const filtered = [];

package/src/router-client.js

@@ -1473,6 +1473,23 @@ function applySwap(doc, frameId, revalidating, href, incomingBuild) {
       blurOutgoingFocus();
       return;
     }
+    // The response did not carry the requested frame (source null), or the
+    // target frame is gone from the live DOM (target null). Falling through
+    // would wholesale-replace the document, a silent full-page swap that
+    // destroys the page (e.g. an auth redirect returning a login page without
+    // the frame). Surface the contract violation with a cancelable event
+    // instead. Default: warn and leave the frame unchanged. A listener that
+    // calls preventDefault owns the outcome.
+    const evt = new CustomEvent('webjs:frame-missing', {
+      bubbles: true,
+      cancelable: true,
+      detail: { frameId, url: href || (typeof location !== 'undefined' ? location.href : null), document: doc },
+    });
+    (target || document).dispatchEvent(evt);
+    if (!evt.defaultPrevented) {
+      console.warn(`[webjs] frame "${frameId}" was not in the navigation response, leaving it unchanged. Handle "webjs:frame-missing" (preventDefault) to override.`);
+    }
+    return;
   }
 
   // 2. Auto-derived layout-marker swap.