@bleedingdev/modern-js-renderer-solid 0.0.0-stage → 3.9.3-ultramodern.1

package/src/route-completion.tsx

@@ -0,0 +1,222 @@
+import { DataProtocolError } from '@modern-js/renderer-core/data';
+import type { RequestSession } from '@modern-js/renderer-core/session';
+import { Dynamic, type JSX } from '@solidjs/web';
+import type { AnyRouter, CreateRouterFn } from '@tanstack/router-core';
+import type { Accessor } from 'solid-js';
+import { createEffect, createMemo, createSignal, onCleanup } from 'solid-js';
+import type { AnyRoute, RouteComponent } from './router-binding/index';
+import {
+  createRouter,
+  preparePublicContextData,
+  useMatch,
+} from './router-binding/index';
+import { registerPublicRouteDataOwner } from './router-binding/registryTransfer';
+
+interface CompletionRecord {
+  readonly failure: Accessor<{ reason: unknown } | undefined>;
+  acquire(): () => void;
+}
+
+interface PublicDataGeneration {
+  readonly owner: Pick<RequestSession, 'fail' | 'signal'>;
+  publish(value: unknown, completion?: Promise<void>): void;
+}
+
+export interface RouteCompletionScope {
+  readonly hydrationOwner: Pick<RequestSession, 'fail' | 'signal'>;
+  readonly privateRoots: readonly object[];
+  attach(router: AnyRouter): void;
+  begin(signal: AbortSignal, cancel: () => void): PublicDataGeneration;
+  component(component: RouteComponent): RouteComponent;
+  dispose(): void;
+}
+
+// These weak associations contain owned lifecycles, never ambient request data.
+const routeScopes = new WeakMap<AnyRoute, RouteCompletionScope>();
+const routerScopes = new WeakMap<AnyRouter, RouteCompletionScope>();
+
+function assertManagedRouteData(route: AnyRoute | undefined): void {
+  if (!route) return;
+  if (route.options.loader || route.options.beforeLoad || route.options.context)
+    throw new DataProtocolError(
+      'Custom native Solid loader/beforeLoad/context routes are unsupported by the immutable public-data profile; use createFileSystemRouteTree',
+    );
+  for (const child of route.children ?? []) assertManagedRouteData(child);
+}
+
+export function registerRouteCompletionScope(
+  route: AnyRoute,
+  scope: RouteCompletionScope,
+): void {
+  routeScopes.set(route, scope);
+}
+
+export const createApplicationRouter: CreateRouterFn = options => {
+  const scope = options.routeTree
+    ? routeScopes.get(options.routeTree)
+    : undefined;
+  if (!scope) assertManagedRouteData(options.routeTree);
+  if (scope && options.routeTree)
+    registerPublicRouteDataOwner(
+      options.routeTree,
+      scope.hydrationOwner,
+      scope.privateRoots,
+    );
+  const context = preparePublicContextData(
+    options.context,
+    scope?.hydrationOwner,
+  );
+  if (
+    context !== undefined &&
+    (!context || typeof context !== 'object' || Array.isArray(context))
+  )
+    throw new DataProtocolError(
+      'The native Solid router context must be a public record',
+    );
+  const router = createRouter({ ...options, context });
+  if (scope) {
+    scope.attach(router);
+    routerScopes.set(router, scope);
+  }
+  return router;
+};
+
+export function ownApplicationRouteData(router: AnyRouter): void {
+  const scope = routerScopes.get(router);
+  if (scope) onCleanup(() => scope.dispose());
+  else assertManagedRouteData(router.options.routeTree);
+}
+
+/** A framing failure belongs to the exact native loader generation that read it. */
+export function createRouteCompletionScope(
+  privateRoots: readonly object[] = [],
+  session?: RequestSession,
+): RouteCompletionScope {
+  const records = new WeakMap<object, CompletionRecord>();
+  const pending = new Set<() => void>();
+  const hydration = new AbortController();
+  let router: AnyRouter | undefined;
+
+  function begin(
+    signal: AbortSignal,
+    cancel: () => void,
+  ): PublicDataGeneration {
+    if (!router)
+      throw new Error(
+        'Use createApplicationRouter to own progressive Solid route data',
+      );
+    const [failure, setFailure] = createSignal<{ reason: unknown }>();
+    const native = router;
+    let value: unknown;
+    let leases = 0;
+    let settled = false;
+    let failed = false;
+    const stop = () => {
+      if (!settled) {
+        pending.delete(stop);
+        if (value && typeof value === 'object')
+          native.clearCache({ filter: match => match.loaderData === value });
+        cancel();
+      }
+    };
+    const fail = (reason: unknown) => {
+      if (failed) return;
+      failed = true;
+      settled = true;
+      pending.delete(stop);
+      if (value && typeof value === 'object')
+        native.clearCache({ filter: match => match.loaderData === value });
+      setFailure({ reason });
+      cancel();
+    };
+    const record: CompletionRecord = {
+      failure,
+      acquire() {
+        leases++;
+        let released = false;
+        return () => {
+          if (released) return;
+          released = true;
+          if (
+            --leases === 0 &&
+            !native.state.matches.some(match => match.loaderData === value)
+          )
+            stop();
+        };
+      },
+    };
+    return {
+      owner: { signal, fail },
+      publish(publicValue, completion) {
+        value = publicValue;
+        const deferred =
+          value && typeof value === 'object'
+            ? Reflect.ownKeys(value).flatMap(key => {
+                const entry = Object.getOwnPropertyDescriptor(value, key);
+                return entry && !entry.get && entry.value instanceof Promise
+                  ? [entry.value]
+                  : [];
+              })
+            : [];
+        if (!completion && deferred.length === 0) return;
+        if (value && typeof value === 'object') {
+          records.set(value, record);
+          pending.add(stop);
+        } else if (completion) {
+          throw new DataProtocolError(
+            'Progressive route data requires its native value object',
+          );
+        }
+        if (completion)
+          void completion.then(() => {
+            settled = true;
+            pending.delete(stop);
+          }, fail);
+        else
+          void Promise.allSettled(deferred).then(() => {
+            settled = true;
+            pending.delete(stop);
+          });
+      },
+    };
+  }
+
+  return {
+    privateRoots,
+    hydrationOwner: session ?? {
+      signal: hydration.signal,
+      fail: error => hydration.abort(error),
+    },
+    attach(native) {
+      if (router && router !== native)
+        throw new Error('A Solid data scope already owns its native router');
+      router = native;
+    },
+    begin,
+    component(component) {
+      return function RouteCompletionView(): JSX.Element {
+        // Select the registry record before native structural sharing can reuse
+        // a deeply equal previous loaderData object from another generation.
+        const record = useMatch({
+          strict: false,
+          select: match =>
+            match.loaderData && typeof match.loaderData === 'object'
+              ? records.get(match.loaderData)
+              : undefined,
+        });
+        createEffect(record, current => current?.acquire());
+        const ready = createMemo(() => {
+          const failure = record()?.failure();
+          if (failure) throw failure.reason;
+          return component;
+        });
+        return <Dynamic component={ready()} />;
+      };
+    },
+    dispose() {
+      hydration.abort();
+      for (const stop of pending) stop();
+      pending.clear();
+    },
+  };
+}

