akanjs 3.0.2 → 3.1.0-rc.0

package/client/router.ts

@@ -1,8 +1,15 @@
 import { getEnv } from "akanjs/base";
 import { getBasePathFromPathname, Logger, parseAkanI18nEnv, parseBasePaths } from "akanjs/common";
+import { csrLocation } from "./csrLocation";
 
 export interface RouteOptions {
   scrollToTop?: boolean;
+  /**
+   * Writes the URL and the store's path and search params without asking the server for the page, as for `?peek=`;
+   * honoured only when the path stays the same. A server component reading `.search()` sees it at the next full
+   * navigation.
+   */
+  shallow?: boolean;
 }
 export interface RouteManifest {
   routes: string[];
@@ -160,6 +167,8 @@ class Router {
   #indexPath = "/";
   #navigation: Promise<void> = Promise.resolve();
   #historyIdx = 0;
+  
+  #historyWrittenByNavigation = false;
   #redirects = 0;
   #instance: RouterInstance = {
     push: (href: string) => {
@@ -197,6 +206,7 @@ class Router {
     Logger.verbose("Router initialized");
   }
   #initSsrClientRouter(options: SsrClientRouterOption) {
+    this.#historyWrittenByNavigation = true;
     const navigate = (method: "push" | "replace") => (href: string, routeOptions?: RouteOptions) => {
       const pathInfo = this.#getPathInfo(href);
       const navigationPathInfo = this.#getNavigationPathInfo(href);
@@ -207,10 +217,8 @@ class Router {
       push: navigate("push"),
       replace: navigate("replace"),
       back: () => {
-        const router = options.router;
-        const pathInfo = this.#getPathInfo(document.referrer);
-        this.#postPathChange(pathInfo);
-        router.back();
+        this.#postPathAfterBack();
+        options.router.back();
       },
       refresh: () => {
         const router = options.router;
@@ -236,8 +244,7 @@ class Router {
         }, 0);
       },
       back: (routeOptions) => {
-        const { path, pathname, hash } = this.#getPathInfo(document.referrer);
-        this.#postPathChange({ path, pathname, hash });
+        this.#postPathAfterBack();
         options.router.back(routeOptions);
       },
       refresh: () => {
@@ -255,14 +262,10 @@ class Router {
     if (getEnv().side === "server") return;
     const history = globalThis.window?.history;
     if (!history?.replaceState) return;
-    const state = (history.state ?? {}) as Record<string, unknown>;
+    const state = (csrLocation.state ?? {}) as Record<string, unknown>;
     const akanState = (state.__akanRouter ?? {}) as { idx?: number };
     this.#historyIdx = Number.isInteger(akanState.idx) ? (akanState.idx as number) : this.#historyIdx;
-    history.replaceState(
-      { ...state, __akanRouter: { ...akanState, idx: this.#historyIdx } },
-      "",
-      globalThis.window.location.href,
-    );
+    csrLocation.replace({ ...state, __akanRouter: { ...akanState, idx: this.#historyIdx } });
     if (!globalThis.window.addEventListener) return;
     globalThis.window.addEventListener("popstate", (event) => {
       const nextState = ((event.state as Record<string, unknown> | null)?.__akanRouter ?? {}) as { idx?: number };
@@ -271,13 +274,14 @@ class Router {
   }
 
   #rememberHistoryState(kind: "push" | "replace") {
-    if (getEnv().side === "server") return;
+    if (getEnv().side === "server" || this.#historyWrittenByNavigation) return;
     const history = globalThis.window?.history;
     if (!history) return;
     if (kind === "push") this.#historyIdx += 1;
-    const state = (history.state ?? {}) as Record<string, unknown>;
+    if (!history.replaceState) return;
+    const state = (csrLocation.state ?? {}) as Record<string, unknown>;
     const nextState = { ...state, __akanRouter: { ...((state.__akanRouter ?? {}) as object), idx: this.#historyIdx } };
-    if (history.replaceState) history.replaceState(nextState, "", globalThis.window.location.href);
+    csrLocation.replace(nextState);
   }
 
   #getPathInfo(href: string, prefix = this.#prefix) {
@@ -287,7 +291,7 @@ class Router {
     return this.#getPathInfo(href, shouldExposeBasePath() ? this.#prefix : "");
   }
   #withCsrRuntimeSearchParams(href: string) {
-    const currentSearch = new URLSearchParams(window.location.search);
+    const currentSearch = new URLSearchParams(csrLocation.search);
     if (currentSearch.get("csr") !== "true") return href;
 
     const [hrefWithoutHash, hash = ""] = href.split("#");
@@ -304,8 +308,18 @@ class Router {
   #getVisiblePathInfo(href: string, lang = this.#lang) {
     return getPathInfo(href, lang, shouldExposeBasePath() ? this.#prefix : "");
   }
+  
+  #postPathAfterBack() {
+    window.addEventListener(
+      "popstate",
+      () => this.#postPathChange(this.#getPathInfo(`${location.pathname}${location.search}${location.hash}`)),
+      { once: true },
+    );
+  }
   #postPathChange({ path, pathname, hash }: { path: string; pathname: string; hash: string }) {
     Logger.info(`pathChange-start:${path}${hash ? `#${hash}` : ""}`);
+    
+    if (globalThis.__AKAN_EMBED__) return;
     window.parent.postMessage({ type: "pathChange", path, pathname, hash }, "*");
   }
   #postDevSyncNavigation(kind: "push" | "replace", href: string) {
@@ -386,7 +400,9 @@ class Router {
   }
   canGoBack() {
     if (getEnv().side === "server") return false;
-    return this.#historyIdx > 0;
+    const state = globalThis.window?.history?.state as { __akanRouter?: { idx?: unknown } } | null | undefined;
+    const idx = state?.__akanRouter?.idx;
+    return (Number.isInteger(idx) ? (idx as number) : this.#historyIdx) > 0;
   }
   backOrFallback(fallbackHref = this.#indexPath, routeOptions?: RouteOptions) {
     if (this.canGoBack()) {
@@ -446,11 +462,8 @@ class Router {
   setLang(lang: string) {
     if (getEnv().side === "server") throw new Error("setLang is only available in client side");
     this.#checkInitialized();
-    const currentLang = getLocaleFromPathname(window.location.pathname) ?? this.#lang;
-    const { path, search, hash } = this.#getVisiblePathInfo(
-      `${window.location.pathname}${window.location.search ?? ""}${window.location.hash ?? ""}`,
-      currentLang,
-    );
+    const currentLang = getLocaleFromPathname(csrLocation.pathname) ?? this.#lang;
+    const { path, search, hash } = this.#getVisiblePathInfo(csrLocation.href, currentLang);
     this.#lang = lang;
     this.#instance.replace(`${path}${search ? `?${search}` : ""}${hash ? `#${hash}` : ""}`);
     return undefined as never;
@@ -459,7 +472,7 @@ class Router {
   routeOf(pathname: string) {
     return getPathInfo(pathname, this.#lang, this.#prefix).path;
   }
-  getPath(pathname = window.location.pathname) {
+  getPath(pathname = csrLocation.pathname) {
     if (getEnv().side === "server") throw new Error("getPath is only available in client side");
     return this.routeOf(pathname);
   }

package/client/rscNavigation.ts

@@ -3,7 +3,10 @@ declare global {
   var __AKAN_RSC_IS_FROM_CACHE__: (() => boolean) | undefined;
   var __AKAN_RSC_REFRESH__: ((options?: { buildId?: number }) => Promise<void>) | undefined;
   var __AKAN_RSC_NAVIGATE__:
-    | ((href: string, options?: { replace?: boolean; scrollToTop?: boolean }) => Promise<void>)
+    | ((
+        href: string,
+        options?: { replace?: boolean; scrollToTop?: boolean; shallow?: boolean; pop?: boolean },
+      ) => Promise<void>)
     | undefined;
   var __AKAN_DEV_SYNC_NAVIGATION__: ((href: string, kind: "push" | "replace" | "back" | "pop") => void) | undefined;
   var __AKAN_DEV_SYNC_NAVIGATION_APPLYING__: boolean | undefined;
@@ -17,7 +20,10 @@ export const clearRscNavigationCache = () => {
 /** True when the page on screen was replayed from the RSC navigation cache, so its hydrated data may be stale. */
 export const isRscNavigationFromCache = () => globalThis.__AKAN_RSC_IS_FROM_CACHE__?.() ?? false;
 
-export const navigateRsc = (href: string, options?: { replace?: boolean; scrollToTop?: boolean }) => {
+export const navigateRsc = (
+  href: string,
+  options?: { replace?: boolean; scrollToTop?: boolean; shallow?: boolean },
+) => {
   return globalThis.__AKAN_RSC_NAVIGATE__?.(href, options);
 };
 

package/client/viewportMeta.ts

@@ -0,0 +1,60 @@
+import type { RouteViewport } from "./csrTypes";
+
+export interface ThemeColorTag {
+  content: string;
+  media?: string;
+}
+
+/** Turns a root layout's `.viewport()` into the `viewport` and `theme-color` meta tags every document shell writes. */
+export class ViewportMeta {
+  static content(viewport: RouteViewport | undefined, { native = false }: { native?: boolean } = {}): string {
+    const parts = ["width=device-width", "initial-scale=1"];
+    if (viewport?.fitCover ?? native) parts.push("viewport-fit=cover");
+    if (viewport?.interactiveWidget) parts.push(`interactive-widget=${viewport.interactiveWidget}`);
+    return parts.join(", ");
+  }
+
+  /** The request's theme when it is known; otherwise `light`/`dark` follow the OS until the client names the theme. */
+  static themeColors(viewport: RouteViewport | undefined, theme?: string): ThemeColorTag[] {
+    const themeColor = viewport?.themeColor;
+    if (!themeColor) return [];
+    if (typeof themeColor === "string") return [{ content: themeColor }];
+    const named = theme ? themeColor[theme] : undefined;
+    if (named) return [{ content: named }];
+    const schemes = (["light", "dark"] as const)
+      .filter((scheme) => themeColor[scheme])
+      .map((scheme) => ({ content: themeColor[scheme] ?? "", media: `(prefers-color-scheme: ${scheme})` }));
+    if (schemes.length) return schemes;
+    const first = Object.values(themeColor)[0];
+    return first ? [{ content: first }] : [];
+  }
+
+  static applyContent(viewport: RouteViewport | undefined, { native = false }: { native?: boolean } = {}) {
+    const meta = ViewportMeta.#ensureMeta("viewport");
+    const content = ViewportMeta.content(viewport, { native });
+    if (meta.content !== content) meta.content = content;
+  }
+
+  static applyThemeColor(viewport: RouteViewport | undefined, theme?: string) {
+    const tags = ViewportMeta.themeColors(viewport, theme);
+    if (!tags.length) return;
+    const existing = [...document.head.querySelectorAll<HTMLMetaElement>('meta[name="theme-color"]')];
+    const kept = existing.slice(0, tags.length);
+    for (const meta of existing.slice(tags.length)) meta.remove();
+    tags.forEach((tag, idx) => {
+      const meta = kept[idx] ?? ViewportMeta.#ensureMeta("theme-color", true);
+      meta.content = tag.content;
+      if (tag.media) meta.media = tag.media;
+      else meta.removeAttribute("media");
+    });
+  }
+
+  static #ensureMeta(name: string, fresh = false): HTMLMetaElement {
+    const found = fresh ? null : document.head.querySelector<HTMLMetaElement>(`meta[name="${name}"]`);
+    if (found) return found;
+    const meta = document.createElement("meta");
+    meta.name = name;
+    document.head.appendChild(meta);
+    return meta;
+  }
+}

package/client/webManifest.ts

@@ -0,0 +1,18 @@
+/** Where an SSR document links its root layout's `.manifest()`; the server answers it from that layout. */
+export const webManifestHref = (basePath?: string | null) =>
+  basePath ? `/${basePath}/manifest.webmanifest` : "/manifest.webmanifest";
+
+const camelToSnake = (key: string) => key.replace(/[A-Z]/g, (match) => `_${match.toLowerCase()}`);
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  Object.prototype.toString.call(value) === "[object Object]";
+
+/** A `.manifest()` object in the browser's own snake_case keys, at every depth. */
+export const toManifestJson = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(toManifestJson);
+  if (!isPlainObject(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([, entryValue]) => entryValue !== undefined)
+      .map(([key, entryValue]) => [camelToSnake(key), toManifestJson(entryValue)]),
+  );
+};

package/common/Logger.ts

@@ -347,10 +347,15 @@ export class Logger {
       }
     }
   }
+
+  static readonly #stderrHidden = envValue("AKAN_CHILD_STDERR_HIDDEN") === "1";
+  static #consoleStream(stream: "stdout" | "stderr") {
+    return stream === "stderr" && Logger.#stderrHidden ? "stdout" : stream;
+  }
   static #writeConsole(entry: LoggerSinkEntry) {
     if (!Logger.consoleOutput) return;
     if (typeof window === "undefined")
-      (process[entry.stream] as unknown as NodeJS.WriteStream | undefined)?.write(entry.message);
+      (process[Logger.#consoleStream(entry.stream)] as unknown as NodeJS.WriteStream | undefined)?.write(entry.message);
     else Logger.#writeBrowserConsole(entry.record, entry.message);
   }
 
@@ -400,7 +405,7 @@ export class Logger {
     Logger.#emit(Logger.#entry(Logger.#buildRecord(undefined, msg, "", null, stream, readLogContext()), msg));
     if (!Logger.consoleOutput) return;
     if (typeof window === "undefined" && method !== "console" && (process as unknown as NodeJS.Process | undefined))
-      process[stream].write(msg);
+      process[Logger.#consoleStream(stream)].write(msg);
     else console[outputStream === "error" ? "error" : Logger.#inNativeShell() ? "debug" : "log"](msg.trim());
   }
   static {

package/common/PipelineNames.ts

@@ -0,0 +1,31 @@
+import {
+  pipelineEnvNamePattern,
+  pipelineIdPattern,
+  pipelineReservedEnv,
+  pipelineSecretNamePattern,
+} from "./pipelinePlan";
+
+export class PipelineNames {
+  static isReservedEnv(name: string) {
+    return (pipelineReservedEnv as readonly string[]).includes(name) || name.startsWith("AKAN_CI_");
+  }
+
+  static idError(id: string): string | null {
+    if (pipelineIdPattern.test(id)) return null;
+    return `"${id}" is not an id: up to 64 lowercase letters, digits and "-", starting with a letter or digit`;
+  }
+
+  static secretNameError(name: string): string | null {
+    if (!pipelineSecretNamePattern.test(name))
+      return `"${name}" is not a secret name: up to 64 uppercase letters, digits and "_", starting with a letter`;
+    if (PipelineNames.isReservedEnv(name)) return `"${name}" is reserved for the executor`;
+    return null;
+  }
+
+  static envNameError(name: string): string | null {
+    if (!pipelineEnvNamePattern.test(name))
+      return `"${name}" is not an environment variable name: letters, digits and "_", not starting with a digit`;
+    if (PipelineNames.isReservedEnv(name)) return `"${name}" is reserved for the executor`;
+    return null;
+  }
+}

package/common/PipelinePattern.ts

@@ -0,0 +1,70 @@
+import { pipelinePlanLimits } from "./pipelinePlan";
+
+/**
+ * The one glob dialect of `when`, shared by the planner (`branch`, `app`) and the executor (`changed`) so both decide
+ * alike. `*` is any run without `/`, `**` any run including `/` (and with its `/` also no segment at all), `?` one
+ * character but `/`; everything else is literal and case-sensitive. A leading `!` excludes.
+ */
+export class PipelinePattern {
+  static readonly #compiled = new Map<string, RegExp>();
+
+  /** True when some positive pattern matches (or none is given) and no `!` pattern does. */
+  static matches(pattern: string | readonly string[], value: string) {
+    const patterns = PipelinePattern.#list(pattern);
+    const positives = patterns.filter((glob) => !glob.startsWith("!"));
+    const negatives = patterns.filter((glob) => glob.startsWith("!")).map((glob) => glob.slice(1));
+    const included = !positives.length || positives.some((glob) => PipelinePattern.#regex(glob).test(value));
+    return included && !negatives.some((glob) => PipelinePattern.#regex(glob).test(value));
+  }
+
+  /** `changed`: true when at least one of `values` matches. */
+  static matchesAny(pattern: string | readonly string[], values: readonly string[]) {
+    return values.some((value) => PipelinePattern.matches(pattern, value));
+  }
+
+  /** Braces and character classes are refused rather than given a meaning, so no implementation can read them apart. */
+  static validate(pattern: string | readonly string[]): string | null {
+    const patterns = PipelinePattern.#list(pattern);
+    if (!patterns.length) return "a pattern list may not be empty";
+    for (const glob of patterns) {
+      const body = glob.startsWith("!") ? glob.slice(1) : glob;
+      if (!body) return `"${glob}" matches nothing`;
+      if (body.startsWith("!")) return `"${glob}" negates twice`;
+      if (glob.length > pipelinePlanLimits.patternChars)
+        return `"${glob.slice(0, 40)}…" is longer than ${pipelinePlanLimits.patternChars} characters`;
+      if (/[{}[\]\\]/.test(body))
+        return `"${glob}" uses braces, a character class or a backslash, which are not supported`;
+    }
+    return null;
+  }
+
+  static #list(pattern: string | readonly string[]) {
+    return typeof pattern === "string" ? [pattern] : [...pattern];
+  }
+
+  static #regex(glob: string) {
+    const cached = PipelinePattern.#compiled.get(glob);
+    if (cached) return cached;
+    let source = "";
+    let idx = 0;
+    while (idx < glob.length) {
+      if (glob.startsWith("**/", idx)) {
+        source += "(?:.*/)?";
+        idx += 3;
+      } else if (glob.startsWith("/**", idx) && idx + 3 === glob.length) {
+        source += "(?:/.*)?";
+        idx += 3;
+      } else if (glob.startsWith("**", idx)) {
+        source += ".*";
+        idx += 2;
+      } else {
+        const char = glob.charAt(idx);
+        source += char === "*" ? "[^/]*" : char === "?" ? "[^/]" : char.replace(/[.+^$|(){}[\]\\]/, "\\$&");
+        idx += 1;
+      }
+    }
+    const regex = new RegExp(`^${source}$`);
+    PipelinePattern.#compiled.set(glob, regex);
+    return regex;
+  }
+}