package/src/route-data-error.ts

@@ -0,0 +1,175 @@
+import {
+  assertPublicData,
+  DataProtocolError,
+} from '@modern-js/renderer-core/data';
+import { RouteDataError } from '@modern-js/renderer-core/router';
+
+export interface RouteDataErrorSnapshot {
+  kind: 'ultramodern-route-data-error';
+  version: 1;
+  routeId: string;
+  status: number;
+  data: unknown;
+  error: { name: string; message: string; stack?: string };
+}
+
+function invalid(message: string): never {
+  throw new DataProtocolError(message);
+}
+
+function publicFields(
+  value: object,
+  required: readonly string[],
+  optional: readonly string[] = [],
+  allowStackAccessor = false,
+): Record<string, PropertyDescriptor> {
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  for (const key of Reflect.ownKeys(descriptors)) {
+    if (
+      typeof key !== 'string' ||
+      (!required.includes(key) && !optional.includes(key))
+    ) {
+      invalid('Route data errors must not contain undeclared fields');
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
+    if (descriptor.get || descriptor.set) {
+      // Native Node errors can own a lazy stack getter. Never evaluate it.
+      if (allowStackAccessor && key === 'stack') continue;
+      invalid('Route data errors must not contain accessors');
+    }
+  }
+  for (const key of required) {
+    if (!Object.hasOwn(descriptors, key)) {
+      invalid('Route data errors are missing a declared field');
+    }
+  }
+  return descriptors;
+}
+
+function validateFields(
+  routeId: unknown,
+  status: unknown,
+  name: unknown,
+  message: unknown,
+): { routeId: string; status: number; name: string; message: string } {
+  if (typeof routeId !== 'string' || routeId.length === 0) {
+    invalid('Route data errors require a nonempty route identifier');
+  }
+  if (
+    typeof status !== 'number' ||
+    !Number.isInteger(status) ||
+    status < 200 ||
+    status > 599
+  ) {
+    invalid('Route data errors require a valid public HTTP status');
+  }
+  if (typeof name !== 'string' || typeof message !== 'string') {
+    invalid('Route data errors require public name and message strings');
+  }
+  return { routeId, status, name, message };
+}
+
+/** Preserve the known public route error without serializing its Error object. */
+export function projectRouteDataError(
+  error: unknown,
+  production = true,
+): RouteDataErrorSnapshot {
+  if (
+    !error ||
+    typeof error !== 'object' ||
+    Object.getPrototypeOf(error) !== RouteDataError.prototype
+  ) {
+    invalid('Only the exact RouteDataError class has a route error projection');
+  }
+  const descriptors = publicFields(
+    error,
+    ['routeId', 'status', 'data', 'name', 'message'],
+    ['stack'],
+    true,
+  );
+  const routeId: unknown = descriptors.routeId!.value;
+  const status: unknown = descriptors.status!.value;
+  const name: unknown = descriptors.name!.value;
+  const message: unknown = descriptors.message!.value;
+  const fields = validateFields(routeId, status, name, message);
+  const snapshot: RouteDataErrorSnapshot = {
+    kind: 'ultramodern-route-data-error',
+    version: 1,
+    routeId: fields.routeId,
+    status: fields.status,
+    data: descriptors.data!.value,
+    error: {
+      name: fields.name,
+      message: fields.message,
+    },
+  };
+  const stack = descriptors.stack;
+  if (stack && !stack.get && !stack.set) {
+    if (typeof stack.value !== 'string') {
+      invalid('Route data error stacks must be strings');
+    }
+    if (!production) snapshot.error.stack = stack.value;
+  }
+  assertPublicData(snapshot);
+  return snapshot;
+}
+
+function plainRecord(value: unknown): object {
+  if (!value || typeof value !== 'object') {
+    invalid('Malformed route data error snapshot');
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    invalid('Route data error snapshots require plain records');
+  }
+  return value;
+}
+
+/** Reconstruct only the validated route error tag produced by this adapter. */
+export function restoreRouteDataError(snapshot: unknown): RouteDataError {
+  const descriptors = publicFields(plainRecord(snapshot), [
+    'kind',
+    'version',
+    'routeId',
+    'status',
+    'data',
+    'error',
+  ]);
+  if (
+    descriptors.kind!.value !== 'ultramodern-route-data-error' ||
+    descriptors.version!.value !== 1
+  ) {
+    invalid('Unsupported route data error snapshot');
+  }
+  const error = publicFields(
+    plainRecord(descriptors.error!.value),
+    ['name', 'message'],
+    ['stack'],
+  );
+  const routeId: unknown = descriptors.routeId!.value;
+  const fields = validateFields(
+    routeId,
+    descriptors.status!.value,
+    error.name!.value,
+    error.message!.value,
+  );
+  if (error.stack && typeof error.stack.value !== 'string') {
+    invalid('Route data error stacks must be strings');
+  }
+  assertPublicData(snapshot);
+  const restored = new RouteDataError(fields.routeId, {
+    kind: 'error',
+    status: fields.status,
+    data: descriptors.data!.value,
+    error: { name: fields.name, message: fields.message },
+    thrown: true,
+  });
+  if (error.stack) {
+    Object.defineProperty(restored, 'stack', {
+      value: error.stack.value,
+      configurable: true,
+      writable: true,
+    });
+  }
+  return restored;
+}

package/src/router-binding/Asset.tsx

@@ -0,0 +1,283 @@
+import type { JSX } from '@solidjs/web';
+import type { RouterManagedTag } from '@tanstack/router-core';
+import { isServer } from '@tanstack/router-core/isServer';
+import { createEffect, onCleanup, onSettled } from 'solid-js';
+import { useRouter } from './useRouter';
+
+const INLINE_CSS_HYDRATION_ATTR = 'data-tsr-inline-css';
+
+export function Asset(asset: RouterManagedTag): JSX.Element | null {
+  const { tag, attrs, children } = asset;
+
+  switch (tag) {
+    case 'title':
+      return <Title attrs={attrs} children={children} />;
+    case 'meta':
+      return <HeadElement tag="meta" attrs={attrs} />;
+    case 'link':
+      return <HeadElement tag="link" attrs={attrs} />;
+    case 'style':
+      if (
+        asset.inlineCss &&
+        (process.env.TSS_INLINE_CSS_ENABLED === 'true' ||
+          (process.env.TSS_INLINE_CSS_ENABLED === undefined && isServer))
+      ) {
+        return <InlineCssStyle attrs={attrs}>{children}</InlineCssStyle>;
+      }
+
+      return <HeadElement tag="style" attrs={attrs} children={children} />;
+    case 'script':
+      return <Script attrs={attrs} children={children} />;
+    default:
+      return null;
+  }
+}
+
+// On the client, relocate a rendered head element into document.head so head
+// tags end up in the right place even when <HeadContent /> is rendered in
+// <body>. The *same* node that Solid rendered/hydrated is moved — never
+// recreated — so the server-rendered node stays claimed (its hydration id is
+// preserved) and stylesheets/scripts are not refetched or re-executed.
+//
+// When <HeadContent /> is placed in <head> (the SSR/hydration case), the node
+// is already in document.head, so this is a no-op and the element is left
+// exactly where Solid hydrated it.
+function useRelocateToHead(getEl: () => Node | undefined) {
+  onSettled(() => {
+    const el = getEl();
+    if (el && el.parentNode !== document.head) {
+      document.head.appendChild(el);
+    }
+  });
+
+  onCleanup(() => {
+    const el = getEl();
+    if (el?.parentNode) {
+      el.parentNode.removeChild(el);
+    }
+  });
+}
+
+function InlineCssStyle({
+  attrs,
+  children,
+}: {
+  attrs?: Record<string, any>;
+  children?: RouterManagedTag['children'];
+}) {
+  const isInlineCssPlaceholder = children === undefined;
+  const html = isInlineCssPlaceholder
+    ? typeof document === 'undefined'
+      ? ''
+      : (document.querySelector<HTMLStyleElement>(
+          `style[${INLINE_CSS_HYDRATION_ATTR}]`,
+        )?.textContent ?? '')
+    : (children ?? '');
+
+  return (
+    <HeadElement
+      tag="style"
+      attrs={{ ...attrs, [INLINE_CSS_HYDRATION_ATTR]: '' }}
+      children={html}
+    />
+  );
+}
+
+function HeadElement(props: {
+  tag: 'meta' | 'link' | 'style';
+  attrs?: Record<string, any>;
+  children?: unknown;
+}): JSX.Element | null {
+  // Each branch must live in its own `case` block so the Solid compiler emits
+  // exactly ONE getNextElement() per invocation. Sequential `if ... return`
+  // statements compile to multiple getNextElement() calls that all execute,
+  // desyncing the hydration key counter (causing "expected <style>" mismatches
+  // and unclaimed nodes).
+  //
+  // We capture the element via the JSX return value (a real DOM node in Solid)
+  // rather than a `ref` attribute: a `ref` compiles to a _$ref() call that
+  // interferes with attribute spreading on hydration-claimed nodes (wiping the
+  // SSR attributes).
+  let element: Element;
+  switch (props.tag) {
+    case 'style': {
+      const attrs = {
+        ...props.attrs,
+        innerHTML:
+          typeof props.children === 'string' ? props.children : undefined,
+      };
+      element = (<style {...attrs} />) as unknown as Element;
+      break;
+    }
+    case 'meta':
+      element = (<meta {...props.attrs} />) as unknown as Element;
+      break;
+    default:
+      element = (<link {...props.attrs} />) as unknown as Element;
+  }
+
+  // Move the rendered/hydrated element into <head> when <HeadContent /> is
+  // placed in <body>. No-op when already in <head>. Called unconditionally so
+  // server and client register the same primitives (see Title).
+  useRelocateToHead(() => element);
+
+  return element as unknown as JSX.Element;
+}
+
+function Title(props: {
+  attrs?: Record<string, any>;
+  children?: unknown;
+}): JSX.Element | null {
+  let el: HTMLTitleElement | undefined;
+
+  // IMPORTANT: call these hooks UNCONDITIONALLY (do not guard with isServer).
+  // Solid's hydration relies on the component body registering the same
+  // reactive primitives in the same order on the server and the client. An
+  // `if (!isServer)` guard would skip them on the server but run them on the
+  // client, desyncing the hydration owner tree and causing the server <title>
+  // to be left unclaimed (and a duplicate appended). These hooks are no-ops
+  // during SSR anyway.
+
+  // Move the rendered/hydrated <title> into <head> when <HeadContent /> is
+  // placed in <body>. No-op when already in <head>.
+  useRelocateToHead(() => el);
+
+  // Keep document.title in sync during client-side navigation.
+  createEffect(
+    () => props.children,
+    titleText => {
+      document.title = typeof titleText === 'string' ? titleText : '';
+    },
+  );
+
+  return (
+    <title ref={e => (el = e)} {...props.attrs}>
+      {props.children as string}
+    </title>
+  );
+}
+
+function Script(props: {
+  attrs?: Record<string, any>;
+  children?: unknown;
+}): JSX.Element | null {
+  const router = useRouter();
+  const attrs = props.attrs;
+  const children = props.children;
+
+  const dataScript =
+    typeof attrs?.type === 'string' &&
+    attrs.type !== '' &&
+    attrs.type !== 'text/javascript' &&
+    attrs.type !== 'module';
+
+  // --- Server rendering ---
+  if (isServer ?? router.isServer) {
+    if (attrs?.src) {
+      return <script {...attrs} />;
+    }
+
+    if (typeof children === 'string') {
+      return <script {...attrs} innerHTML={children} />;
+    }
+
+    return null;
+  }
+
+  // --- Client rendering ---
+
+  // Data scripts (e.g. application/ld+json) are rendered in the tree;
+  // they don't need to execute.
+  if (dataScript && typeof children === 'string') {
+    return <script {...attrs} innerHTML={children} />;
+  }
+
+  // For executable scripts, use imperative DOM injection so the browser
+  // actually executes them during client-side navigation. The injection is
+  // idempotent (it checks for an already-present matching script), so the
+  // server-rendered script node is reused rather than duplicated.
+  createEffect(
+    () => ({ attrs, children, dataScript }) as const,
+    ({ attrs, children, dataScript }) => {
+      if (dataScript) return;
+
+      let script: HTMLScriptElement | undefined;
+
+      if (attrs?.src) {
+        const normSrc = (() => {
+          try {
+            const base = document.baseURI || window.location.href;
+            return new URL(attrs.src, base).href;
+          } catch {
+            return attrs.src;
+          }
+        })();
+        const existingScript = Array.from(
+          document.querySelectorAll('script[src]'),
+        ).find(el => (el as HTMLScriptElement).src === normSrc);
+
+        if (existingScript) {
+          return;
+        }
+
+        script = document.createElement('script');
+
+        for (const [key, value] of Object.entries(attrs)) {
+          if (value !== undefined && value !== false) {
+            script.setAttribute(
+              key,
+              typeof value === 'boolean' ? '' : String(value),
+            );
+          }
+        }
+
+        document.head.appendChild(script);
+      } else if (typeof children === 'string') {
+        const typeAttr =
+          typeof attrs?.type === 'string' ? attrs.type : 'text/javascript';
+        const nonceAttr =
+          typeof attrs?.nonce === 'string' ? attrs.nonce : undefined;
+        const existingScript = Array.from(
+          document.querySelectorAll('script:not([src])'),
+        ).find(el => {
+          if (!(el instanceof HTMLScriptElement)) return false;
+          const sType = el.getAttribute('type') ?? 'text/javascript';
+          const sNonce = el.getAttribute('nonce') ?? undefined;
+          return (
+            el.textContent === children &&
+            sType === typeAttr &&
+            sNonce === nonceAttr
+          );
+        });
+
+        if (existingScript) {
+          return;
+        }
+
+        script = document.createElement('script');
+        script.textContent = children;
+
+        if (attrs) {
+          for (const [key, value] of Object.entries(attrs)) {
+            if (value !== undefined && value !== false) {
+              script.setAttribute(
+                key,
+                typeof value === 'boolean' ? '' : String(value),
+              );
+            }
+          }
+        }
+
+        document.head.appendChild(script);
+      }
+
+      return () => {
+        if (script?.parentNode) {
+          script.parentNode.removeChild(script);
+        }
+      };
+    },
+  );
+
+  return null;
+}