alepha 0.21.2 → 0.22.0

package/dist/react/i18n/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/react/i18n/providers/I18nProvider.ts","../../../src/react/i18n/primitives/$dictionary.ts","../../../src/react/i18n/hooks/useI18n.ts","../../../src/react/i18n/components/Localize.tsx","../../../src/react/i18n/index.ts"],"sourcesContent":["import { $hook, $inject, Alepha, TypeBoxError, TypeProvider, t } from \"alepha\";\nimport { type DateTime, DateTimeProvider } from \"alepha/datetime\";\nimport { $logger } from \"alepha/logger\";\nimport { $cookie } from \"alepha/server/cookies\";\nimport type { ServiceDictionary } from \"../hooks/useI18n.ts\";\n\nexport class I18nProvider<\n  S extends object,\n  K extends keyof ServiceDictionary<S>,\n> {\n  protected log = $logger();\n  protected alepha = $inject(Alepha);\n  protected dateTimeProvider = $inject(DateTimeProvider);\n\n  protected cookie = $cookie({\n    name: \"lang\",\n    schema: t.text(),\n    ttl: [1, \"year\"],\n  });\n\n  public readonly registry: Array<{\n    target: string;\n    name: string;\n    lang: string;\n    loader: () => Promise<Record<string, string>>;\n    translations: Record<string, string>;\n  }> = [];\n\n  options = {\n    fallbackLang: \"en\",\n  };\n\n  public dateFormat: { format: (value: Date) => string } =\n    new Intl.DateTimeFormat(this.lang);\n\n  public numberFormat: { format: (value: number) => string } =\n    new Intl.NumberFormat(this.lang);\n\n  public get languages() {\n    const languages = new Set<string>();\n\n    for (const item of this.registry) {\n      languages.add(item.lang);\n    }\n\n    return Array.from(languages);\n  }\n\n  constructor() {\n    this.refreshLocale();\n  }\n\n  protected readonly onRender = $hook({\n    on: \"server:onRequest\",\n    priority: \"last\",\n    handler: async ({ request }) => {\n      this.alepha.store.set(\"alepha.react.i18n.lang\", this.cookie.get(request));\n    },\n  });\n\n  protected readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      if (this.alepha.isBrowser()) {\n        // get cookie lang\n        const cookieLang = this.cookie.get();\n        if (cookieLang) {\n          this.alepha.store.set(\"alepha.react.i18n.lang\", cookieLang);\n        }\n\n        for (const item of this.registry) {\n          if (item.lang === this.lang || item.lang === this.fallbackLang) {\n            this.log.trace(\"Loading language\", {\n              lang: item.lang,\n              name: item.name,\n              target: item.target,\n            });\n            item.translations = await item.loader();\n          }\n        }\n        return;\n      }\n\n      for (const item of this.registry) {\n        item.translations = await item.loader();\n      }\n    },\n  });\n\n  protected refreshLocale() {\n    this.numberFormat = new Intl.NumberFormat(this.lang);\n    this.dateFormat = new Intl.DateTimeFormat(this.lang);\n    this.dateTimeProvider.setLocale(this.lang);\n    TypeProvider.setLocale(this.lang);\n  }\n\n  public setLang = async (lang: string) => {\n    if (this.alepha.isBrowser()) {\n      for (const item of this.registry) {\n        if (lang === item.lang) {\n          if (Object.keys(item.translations).length > 0) {\n            continue; // already loaded\n          }\n          item.translations = await item.loader();\n        }\n      }\n      this.cookie.set(lang);\n    }\n\n    this.alepha.store.set(\"alepha.react.i18n.lang\", lang);\n    this.refreshLocale();\n  };\n\n  protected readonly mutate = $hook({\n    on: \"state:mutate\",\n    handler: async ({ key, value }) => {\n      if (key === \"alepha.react.i18n.lang\" && this.alepha.isBrowser()) {\n        let hasChanged = false;\n        for (const item of this.registry) {\n          if (value === item.lang) {\n            if (Object.keys(item.translations).length > 0) {\n              continue; // already loaded\n            }\n            item.translations = await item.loader();\n            hasChanged = true;\n          }\n        }\n\n        this.refreshLocale();\n\n        if (hasChanged) {\n          this.alepha.store.set(\"alepha.react.i18n.lang\", value);\n        }\n      }\n    },\n  });\n\n  public get fallbackLang(): string {\n    const configured = this.options.fallbackLang;\n    const hasDict = this.registry.some((item) => item.lang === configured);\n    if (hasDict) {\n      return configured;\n    }\n    return this.registry[0]?.lang ?? configured;\n  }\n\n  public get lang(): string {\n    return this.alepha.store.get(\"alepha.react.i18n.lang\") || this.fallbackLang;\n  }\n\n  public translate = (key: string, args: string[] = []) => {\n    for (const item of this.registry) {\n      if (item.lang === this.lang) {\n        if (item.translations[key]) {\n          return this.render(item.translations[key], args); // append lang for fallback\n        }\n      }\n    }\n\n    for (const item of this.registry) {\n      if (item.lang === this.fallbackLang) {\n        if (item.translations[key]) {\n          return this.render(item.translations[key], args); // append lang for fallback\n        }\n      }\n    }\n\n    return key; // fallback to the key itself if not found\n  };\n\n  public readonly l = (\n    value: I18nLocalizeType,\n    options: I18nLocalizeOptions = {},\n  ) => {\n    // Handle numbers\n    if (typeof value === \"number\" && !options.date) {\n      return new Intl.NumberFormat(this.lang, options.number).format(value);\n    }\n\n    // Handle dates\n    if (\n      value instanceof Date ||\n      this.dateTimeProvider.isDateTime(value) ||\n      (typeof value === \"string\" && options.date) ||\n      (typeof value === \"number\" && options.date)\n    ) {\n      // convert to DateTime with locale applied\n      let dt = this.dateTimeProvider.of(value);\n\n      // apply timezone if specified\n      if (options.timezone) {\n        dt = dt.tz(options.timezone);\n      }\n\n      // format using dayjs format string\n      if (typeof options.date === \"string\") {\n        if (options.date === \"fromNow\") {\n          return dt.locale(this.lang).fromNow();\n        }\n        return dt.locale(this.lang).format(options.date);\n      }\n\n      // format using Intl.DateTimeFormatOptions\n      if (options.date) {\n        return new Intl.DateTimeFormat(\n          this.lang,\n          options.timezone\n            ? { ...options.date, timeZone: options.timezone }\n            : options.date,\n        ).format(dt.toDate());\n      }\n\n      // default formatting with timezone\n      if (options.timezone) {\n        return new Intl.DateTimeFormat(this.lang, {\n          timeZone: options.timezone,\n        }).format(dt.toDate());\n      }\n\n      // default formatting\n      return new Intl.DateTimeFormat(this.lang).format(dt.toDate());\n    }\n\n    // handle TypeBox errors\n    if (value instanceof TypeBoxError) {\n      return TypeProvider.translateError(value, this.lang);\n    }\n\n    // return string values as-is\n    return value;\n  };\n\n  /**\n   * Look up `key` in the registered dictionaries. The `(string & {})` arm\n   * keeps autocomplete for the typed dictionary keys while allowing shared\n   * library components to pass arbitrary string keys (with a `default`\n   * fallback) without casting to `as never`.\n   */\n  public readonly tr = (\n    key: keyof ServiceDictionary<S>[K] | (string & {}),\n    options: {\n      args?: string[];\n      default?: string;\n    } = {},\n  ) => {\n    const translation = this.translate(key as string, options.args || []);\n    if (translation === (key as string) && options.default) {\n      return options.default;\n    }\n    return translation;\n  };\n\n  protected render(item: string, args: string[]): string {\n    let result = item;\n    for (let i = 0; i < args.length; i++) {\n      result = result.replace(`$${i + 1}`, args[i]);\n    }\n    return result;\n  }\n}\n\nexport type I18nLocalizeType = string | number | Date | DateTime | TypeBoxError;\n\nexport interface I18nLocalizeOptions {\n  /**\n   * Options for number formatting (when value is a number)\n   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat\n   */\n  number?: Intl.NumberFormatOptions;\n  /**\n   * Options for date formatting (when value is a Date or DateTime)\n   * Can be:\n   * - A dayjs format string (e.g., \"LLL\", \"YYYY-MM-DD\", \"dddd, MMMM D YYYY\")\n   * - \"fromNow\" for relative time (e.g., \"2 hours ago\")\n   * - Intl.DateTimeFormatOptions for native formatting\n   * @see https://day.js.org/docs/en/display/format\n   * @see https://day.js.org/docs/en/display/from-now\n   */\n  date?: string | \"fromNow\" | Intl.DateTimeFormatOptions;\n  /**\n   * Timezone to display dates in (when value is a Date or DateTime)\n   * Uses IANA timezone names (e.g., \"America/New_York\", \"Europe/Paris\", \"Asia/Tokyo\")\n   * @see https://day.js.org/docs/en/timezone/timezone\n   */\n  timezone?: string;\n}\n","import { $inject, type Async, createPrimitive, KIND, Primitive } from \"alepha\";\nimport { I18nProvider } from \"../providers/I18nProvider.ts\";\n\n/**\n * Register a dictionary entry for translations.\n *\n * It allows you to define a set of translations for a specific language.\n * Entry can be lazy-loaded, which is useful for large dictionaries or when translations are not needed immediately.\n *\n * @example\n * ```ts\n * import { $dictionary } from \"alepha/react/i18n\";\n *\n * const Example = () => {\n *   const { tr } = useI18n<App, \"en\">();\n *   return <div>{tr(\"hello\")}</div>; //\n * }\n *\n * class App {\n *\n *   en = $dictionary({\n *     // { default: { hello: \"Hey\" } }\n *     lazy: () => import(\"./translations/en.ts\"),\n *   });\n *\n *   home = $page({\n *     path: \"/\",\n *     component: Example,\n *   })\n * }\n *\n * run(App);\n * ```\n */\nexport const $dictionary = <T extends Record<string, string>>(\n  options: DictionaryPrimitiveOptions<T>,\n): DictionaryPrimitive<T> => {\n  return createPrimitive(DictionaryPrimitive<T>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface DictionaryPrimitiveOptions<T extends Record<string, string>> {\n  lang?: string;\n  name?: string;\n  lazy: () => Async<{ default: T }>;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class DictionaryPrimitive<\n  T extends Record<string, string>,\n> extends Primitive<DictionaryPrimitiveOptions<T>> {\n  protected provider = $inject(I18nProvider);\n  protected onInit() {\n    this.provider.registry.push({\n      target: this.config.service.name,\n      name: this.options.name ?? this.config.propertyKey,\n      lang: this.options.lang ?? this.config.propertyKey,\n      loader: async () => {\n        const mod = await this.options.lazy();\n        return mod.default;\n      },\n      translations: {},\n    });\n  }\n}\n\n$dictionary[KIND] = DictionaryPrimitive;\n","import { useInject, useStore } from \"alepha/react\";\nimport type { DictionaryPrimitive } from \"../primitives/$dictionary.ts\";\nimport { I18nProvider } from \"../providers/I18nProvider.ts\";\n\n/**\n * Hook to access the i18n service.\n */\nexport const useI18n = <\n  S extends object,\n  K extends keyof ServiceDictionary<S>,\n>(): I18nProvider<S, K> => {\n  useStore(\"alepha.react.i18n.lang\");\n  return useInject(I18nProvider<S, K>);\n};\n\nexport type ServiceDictionary<T extends object> = {\n  [K in keyof T]: T[K] extends DictionaryPrimitive<infer U> ? U : never;\n};\n","import type { TypeBoxError } from \"alepha\";\nimport type { DateTime } from \"alepha/datetime\";\nimport { useI18n } from \"../hooks/useI18n.ts\";\n\nexport interface LocalizeProps {\n  value: string | number | Date | DateTime | TypeBoxError;\n  /**\n   * Options for number formatting (when value is a number)\n   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat\n   */\n  number?: Intl.NumberFormatOptions;\n  /**\n   * Options for date formatting (when value is a Date or DateTime)\n   * Can be:\n   * - A dayjs format string (e.g., \"LLL\", \"YYYY-MM-DD\", \"dddd, MMMM D YYYY\")\n   * - \"fromNow\" for relative time (e.g., \"2 hours ago\")\n   * - Intl.DateTimeFormatOptions for native formatting\n   * @see https://day.js.org/docs/en/display/format\n   * @see https://day.js.org/docs/en/display/from-now\n   */\n  date?: string | \"fromNow\" | Intl.DateTimeFormatOptions;\n  /**\n   * Timezone to display dates in (when value is a Date or DateTime)\n   * Uses IANA timezone names (e.g., \"America/New_York\", \"Europe/Paris\", \"Asia/Tokyo\")\n   * @see https://day.js.org/docs/en/timezone/timezone\n   */\n  timezone?: string;\n}\n\nconst Localize = (props: LocalizeProps) => {\n  const i18n = useI18n();\n  return i18n.l(props.value, props);\n};\n\nexport default Localize;\n","import { $module } from \"alepha\";\nimport { $dictionary } from \"./primitives/$dictionary.ts\";\nimport { I18nProvider } from \"./providers/I18nProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport type { LocalizeProps } from \"./components/Localize.tsx\";\nexport { default as Localize } from \"./components/Localize.tsx\";\nexport * from \"./hooks/useI18n.ts\";\nexport * from \"./primitives/$dictionary.ts\";\nexport * from \"./providers/I18nProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha\" {\n  export interface State {\n    \"alepha.react.i18n.lang\"?: string;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Multi-language support.\n *\n * **Features:**\n * - Translation loading\n * - Locale detection\n * - Pluralization\n *\n * @module alepha.react.i18n\n */\nexport const AlephaReactI18n = $module({\n  name: \"alepha.react.i18n\",\n  primitives: [$dictionary],\n  services: [I18nProvider],\n});\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/react/i18n/providers/I18nProvider.ts","../../../src/react/i18n/primitives/$dictionary.ts","../../../src/react/i18n/hooks/useI18n.ts","../../../src/react/i18n/components/Localize.tsx","../../../src/react/i18n/components/Translate.tsx","../../../src/react/i18n/index.ts"],"sourcesContent":["import { $hook, $inject, Alepha, TypeBoxError, TypeProvider, t } from \"alepha\";\nimport { type DateTime, DateTimeProvider } from \"alepha/datetime\";\nimport { $logger } from \"alepha/logger\";\nimport { $cookie } from \"alepha/server/cookies\";\nimport type { ServiceDictionary } from \"../hooks/useI18n.ts\";\n\nexport class I18nProvider<\n  S extends object,\n  K extends keyof ServiceDictionary<S>,\n> {\n  protected log = $logger();\n  protected alepha = $inject(Alepha);\n  protected dateTimeProvider = $inject(DateTimeProvider);\n\n  protected cookie = $cookie({\n    name: \"lang\",\n    schema: t.text(),\n    ttl: [1, \"year\"],\n  });\n\n  public readonly registry: Array<{\n    target: string;\n    name: string;\n    lang: string;\n    loader: () => Promise<Record<string, string>>;\n    translations: Record<string, string>;\n  }> = [];\n\n  options = {\n    fallbackLang: \"en\",\n  };\n\n  public dateFormat: { format: (value: Date) => string } =\n    new Intl.DateTimeFormat(this.lang);\n\n  public numberFormat: { format: (value: number) => string } =\n    new Intl.NumberFormat(this.lang);\n\n  public get languages() {\n    const languages = new Set<string>();\n\n    for (const item of this.registry) {\n      languages.add(item.lang);\n    }\n\n    return Array.from(languages);\n  }\n\n  constructor() {\n    this.refreshLocale();\n  }\n\n  protected readonly onRender = $hook({\n    on: \"server:onRequest\",\n    priority: \"last\",\n    handler: async ({ request }) => {\n      this.alepha.store.set(\"alepha.react.i18n.lang\", this.cookie.get(request));\n    },\n  });\n\n  protected readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      if (this.alepha.isBrowser()) {\n        // get cookie lang\n        const cookieLang = this.cookie.get();\n        if (cookieLang) {\n          this.alepha.store.set(\"alepha.react.i18n.lang\", cookieLang);\n        }\n\n        for (const item of this.registry) {\n          if (item.lang === this.lang || item.lang === this.fallbackLang) {\n            this.log.trace(\"Loading language\", {\n              lang: item.lang,\n              name: item.name,\n              target: item.target,\n            });\n            item.translations = await item.loader();\n          }\n        }\n        return;\n      }\n\n      for (const item of this.registry) {\n        item.translations = await item.loader();\n      }\n    },\n  });\n\n  protected refreshLocale() {\n    this.numberFormat = new Intl.NumberFormat(this.lang);\n    this.dateFormat = new Intl.DateTimeFormat(this.lang);\n    this.dateTimeProvider.setLocale(this.lang);\n    TypeProvider.setLocale(this.lang);\n  }\n\n  public setLang = async (lang: string) => {\n    if (this.alepha.isBrowser()) {\n      for (const item of this.registry) {\n        if (lang === item.lang) {\n          if (Object.keys(item.translations).length > 0) {\n            continue; // already loaded\n          }\n          item.translations = await item.loader();\n        }\n      }\n      this.cookie.set(lang);\n    }\n\n    this.alepha.store.set(\"alepha.react.i18n.lang\", lang);\n    this.refreshLocale();\n  };\n\n  protected readonly mutate = $hook({\n    on: \"state:mutate\",\n    handler: async ({ key, value }) => {\n      if (key === \"alepha.react.i18n.lang\" && this.alepha.isBrowser()) {\n        let hasChanged = false;\n        for (const item of this.registry) {\n          if (value === item.lang) {\n            if (Object.keys(item.translations).length > 0) {\n              continue; // already loaded\n            }\n            item.translations = await item.loader();\n            hasChanged = true;\n          }\n        }\n\n        this.refreshLocale();\n\n        if (hasChanged) {\n          this.alepha.store.set(\"alepha.react.i18n.lang\", value);\n        }\n      }\n    },\n  });\n\n  public get fallbackLang(): string {\n    const configured = this.options.fallbackLang;\n    const hasDict = this.registry.some((item) => item.lang === configured);\n    if (hasDict) {\n      return configured;\n    }\n    return this.registry[0]?.lang ?? configured;\n  }\n\n  public get lang(): string {\n    return this.alepha.store.get(\"alepha.react.i18n.lang\") || this.fallbackLang;\n  }\n\n  public translate = (key: string, args: string[] = []) => {\n    for (const item of this.registry) {\n      if (item.lang === this.lang) {\n        if (item.translations[key]) {\n          return this.render(item.translations[key], args); // append lang for fallback\n        }\n      }\n    }\n\n    for (const item of this.registry) {\n      if (item.lang === this.fallbackLang) {\n        if (item.translations[key]) {\n          return this.render(item.translations[key], args); // append lang for fallback\n        }\n      }\n    }\n\n    return key; // fallback to the key itself if not found\n  };\n\n  public readonly l = (\n    value: I18nLocalizeType,\n    options: I18nLocalizeOptions = {},\n  ) => {\n    // Handle numbers\n    if (typeof value === \"number\" && !options.date) {\n      return new Intl.NumberFormat(this.lang, options.number).format(value);\n    }\n\n    // Handle dates\n    if (\n      value instanceof Date ||\n      this.dateTimeProvider.isDateTime(value) ||\n      (typeof value === \"string\" && options.date) ||\n      (typeof value === \"number\" && options.date)\n    ) {\n      // convert to DateTime with locale applied\n      let dt = this.dateTimeProvider.of(value);\n\n      // apply timezone if specified\n      if (options.timezone) {\n        dt = dt.tz(options.timezone);\n      }\n\n      // format using dayjs format string\n      if (typeof options.date === \"string\") {\n        if (options.date === \"fromNow\") {\n          return dt.locale(this.lang).fromNow();\n        }\n        return dt.locale(this.lang).format(options.date);\n      }\n\n      // format using Intl.DateTimeFormatOptions\n      if (options.date) {\n        return new Intl.DateTimeFormat(\n          this.lang,\n          options.timezone\n            ? { ...options.date, timeZone: options.timezone }\n            : options.date,\n        ).format(dt.toDate());\n      }\n\n      // default formatting with timezone\n      if (options.timezone) {\n        return new Intl.DateTimeFormat(this.lang, {\n          timeZone: options.timezone,\n        }).format(dt.toDate());\n      }\n\n      // default formatting\n      return new Intl.DateTimeFormat(this.lang).format(dt.toDate());\n    }\n\n    // handle TypeBox errors\n    if (value instanceof TypeBoxError) {\n      return TypeProvider.translateError(value, this.lang);\n    }\n\n    // return string values as-is\n    return value;\n  };\n\n  /**\n   * Look up `key` in the registered dictionaries. The `(string & {})` arm\n   * keeps autocomplete for the typed dictionary keys while allowing shared\n   * library components to pass arbitrary string keys (with a `default`\n   * fallback) without casting to `as never`.\n   */\n  public readonly tr = (\n    key: keyof ServiceDictionary<S>[K] | (string & {}),\n    options: {\n      args?: string[];\n      default?: string;\n    } = {},\n  ) => {\n    const translation = this.translate(key as string, options.args || []);\n    if (translation === (key as string) && options.default) {\n      return options.default;\n    }\n    return translation;\n  };\n\n  protected render(item: string, args: string[]): string {\n    let result = item;\n    for (let i = 0; i < args.length; i++) {\n      result = result.replace(`$${i + 1}`, args[i]);\n    }\n    return result;\n  }\n}\n\nexport type I18nLocalizeType = string | number | Date | DateTime | TypeBoxError;\n\nexport interface I18nLocalizeOptions {\n  /**\n   * Options for number formatting (when value is a number)\n   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat\n   */\n  number?: Intl.NumberFormatOptions;\n  /**\n   * Options for date formatting (when value is a Date or DateTime)\n   * Can be:\n   * - A dayjs format string (e.g., \"LLL\", \"YYYY-MM-DD\", \"dddd, MMMM D YYYY\")\n   * - \"fromNow\" for relative time (e.g., \"2 hours ago\")\n   * - Intl.DateTimeFormatOptions for native formatting\n   * @see https://day.js.org/docs/en/display/format\n   * @see https://day.js.org/docs/en/display/from-now\n   */\n  date?: string | \"fromNow\" | Intl.DateTimeFormatOptions;\n  /**\n   * Timezone to display dates in (when value is a Date or DateTime)\n   * Uses IANA timezone names (e.g., \"America/New_York\", \"Europe/Paris\", \"Asia/Tokyo\")\n   * @see https://day.js.org/docs/en/timezone/timezone\n   */\n  timezone?: string;\n}\n","import { $inject, type Async, createPrimitive, KIND, Primitive } from \"alepha\";\nimport { I18nProvider } from \"../providers/I18nProvider.ts\";\n\n/**\n * Register a dictionary entry for translations.\n *\n * It allows you to define a set of translations for a specific language.\n * Entry can be lazy-loaded, which is useful for large dictionaries or when translations are not needed immediately.\n *\n * @example\n * ```ts\n * import { $dictionary } from \"alepha/react/i18n\";\n *\n * const Example = () => {\n *   const { tr } = useI18n<App, \"en\">();\n *   return <div>{tr(\"hello\")}</div>; //\n * }\n *\n * class App {\n *\n *   en = $dictionary({\n *     // { default: { hello: \"Hey\" } }\n *     lazy: () => import(\"./translations/en.ts\"),\n *   });\n *\n *   home = $page({\n *     path: \"/\",\n *     component: Example,\n *   })\n * }\n *\n * run(App);\n * ```\n */\nexport const $dictionary = <T extends Record<string, string>>(\n  options: DictionaryPrimitiveOptions<T>,\n): DictionaryPrimitive<T> => {\n  return createPrimitive(DictionaryPrimitive<T>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface DictionaryPrimitiveOptions<T extends Record<string, string>> {\n  lang?: string;\n  name?: string;\n  lazy: () => Async<{ default: T }>;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class DictionaryPrimitive<\n  T extends Record<string, string>,\n> extends Primitive<DictionaryPrimitiveOptions<T>> {\n  protected provider = $inject(I18nProvider);\n  protected onInit() {\n    this.provider.registry.push({\n      target: this.config.service.name,\n      name: this.options.name ?? this.config.propertyKey,\n      lang: this.options.lang ?? this.config.propertyKey,\n      loader: async () => {\n        const mod = await this.options.lazy();\n        return mod.default;\n      },\n      translations: {},\n    });\n  }\n}\n\n$dictionary[KIND] = DictionaryPrimitive;\n","import { useInject, useStore } from \"alepha/react\";\nimport type { DictionaryPrimitive } from \"../primitives/$dictionary.ts\";\nimport { I18nProvider } from \"../providers/I18nProvider.ts\";\n\n/**\n * Hook to access the i18n service.\n */\nexport const useI18n = <\n  S extends object,\n  K extends keyof ServiceDictionary<S>,\n>(): I18nProvider<S, K> => {\n  useStore(\"alepha.react.i18n.lang\");\n  return useInject(I18nProvider<S, K>);\n};\n\nexport type ServiceDictionary<T extends object> = {\n  [K in keyof T]: T[K] extends DictionaryPrimitive<infer U> ? U : never;\n};\n","import type { TypeBoxError } from \"alepha\";\nimport type { DateTime } from \"alepha/datetime\";\nimport { useI18n } from \"../hooks/useI18n.ts\";\n\nexport interface LocalizeProps {\n  value: string | number | Date | DateTime | TypeBoxError;\n  /**\n   * Options for number formatting (when value is a number)\n   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat\n   */\n  number?: Intl.NumberFormatOptions;\n  /**\n   * Options for date formatting (when value is a Date or DateTime)\n   * Can be:\n   * - A dayjs format string (e.g., \"LLL\", \"YYYY-MM-DD\", \"dddd, MMMM D YYYY\")\n   * - \"fromNow\" for relative time (e.g., \"2 hours ago\")\n   * - Intl.DateTimeFormatOptions for native formatting\n   * @see https://day.js.org/docs/en/display/format\n   * @see https://day.js.org/docs/en/display/from-now\n   */\n  date?: string | \"fromNow\" | Intl.DateTimeFormatOptions;\n  /**\n   * Timezone to display dates in (when value is a Date or DateTime)\n   * Uses IANA timezone names (e.g., \"America/New_York\", \"Europe/Paris\", \"Asia/Tokyo\")\n   * @see https://day.js.org/docs/en/timezone/timezone\n   */\n  timezone?: string;\n}\n\nconst Localize = (props: LocalizeProps) => {\n  const i18n = useI18n();\n  return i18n.l(props.value, props);\n};\n\nexport default Localize;\n","import { useI18n } from \"../hooks/useI18n.ts\";\n\nexport interface TranslateProps {\n  /**\n   * Dictionary key to look up — the same key you would pass to `tr(...)`.\n   */\n  k: string;\n  /**\n   * Positional substitutions for `$1`, `$2`, … placeholders in the entry.\n   */\n  args?: string[];\n  /**\n   * Shown when the key is missing from every registered dictionary (otherwise\n   * the raw key is rendered, matching `tr`'s behaviour).\n   */\n  fallback?: string;\n}\n\n/**\n * Renders a translated dictionary entry as a reactive text node.\n *\n * `tr(...)` is a hook, so it can only be called inside a component body. Use\n * `<Translate>` wherever a *node* is expected instead — a prop, a `children`\n * slot, or route metadata such as a nav-shell `label`. Because it subscribes to\n * {@link useI18n} it re-renders on a language switch, unlike a string resolved\n * once at module/initialisation time.\n *\n * Sibling of {@link Localize}: `Localize` formats a value (number, date,\n * error); `Translate` looks up a key.\n *\n * @example\n * ```tsx\n * nav: { label: <Translate k=\"admin.nav.users\" /> }\n * <Translate k=\"cart.items\" args={[String(count)]} fallback=\"Items\" />\n * ```\n */\nexport const Translate = (props: TranslateProps) => {\n  const { tr } = useI18n();\n  return <>{tr(props.k, { args: props.args, default: props.fallback })}</>;\n};\n\n/**\n * Terse alias for {@link Translate} — handy in dense JSX such as nav labels.\n */\nexport const Tr = Translate;\n\nexport default Translate;\n","import { $module } from \"alepha\";\nimport { $dictionary } from \"./primitives/$dictionary.ts\";\nimport { I18nProvider } from \"./providers/I18nProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport type { LocalizeProps } from \"./components/Localize.tsx\";\nexport { default as Localize } from \"./components/Localize.tsx\";\nexport type { TranslateProps } from \"./components/Translate.tsx\";\nexport { default as Translate, Tr } from \"./components/Translate.tsx\";\nexport * from \"./hooks/useI18n.ts\";\nexport * from \"./primitives/$dictionary.ts\";\nexport * from \"./providers/I18nProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha\" {\n  export interface State {\n    \"alepha.react.i18n.lang\"?: string;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Multi-language support.\n *\n * **Features:**\n * - Translation loading\n * - Locale detection\n * - Pluralization\n *\n * @module alepha.react.i18n\n */\nexport const AlephaReactI18n = $module({\n  name: \"alepha.react.i18n\",\n  primitives: [$dictionary],\n  services: [I18nProvider],\n});\n"],"mappings":"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"}

package/dist/react/intro/index.d.ts

@@ -1,5 +1,4 @@
 import { ReactNode } from "react";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region ../../src/react/intro/components/GettingStarted.d.ts
 type GettingStartedStep = {
@@ -34,7 +33,7 @@ type GettingStartedProps = {
  */
 declare const GettingStarted: ({
   welcome
-}: GettingStartedProps) => _$react_jsx_runtime0.JSX.Element;
+}: GettingStartedProps) => import("react/jsx-runtime").JSX.Element;
 //#endregion
 export { GettingStarted, type GettingStartedSlide, type GettingStartedStep };
 //# sourceMappingURL=index.d.ts.map

package/dist/react/intro/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/react/intro/components/GettingStarted.tsx"],"mappings":";;;;KAMY,kBAAA;EACV,GAAA;EACA,IAAA,EAAM,SAAA;AAAA;AAAA,KAGI,mBAAA;EACV,IAAA;EACA,GAAA;EACA,MAAA;EACA,KAAA,GAAQ,kBAAA;EACR,KAAA;IAAU,KAAA;IAAe,IAAA;EAAA;AAAA;AAAA,KAGf,qBAAA;EACV,OAAA;EACA,UAAA;AAAA;AAAA,KAGU,mBAAA;EATV;;;;;;EAgBA,OAAA,GAAU,qBAAA;AAAA;;;;cAmCN,cAAA;EAAkB;AAAA,GAAa,mBAAA,KAAmB,oBAAA,CAAA,GAAA,CAAA,OAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/react/intro/components/GettingStarted.tsx"],"mappings":";;;KAMY,kBAAA;EACV,GAAA;EACA,IAAA,EAAM,SAAS;AAAA;AAAA,KAGL,mBAAA;EACV,IAAA;EACA,GAAA;EACA,MAAA;EACA,KAAA,GAAQ,kBAAkB;EAC1B,KAAA;IAAU,KAAA;IAAe,IAAA;EAAA;AAAA;AAAA,KAGf,qBAAA;EACV,OAAA;EACA,UAAU;AAAA;AAAA,KAGA,mBAAA;EATF;;;;;AACqB;EAe7B,OAAA,GAAU,qBAAqB;AAAA;;;AAVrB;cA6CN,cAAA;EAAkB;AAAA,GAAa,mBAAmB,iCAAA,GAAA,CAAA,OAAA"}

package/dist/react/intro/index.js

@@ -9,11 +9,11 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 * Returns undefined if admin routes are not configured.
 */
 const useAdminSlide = () => {
-	const { user, can } = useAuth();
+	const { user, has } = useAuth();
 	const router = useRouter();
 	if (!router.pages.find((it) => it.name === "adminLayout")) return;
 	const adminAnchorProps = router.anchor(router.path("adminLayout"));
-	if (can("admin:*")) return {
+	if (has("admin:*")) return {
 		text: "You're in control.",
 		sub: "Admin access granted.",
 		steps: [{

package/dist/react/intro/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/react/intro/components/GettingStartedAdminSlide.tsx","../../../src/react/intro/components/GettingStartedAuthSlide.tsx","../../../src/react/intro/components/GettingStartedDevtoolsSlide.tsx","../../../src/react/intro/components/GettingStarted.tsx"],"sourcesContent":["import { useAuth } from \"alepha/react/auth\";\nimport { useRouter } from \"alepha/react/router\";\nimport type { GettingStartedSlide } from \"./GettingStarted.tsx\";\n\n/**\n * Hook that provides the admin slide content.\n * Content changes based on user status and admin permissions.\n * Returns undefined if admin routes are not configured.\n */\nexport const useAdminSlide = (): GettingStartedSlide | undefined => {\n  const { user, can } = useAuth();\n  const router = useRouter();\n\n  // Check if admin routes exist\n  const hasAdmin = router.pages.find((it) => it.name === \"adminLayout\");\n  if (!hasAdmin) {\n    return undefined;\n  }\n\n  const adminAnchorProps = router.anchor(router.path(\"adminLayout\"));\n  const canAccessAdmin = can(\"admin:*\");\n\n  // User is admin - show success message\n  if (canAccessAdmin) {\n    return {\n      text: \"You're in control.\",\n      sub: \"Admin access granted.\",\n      steps: [\n        {\n          num: \"✓\",\n          text: \"You have admin privileges\",\n        },\n        {\n          num: \"→\",\n          text: (\n            <>\n              Go to <a {...adminAnchorProps}>/admin</a> to manage your\n              application\n            </>\n          ),\n        },\n      ],\n    };\n  }\n\n  // User is logged in but not admin - show how to become admin\n  if (user) {\n    return {\n      text: \"Take the wheel.\",\n      sub: \"Become admin in two steps.\",\n      steps: [\n        {\n          num: \"1\",\n          text: (\n            <>\n              Add your email to <code>adminEmails</code> in{\" \"}\n              <code>AppSecurity.ts</code>\n            </>\n          ),\n        },\n        {\n          num: \"2\",\n          text: (\n            <>\n              Go to <a {...adminAnchorProps}>/admin</a>\n            </>\n          ),\n        },\n      ],\n    };\n  }\n\n  // User is not logged in - show full instructions\n  return {\n    text: \"Take the wheel.\",\n    sub: \"Become admin in three steps.\",\n    steps: [\n      {\n        num: \"1\",\n        text: (\n          <>\n            Add your email to <code>adminEmails</code> in{\" \"}\n            <code>AppSecurity.ts</code>\n          </>\n        ),\n      },\n      { num: \"2\", text: \"Create a user account with that email\" },\n      {\n        num: \"3\",\n        text: (\n          <>\n            Go to <a {...adminAnchorProps}>/admin</a>\n          </>\n        ),\n      },\n    ],\n  };\n};\n","import { useAuth } from \"alepha/react/auth\";\nimport { useRouter } from \"alepha/react/router\";\nimport type { GettingStartedSlide } from \"./GettingStarted.tsx\";\n\n/**\n * Hook that provides the auth slide content.\n * Content changes based on whether user is logged in.\n * Returns undefined if auth routes are not configured.\n */\nexport const useAuthSlide = (): GettingStartedSlide | undefined => {\n  const { user, logout } = useAuth();\n  const router = useRouter();\n\n  // Check if auth routes exist\n  const hasAuth = router.pages.find((it) => it.name === \"authLayout\");\n  if (!hasAuth) {\n    return undefined;\n  }\n\n  // User is logged in - show user info and logout option\n  if (user) {\n    return {\n      text: \"Welcome back!\",\n      sub: `You're signed in as ${user.email || user.username || \"user\"}.`,\n      steps: [\n        {\n          num: \"✓\",\n          text: \"Authentication is working correctly\",\n        },\n        {\n          num: \"→\",\n          text: (\n            <>\n              <a\n                href=\"#\"\n                onClick={(e) => {\n                  e.preventDefault();\n                  logout();\n                }}\n              >\n                Sign out\n              </a>{\" \"}\n              to test the login flow\n            </>\n          ),\n        },\n      ],\n    };\n  }\n\n  // User is not logged in - show signup instructions\n  const authAnchorProps = router.anchor(router.path(\"login\"));\n\n  return {\n    text: \"Who are you?\",\n    sub: \"Create your first account.\",\n    steps: [\n      {\n        num: \"1\",\n        text: (\n          <>\n            Sign up at <a {...authAnchorProps}>/auth/login</a>\n          </>\n        ),\n      },\n      {\n        num: \"2\",\n        text: (\n          <>\n            Customize in <code>src/api/AppSecurity.ts</code>\n          </>\n        ),\n      },\n    ],\n  };\n};\n","import type { GettingStartedSlide } from \"./GettingStarted.tsx\";\n\n/**\n * Hook that provides the devtools slide content.\n * Only shown when @alepha/devtools is installed and enabled.\n * Returns undefined if devtools are not available.\n */\nexport const useDevtoolsSlide = (): GettingStartedSlide | undefined => {\n  if (!import.meta.env?.VITE_ALEPHA_DEVTOOLS) {\n    return undefined;\n  }\n\n  return {\n    text: \"Inspect everything.\",\n    sub: \"DevTools are built in.\",\n    steps: [\n      {\n        num: \"→\",\n        text: (\n          <>\n            Open{\" \"}\n            <a href=\"/__devtools/\" target=\"_blank\" rel=\"noopener noreferrer\">\n              /__devtools\n            </a>{\" \"}\n            to explore your app\n          </>\n        ),\n      },\n      {\n        num: \"✓\",\n        text: \"Browse entities, logs, configuration and dependencies\",\n      },\n    ],\n  };\n};\n","import type { ReactNode } from \"react\";\nimport { useCallback, useEffect, useMemo, useState } from \"react\";\nimport { useAdminSlide } from \"./GettingStartedAdminSlide.tsx\";\nimport { useAuthSlide } from \"./GettingStartedAuthSlide.tsx\";\nimport { useDevtoolsSlide } from \"./GettingStartedDevtoolsSlide.tsx\";\n\nexport type GettingStartedStep = {\n  num: string;\n  text: ReactNode;\n};\n\nexport type GettingStartedSlide = {\n  text: string;\n  sub: string;\n  detail?: string;\n  steps?: GettingStartedStep[];\n  links?: { label: string; href: string }[];\n};\n\nexport type GettingStartedWelcome = {\n  appName: string;\n  serverTime: string;\n};\n\nexport type GettingStartedProps = {\n  /**\n   * Welcome data loaded from the server via SSR.\n   *\n   * When provided, displays app name and server timestamp on the first slide,\n   * demonstrating the full SSR → hydration data flow.\n   */\n  welcome?: GettingStartedWelcome;\n};\n\nconst defaultFirstSlide: GettingStartedSlide = {\n  text: \"Let's begin.\",\n  sub: \"Every story starts with a blank page.\",\n  detail: \"This one is yours.\",\n};\n\nconst helpSlide: GettingStartedSlide = {\n  text: \"Need help?\",\n  sub: \"We've got you covered.\",\n  detail: \"Even our AI friends can read the docs.\",\n  links: [\n    { label: \"alepha.dev\", href: \"https://alepha.dev\" },\n    { label: \"llms.txt\", href: \"https://alepha.dev/llms.txt\" },\n  ],\n};\n\nconst formatServerTime = (isoString: string): string => {\n  try {\n    const date = new Date(isoString);\n    return date.toLocaleTimeString(undefined, {\n      hour: \"2-digit\",\n      minute: \"2-digit\",\n      second: \"2-digit\",\n    });\n  } catch {\n    return isoString;\n  }\n};\n\n/**\n * A welcome component displayed when creating a new Alepha application.\n */\nconst GettingStarted = ({ welcome }: GettingStartedProps) => {\n  const [index, setIndex] = useState(0);\n  const [direction, setDirection] = useState<\"next\" | \"prev\">(\"next\");\n\n  // Get auth-aware slide content (hooks return undefined if routes don't exist)\n  const authSlide = useAuthSlide();\n  const adminSlide = useAdminSlide();\n  const devtoolsSlide = useDevtoolsSlide();\n\n  const filteredMessages = useMemo(() => {\n    const result: GettingStartedSlide[] = [];\n\n    // First slide: use welcome data if provided, otherwise default\n    if (welcome) {\n      result.push({\n        ...defaultFirstSlide,\n        detail: `Server time: ${formatServerTime(welcome.serverTime)} - App: ${welcome.appName}`,\n      });\n    } else {\n      result.push(defaultFirstSlide);\n    }\n\n    // Add auth slide if auth routes exist\n    if (authSlide) {\n      result.push(authSlide);\n    }\n\n    // Add admin slide if admin routes exist\n    if (adminSlide) {\n      result.push(adminSlide);\n    }\n\n    // Add devtools slide in non-production environments\n    if (devtoolsSlide) {\n      result.push(devtoolsSlide);\n    }\n\n    // Add \"Need help?\" message\n    result.push(helpSlide);\n\n    return result;\n  }, [welcome, authSlide, adminSlide, devtoolsSlide]);\n\n  const current = filteredMessages[index];\n\n  const prev = useCallback(() => {\n    setDirection(\"prev\");\n    setIndex(\n      (i) => (i - 1 + filteredMessages.length) % filteredMessages.length,\n    );\n  }, [filteredMessages.length]);\n\n  const next = useCallback(() => {\n    setDirection(\"next\");\n    setIndex((i) => (i + 1) % filteredMessages.length);\n  }, [filteredMessages.length]);\n\n  const goTo = useCallback(\n    (i: number) => {\n      setDirection(i > index ? \"next\" : \"prev\");\n      setIndex(i);\n    },\n    [index],\n  );\n\n  useEffect(() => {\n    const handleKeyDown = (e: KeyboardEvent) => {\n      if (e.key === \"ArrowLeft\") {\n        prev();\n      } else if (e.key === \"ArrowRight\") {\n        next();\n      }\n    };\n    window.addEventListener(\"keydown\", handleKeyDown);\n    return () => window.removeEventListener(\"keydown\", handleKeyDown);\n  }, [prev, next]);\n\n  return (\n    <>\n      <style>{styles}</style>\n      <main className=\"alepha-blank\">\n        <div className=\"alepha-blank-content\">\n          <div className=\"alepha-blank-text-block\">\n            <h1\n              className={`alepha-blank-message alepha-blank-slide-${direction}`}\n              key={index}\n            >\n              {current.text}\n            </h1>\n            <p\n              className={`alepha-blank-sub alepha-blank-slide-${direction}`}\n              key={`sub-${index}`}\n            >\n              {current.sub}\n            </p>\n            {current.detail && (\n              <p\n                className={`alepha-blank-detail alepha-blank-slide-${direction}`}\n                key={`detail-${index}`}\n              >\n                {current.detail}\n              </p>\n            )}\n            {current.steps && (\n              <div\n                className={`alepha-blank-steps alepha-blank-slide-${direction}`}\n                key={`steps-${index}`}\n              >\n                {current.steps.map((step, i) => (\n                  <div\n                    key={i}\n                    className=\"alepha-blank-step\"\n                    style={{ animationDelay: `${0.15 + i * 0.08}s` }}\n                  >\n                    <span className=\"alepha-blank-step-num\">{step.num}</span>\n                    <span className=\"alepha-blank-step-text\">{step.text}</span>\n                  </div>\n                ))}\n              </div>\n            )}\n            {current.links && (\n              <div\n                className={`alepha-blank-links alepha-blank-slide-${direction}`}\n                key={`links-${index}`}\n              >\n                {current.links.map((link, i) => (\n                  <a\n                    key={link.href}\n                    href={link.href}\n                    target={link.href.startsWith(\"http\") ? \"_blank\" : undefined}\n                    rel={\n                      link.href.startsWith(\"http\")\n                        ? \"noopener noreferrer\"\n                        : undefined\n                    }\n                    style={{ animationDelay: `${0.1 + i * 0.05}s` }}\n                  >\n                    {link.label}\n                  </a>\n                ))}\n              </div>\n            )}\n          </div>\n\n          <div className=\"alepha-blank-slider\">\n            <button\n              className=\"alepha-blank-nav-btn\"\n              onClick={prev}\n              aria-label=\"Previous\"\n            >\n              <svg width=\"14\" height=\"14\" viewBox=\"0 0 14 14\" fill=\"none\">\n                <path\n                  d=\"M9 3L5 7L9 11\"\n                  stroke=\"currentColor\"\n                  strokeWidth=\"1.5\"\n                  strokeLinecap=\"round\"\n                  strokeLinejoin=\"round\"\n                />\n              </svg>\n            </button>\n            <div className=\"alepha-blank-dots\">\n              {filteredMessages.map((_, i) => (\n                <button\n                  key={i}\n                  className={`alepha-blank-dot ${i === index ? \"active\" : \"\"}`}\n                  onClick={() => goTo(i)}\n                  aria-label={`Go to message ${i + 1}`}\n                />\n              ))}\n            </div>\n            <button\n              className=\"alepha-blank-nav-btn\"\n              onClick={next}\n              aria-label=\"Next\"\n            >\n              <svg width=\"14\" height=\"14\" viewBox=\"0 0 14 14\" fill=\"none\">\n                <path\n                  d=\"M5 3L9 7L5 11\"\n                  stroke=\"currentColor\"\n                  strokeWidth=\"1.5\"\n                  strokeLinecap=\"round\"\n                  strokeLinejoin=\"round\"\n                />\n              </svg>\n            </button>\n          </div>\n\n          <div className=\"alepha-blank-hint\">\n            <kbd>←</kbd> <kbd>→</kbd> to navigate\n          </div>\n        </div>\n      </main>\n    </>\n  );\n};\n\nexport default GettingStarted;\n\nconst styles = `\n.alepha-blank {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  min-height: 100svh;\n  background: #fafafa;\n  font-family: system-ui, -apple-system, sans-serif;\n  color: #171717;\n  position: absolute;\n  left: 0;\n  right: 0;\n  bottom: 0;\n  top: 0;\n  width: 100%;\n}\n\n.alepha-blank-content {\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n  text-align: center;\n  max-width: 640px;\n}\n\n.alepha-blank-text-block {\n  min-height: 320px;\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n  justify-content: center;\n}\n\n.alepha-blank-message {\n  font-size: clamp(2rem, 8vw, 3rem);\n  font-weight: 600;\n  letter-spacing: -0.02em;\n  margin: 0;\n  line-height: 1.1;\n}\n\n.alepha-blank-sub {\n  font-size: 1.0625rem;\n  color: #525252;\n  margin: 1rem 0 0;\n  font-weight: 400;\n  line-height: 1.5;\n}\n\n.alepha-blank-detail {\n  font-size: 0.875rem;\n  color: #a3a3a3;\n  margin: 0.5rem 0 0;\n  font-weight: 400;\n  line-height: 1.5;\n}\n\n.alepha-blank-slide-next {\n  animation: alepha-blank-slideNext 0.4s cubic-bezier(0.22, 1, 0.36, 1) both;\n}\n\n.alepha-blank-slide-prev {\n  animation: alepha-blank-slidePrev 0.4s cubic-bezier(0.22, 1, 0.36, 1) both;\n}\n\n@keyframes alepha-blank-slideNext {\n  from {\n    opacity: 0;\n    transform: translateX(20px);\n  }\n  to {\n    opacity: 1;\n    transform: translateX(0);\n  }\n}\n\n@keyframes alepha-blank-slidePrev {\n  from {\n    opacity: 0;\n    transform: translateX(-20px);\n  }\n  to {\n    opacity: 1;\n    transform: translateX(0);\n  }\n}\n\n.alepha-blank-steps {\n  display: flex;\n  flex-direction: column;\n  gap: 0.25rem;\n  margin-top: 1.25rem;\n  text-align: left;\n}\n\n.alepha-blank-step {\n  display: flex;\n  align-items: center;\n  gap: 0.625rem;\n  padding: 0.25rem 0;\n  opacity: 0;\n  animation: alepha-blank-stepIn 0.4s cubic-bezier(0.22, 1, 0.36, 1) forwards;\n}\n\n.alepha-blank-step-num {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  width: 20px;\n  height: 20px;\n  border-radius: 50%;\n  background: #171717;\n  color: #fff;\n  font-size: 0.6875rem;\n  font-weight: 600;\n  flex-shrink: 0;\n}\n\n.alepha-blank-step-text {\n  font-size: 0.8125rem;\n  color: #525252;\n  line-height: 1.5;\n}\n\n.alepha-blank-step-text code {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 0.75rem;\n  background: #f5f5f5;\n  color: #171717;\n  padding: 0.0625rem 0.375rem;\n  border-radius: 3px;\n  border: 1px solid #e5e5e5;\n}\n\n.alepha-blank-step-text a {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  color: #525252;\n  text-decoration: underline;\n  text-underline-offset: 2px;\n  transition: color 0.15s ease;\n}\n\n.alepha-blank-step-text a:hover {\n  color: #171717;\n}\n\n@keyframes alepha-blank-stepIn {\n  from {\n    opacity: 0;\n    transform: translateY(10px);\n  }\n  to {\n    opacity: 1;\n    transform: translateY(0);\n  }\n}\n\n.alepha-blank-links {\n  display: flex;\n  gap: 1.5rem;\n  margin-top: 1.25rem;\n}\n\n.alepha-blank-links a {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 0.875rem;\n  color: #525252;\n  text-decoration: none;\n  position: relative;\n  opacity: 0;\n  animation: alepha-blank-fadeIn 0.3s ease-out forwards;\n  transition: color 0.2s ease;\n}\n\n.alepha-blank-links a::after {\n  content: \"\";\n  position: absolute;\n  left: 0;\n  right: 0;\n  bottom: -2px;\n  height: 1px;\n  background: #a3a3a3;\n  transform: scaleX(1);\n  transform-origin: left;\n  transition:\n    transform 0.25s cubic-bezier(0.22, 1, 0.36, 1),\n    background 0.2s ease;\n}\n\n.alepha-blank-links a:hover {\n  color: #171717;\n}\n\n.alepha-blank-links a:hover::after {\n  background: #171717;\n  transform: scaleX(1.05);\n}\n\n.alepha-blank-slider {\n  display: flex;\n  align-items: center;\n  gap: 1rem;\n  margin-top: 2.5rem;\n}\n\n.alepha-blank-dots {\n  display: flex;\n  align-items: center;\n  gap: 0.5rem;\n}\n\n.alepha-blank-dot {\n  width: 8px;\n  height: 8px;\n  border-radius: 50%;\n  background: transparent;\n  border: 1.5px solid #d4d4d4;\n  padding: 0;\n  cursor: pointer;\n  transition: all 0.25s cubic-bezier(0.22, 1, 0.36, 1);\n}\n\n.alepha-blank-dot:hover {\n  border-color: #a3a3a3;\n  transform: scale(1.2);\n}\n\n.alepha-blank-dot:focus-visible {\n  outline: 2px solid #737373;\n  outline-offset: 2px;\n}\n\n.alepha-blank-dot.active {\n  background: #737373;\n  border-color: #737373;\n  transform: scale(1.1);\n}\n\n.alepha-blank-nav-btn {\n  width: 32px;\n  height: 32px;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  padding: 0;\n  font-family: inherit;\n  background: transparent;\n  color: #a3a3a3;\n  border: 1.5px solid transparent;\n  border-radius: 8px;\n  cursor: pointer;\n  transition: all 0.2s cubic-bezier(0.22, 1, 0.36, 1);\n}\n\n.alepha-blank-nav-btn:hover {\n  color: #525252;\n  background: #f0f0f0;\n}\n\n.alepha-blank-nav-btn:focus-visible {\n  outline: none;\n  border-color: #737373;\n  color: #525252;\n}\n\n.alepha-blank-nav-btn:active {\n  transform: scale(0.92);\n  background: #e5e5e5;\n}\n\n.alepha-blank-hint {\n  margin-top: 2rem;\n  font-size: 0.75rem;\n  color: #a3a3a3;\n  display: flex;\n  align-items: center;\n  gap: 0.375rem;\n  opacity: 0;\n  animation: alepha-blank-fadeIn 0.5s ease-out 0.5s forwards;\n}\n\n.alepha-blank-hint kbd {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 0.6875rem;\n  background: #f0f0f0;\n  border: 1px solid #e5e5e5;\n  border-radius: 4px;\n  padding: 0.125rem 0.375rem;\n  box-shadow: 0 1px 0 #d4d4d4;\n}\n\n@keyframes alepha-blank-fadeIn {\n  from {\n    opacity: 0;\n  }\n  to {\n    opacity: 1;\n  }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .alepha-blank-slide-next,\n  .alepha-blank-slide-prev,\n  .alepha-blank-links a,\n  .alepha-blank-hint,\n  .alepha-blank-step {\n    animation: none;\n    opacity: 1;\n  }\n\n  .alepha-blank-dot,\n  .alepha-blank-nav-btn,\n  .alepha-blank-links a,\n  .alepha-blank-links a::after {\n    transition: none;\n  }\n}\n`;\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/react/intro/components/GettingStartedAdminSlide.tsx","../../../src/react/intro/components/GettingStartedAuthSlide.tsx","../../../src/react/intro/components/GettingStartedDevtoolsSlide.tsx","../../../src/react/intro/components/GettingStarted.tsx"],"sourcesContent":["import { useAuth } from \"alepha/react/auth\";\nimport { useRouter } from \"alepha/react/router\";\nimport type { GettingStartedSlide } from \"./GettingStarted.tsx\";\n\n/**\n * Hook that provides the admin slide content.\n * Content changes based on user status and admin permissions.\n * Returns undefined if admin routes are not configured.\n */\nexport const useAdminSlide = (): GettingStartedSlide | undefined => {\n  const { user, has } = useAuth();\n  const router = useRouter();\n\n  // Check if admin routes exist\n  const hasAdmin = router.pages.find((it) => it.name === \"adminLayout\");\n  if (!hasAdmin) {\n    return undefined;\n  }\n\n  const adminAnchorProps = router.anchor(router.path(\"adminLayout\"));\n  const canAccessAdmin = has(\"admin:*\");\n\n  // User is admin - show success message\n  if (canAccessAdmin) {\n    return {\n      text: \"You're in control.\",\n      sub: \"Admin access granted.\",\n      steps: [\n        {\n          num: \"✓\",\n          text: \"You have admin privileges\",\n        },\n        {\n          num: \"→\",\n          text: (\n            <>\n              Go to <a {...adminAnchorProps}>/admin</a> to manage your\n              application\n            </>\n          ),\n        },\n      ],\n    };\n  }\n\n  // User is logged in but not admin - show how to become admin\n  if (user) {\n    return {\n      text: \"Take the wheel.\",\n      sub: \"Become admin in two steps.\",\n      steps: [\n        {\n          num: \"1\",\n          text: (\n            <>\n              Add your email to <code>adminEmails</code> in{\" \"}\n              <code>AppSecurity.ts</code>\n            </>\n          ),\n        },\n        {\n          num: \"2\",\n          text: (\n            <>\n              Go to <a {...adminAnchorProps}>/admin</a>\n            </>\n          ),\n        },\n      ],\n    };\n  }\n\n  // User is not logged in - show full instructions\n  return {\n    text: \"Take the wheel.\",\n    sub: \"Become admin in three steps.\",\n    steps: [\n      {\n        num: \"1\",\n        text: (\n          <>\n            Add your email to <code>adminEmails</code> in{\" \"}\n            <code>AppSecurity.ts</code>\n          </>\n        ),\n      },\n      { num: \"2\", text: \"Create a user account with that email\" },\n      {\n        num: \"3\",\n        text: (\n          <>\n            Go to <a {...adminAnchorProps}>/admin</a>\n          </>\n        ),\n      },\n    ],\n  };\n};\n","import { useAuth } from \"alepha/react/auth\";\nimport { useRouter } from \"alepha/react/router\";\nimport type { GettingStartedSlide } from \"./GettingStarted.tsx\";\n\n/**\n * Hook that provides the auth slide content.\n * Content changes based on whether user is logged in.\n * Returns undefined if auth routes are not configured.\n */\nexport const useAuthSlide = (): GettingStartedSlide | undefined => {\n  const { user, logout } = useAuth();\n  const router = useRouter();\n\n  // Check if auth routes exist\n  const hasAuth = router.pages.find((it) => it.name === \"authLayout\");\n  if (!hasAuth) {\n    return undefined;\n  }\n\n  // User is logged in - show user info and logout option\n  if (user) {\n    return {\n      text: \"Welcome back!\",\n      sub: `You're signed in as ${user.email || user.username || \"user\"}.`,\n      steps: [\n        {\n          num: \"✓\",\n          text: \"Authentication is working correctly\",\n        },\n        {\n          num: \"→\",\n          text: (\n            <>\n              <a\n                href=\"#\"\n                onClick={(e) => {\n                  e.preventDefault();\n                  logout();\n                }}\n              >\n                Sign out\n              </a>{\" \"}\n              to test the login flow\n            </>\n          ),\n        },\n      ],\n    };\n  }\n\n  // User is not logged in - show signup instructions\n  const authAnchorProps = router.anchor(router.path(\"login\"));\n\n  return {\n    text: \"Who are you?\",\n    sub: \"Create your first account.\",\n    steps: [\n      {\n        num: \"1\",\n        text: (\n          <>\n            Sign up at <a {...authAnchorProps}>/auth/login</a>\n          </>\n        ),\n      },\n      {\n        num: \"2\",\n        text: (\n          <>\n            Customize in <code>src/api/AppSecurity.ts</code>\n          </>\n        ),\n      },\n    ],\n  };\n};\n","import type { GettingStartedSlide } from \"./GettingStarted.tsx\";\n\n/**\n * Hook that provides the devtools slide content.\n * Only shown when @alepha/devtools is installed and enabled.\n * Returns undefined if devtools are not available.\n */\nexport const useDevtoolsSlide = (): GettingStartedSlide | undefined => {\n  if (!import.meta.env?.VITE_ALEPHA_DEVTOOLS) {\n    return undefined;\n  }\n\n  return {\n    text: \"Inspect everything.\",\n    sub: \"DevTools are built in.\",\n    steps: [\n      {\n        num: \"→\",\n        text: (\n          <>\n            Open{\" \"}\n            <a href=\"/__devtools/\" target=\"_blank\" rel=\"noopener noreferrer\">\n              /__devtools\n            </a>{\" \"}\n            to explore your app\n          </>\n        ),\n      },\n      {\n        num: \"✓\",\n        text: \"Browse entities, logs, configuration and dependencies\",\n      },\n    ],\n  };\n};\n","import type { ReactNode } from \"react\";\nimport { useCallback, useEffect, useMemo, useState } from \"react\";\nimport { useAdminSlide } from \"./GettingStartedAdminSlide.tsx\";\nimport { useAuthSlide } from \"./GettingStartedAuthSlide.tsx\";\nimport { useDevtoolsSlide } from \"./GettingStartedDevtoolsSlide.tsx\";\n\nexport type GettingStartedStep = {\n  num: string;\n  text: ReactNode;\n};\n\nexport type GettingStartedSlide = {\n  text: string;\n  sub: string;\n  detail?: string;\n  steps?: GettingStartedStep[];\n  links?: { label: string; href: string }[];\n};\n\nexport type GettingStartedWelcome = {\n  appName: string;\n  serverTime: string;\n};\n\nexport type GettingStartedProps = {\n  /**\n   * Welcome data loaded from the server via SSR.\n   *\n   * When provided, displays app name and server timestamp on the first slide,\n   * demonstrating the full SSR → hydration data flow.\n   */\n  welcome?: GettingStartedWelcome;\n};\n\nconst defaultFirstSlide: GettingStartedSlide = {\n  text: \"Let's begin.\",\n  sub: \"Every story starts with a blank page.\",\n  detail: \"This one is yours.\",\n};\n\nconst helpSlide: GettingStartedSlide = {\n  text: \"Need help?\",\n  sub: \"We've got you covered.\",\n  detail: \"Even our AI friends can read the docs.\",\n  links: [\n    { label: \"alepha.dev\", href: \"https://alepha.dev\" },\n    { label: \"llms.txt\", href: \"https://alepha.dev/llms.txt\" },\n  ],\n};\n\nconst formatServerTime = (isoString: string): string => {\n  try {\n    const date = new Date(isoString);\n    return date.toLocaleTimeString(undefined, {\n      hour: \"2-digit\",\n      minute: \"2-digit\",\n      second: \"2-digit\",\n    });\n  } catch {\n    return isoString;\n  }\n};\n\n/**\n * A welcome component displayed when creating a new Alepha application.\n */\nconst GettingStarted = ({ welcome }: GettingStartedProps) => {\n  const [index, setIndex] = useState(0);\n  const [direction, setDirection] = useState<\"next\" | \"prev\">(\"next\");\n\n  // Get auth-aware slide content (hooks return undefined if routes don't exist)\n  const authSlide = useAuthSlide();\n  const adminSlide = useAdminSlide();\n  const devtoolsSlide = useDevtoolsSlide();\n\n  const filteredMessages = useMemo(() => {\n    const result: GettingStartedSlide[] = [];\n\n    // First slide: use welcome data if provided, otherwise default\n    if (welcome) {\n      result.push({\n        ...defaultFirstSlide,\n        detail: `Server time: ${formatServerTime(welcome.serverTime)} - App: ${welcome.appName}`,\n      });\n    } else {\n      result.push(defaultFirstSlide);\n    }\n\n    // Add auth slide if auth routes exist\n    if (authSlide) {\n      result.push(authSlide);\n    }\n\n    // Add admin slide if admin routes exist\n    if (adminSlide) {\n      result.push(adminSlide);\n    }\n\n    // Add devtools slide in non-production environments\n    if (devtoolsSlide) {\n      result.push(devtoolsSlide);\n    }\n\n    // Add \"Need help?\" message\n    result.push(helpSlide);\n\n    return result;\n  }, [welcome, authSlide, adminSlide, devtoolsSlide]);\n\n  const current = filteredMessages[index];\n\n  const prev = useCallback(() => {\n    setDirection(\"prev\");\n    setIndex(\n      (i) => (i - 1 + filteredMessages.length) % filteredMessages.length,\n    );\n  }, [filteredMessages.length]);\n\n  const next = useCallback(() => {\n    setDirection(\"next\");\n    setIndex((i) => (i + 1) % filteredMessages.length);\n  }, [filteredMessages.length]);\n\n  const goTo = useCallback(\n    (i: number) => {\n      setDirection(i > index ? \"next\" : \"prev\");\n      setIndex(i);\n    },\n    [index],\n  );\n\n  useEffect(() => {\n    const handleKeyDown = (e: KeyboardEvent) => {\n      if (e.key === \"ArrowLeft\") {\n        prev();\n      } else if (e.key === \"ArrowRight\") {\n        next();\n      }\n    };\n    window.addEventListener(\"keydown\", handleKeyDown);\n    return () => window.removeEventListener(\"keydown\", handleKeyDown);\n  }, [prev, next]);\n\n  return (\n    <>\n      <style>{styles}</style>\n      <main className=\"alepha-blank\">\n        <div className=\"alepha-blank-content\">\n          <div className=\"alepha-blank-text-block\">\n            <h1\n              className={`alepha-blank-message alepha-blank-slide-${direction}`}\n              key={index}\n            >\n              {current.text}\n            </h1>\n            <p\n              className={`alepha-blank-sub alepha-blank-slide-${direction}`}\n              key={`sub-${index}`}\n            >\n              {current.sub}\n            </p>\n            {current.detail && (\n              <p\n                className={`alepha-blank-detail alepha-blank-slide-${direction}`}\n                key={`detail-${index}`}\n              >\n                {current.detail}\n              </p>\n            )}\n            {current.steps && (\n              <div\n                className={`alepha-blank-steps alepha-blank-slide-${direction}`}\n                key={`steps-${index}`}\n              >\n                {current.steps.map((step, i) => (\n                  <div\n                    key={i}\n                    className=\"alepha-blank-step\"\n                    style={{ animationDelay: `${0.15 + i * 0.08}s` }}\n                  >\n                    <span className=\"alepha-blank-step-num\">{step.num}</span>\n                    <span className=\"alepha-blank-step-text\">{step.text}</span>\n                  </div>\n                ))}\n              </div>\n            )}\n            {current.links && (\n              <div\n                className={`alepha-blank-links alepha-blank-slide-${direction}`}\n                key={`links-${index}`}\n              >\n                {current.links.map((link, i) => (\n                  <a\n                    key={link.href}\n                    href={link.href}\n                    target={link.href.startsWith(\"http\") ? \"_blank\" : undefined}\n                    rel={\n                      link.href.startsWith(\"http\")\n                        ? \"noopener noreferrer\"\n                        : undefined\n                    }\n                    style={{ animationDelay: `${0.1 + i * 0.05}s` }}\n                  >\n                    {link.label}\n                  </a>\n                ))}\n              </div>\n            )}\n          </div>\n\n          <div className=\"alepha-blank-slider\">\n            <button\n              className=\"alepha-blank-nav-btn\"\n              onClick={prev}\n              aria-label=\"Previous\"\n            >\n              <svg width=\"14\" height=\"14\" viewBox=\"0 0 14 14\" fill=\"none\">\n                <path\n                  d=\"M9 3L5 7L9 11\"\n                  stroke=\"currentColor\"\n                  strokeWidth=\"1.5\"\n                  strokeLinecap=\"round\"\n                  strokeLinejoin=\"round\"\n                />\n              </svg>\n            </button>\n            <div className=\"alepha-blank-dots\">\n              {filteredMessages.map((_, i) => (\n                <button\n                  key={i}\n                  className={`alepha-blank-dot ${i === index ? \"active\" : \"\"}`}\n                  onClick={() => goTo(i)}\n                  aria-label={`Go to message ${i + 1}`}\n                />\n              ))}\n            </div>\n            <button\n              className=\"alepha-blank-nav-btn\"\n              onClick={next}\n              aria-label=\"Next\"\n            >\n              <svg width=\"14\" height=\"14\" viewBox=\"0 0 14 14\" fill=\"none\">\n                <path\n                  d=\"M5 3L9 7L5 11\"\n                  stroke=\"currentColor\"\n                  strokeWidth=\"1.5\"\n                  strokeLinecap=\"round\"\n                  strokeLinejoin=\"round\"\n                />\n              </svg>\n            </button>\n          </div>\n\n          <div className=\"alepha-blank-hint\">\n            <kbd>←</kbd> <kbd>→</kbd> to navigate\n          </div>\n        </div>\n      </main>\n    </>\n  );\n};\n\nexport default GettingStarted;\n\nconst styles = `\n.alepha-blank {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  min-height: 100svh;\n  background: #fafafa;\n  font-family: system-ui, -apple-system, sans-serif;\n  color: #171717;\n  position: absolute;\n  left: 0;\n  right: 0;\n  bottom: 0;\n  top: 0;\n  width: 100%;\n}\n\n.alepha-blank-content {\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n  text-align: center;\n  max-width: 640px;\n}\n\n.alepha-blank-text-block {\n  min-height: 320px;\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n  justify-content: center;\n}\n\n.alepha-blank-message {\n  font-size: clamp(2rem, 8vw, 3rem);\n  font-weight: 600;\n  letter-spacing: -0.02em;\n  margin: 0;\n  line-height: 1.1;\n}\n\n.alepha-blank-sub {\n  font-size: 1.0625rem;\n  color: #525252;\n  margin: 1rem 0 0;\n  font-weight: 400;\n  line-height: 1.5;\n}\n\n.alepha-blank-detail {\n  font-size: 0.875rem;\n  color: #a3a3a3;\n  margin: 0.5rem 0 0;\n  font-weight: 400;\n  line-height: 1.5;\n}\n\n.alepha-blank-slide-next {\n  animation: alepha-blank-slideNext 0.4s cubic-bezier(0.22, 1, 0.36, 1) both;\n}\n\n.alepha-blank-slide-prev {\n  animation: alepha-blank-slidePrev 0.4s cubic-bezier(0.22, 1, 0.36, 1) both;\n}\n\n@keyframes alepha-blank-slideNext {\n  from {\n    opacity: 0;\n    transform: translateX(20px);\n  }\n  to {\n    opacity: 1;\n    transform: translateX(0);\n  }\n}\n\n@keyframes alepha-blank-slidePrev {\n  from {\n    opacity: 0;\n    transform: translateX(-20px);\n  }\n  to {\n    opacity: 1;\n    transform: translateX(0);\n  }\n}\n\n.alepha-blank-steps {\n  display: flex;\n  flex-direction: column;\n  gap: 0.25rem;\n  margin-top: 1.25rem;\n  text-align: left;\n}\n\n.alepha-blank-step {\n  display: flex;\n  align-items: center;\n  gap: 0.625rem;\n  padding: 0.25rem 0;\n  opacity: 0;\n  animation: alepha-blank-stepIn 0.4s cubic-bezier(0.22, 1, 0.36, 1) forwards;\n}\n\n.alepha-blank-step-num {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  width: 20px;\n  height: 20px;\n  border-radius: 50%;\n  background: #171717;\n  color: #fff;\n  font-size: 0.6875rem;\n  font-weight: 600;\n  flex-shrink: 0;\n}\n\n.alepha-blank-step-text {\n  font-size: 0.8125rem;\n  color: #525252;\n  line-height: 1.5;\n}\n\n.alepha-blank-step-text code {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 0.75rem;\n  background: #f5f5f5;\n  color: #171717;\n  padding: 0.0625rem 0.375rem;\n  border-radius: 3px;\n  border: 1px solid #e5e5e5;\n}\n\n.alepha-blank-step-text a {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  color: #525252;\n  text-decoration: underline;\n  text-underline-offset: 2px;\n  transition: color 0.15s ease;\n}\n\n.alepha-blank-step-text a:hover {\n  color: #171717;\n}\n\n@keyframes alepha-blank-stepIn {\n  from {\n    opacity: 0;\n    transform: translateY(10px);\n  }\n  to {\n    opacity: 1;\n    transform: translateY(0);\n  }\n}\n\n.alepha-blank-links {\n  display: flex;\n  gap: 1.5rem;\n  margin-top: 1.25rem;\n}\n\n.alepha-blank-links a {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 0.875rem;\n  color: #525252;\n  text-decoration: none;\n  position: relative;\n  opacity: 0;\n  animation: alepha-blank-fadeIn 0.3s ease-out forwards;\n  transition: color 0.2s ease;\n}\n\n.alepha-blank-links a::after {\n  content: \"\";\n  position: absolute;\n  left: 0;\n  right: 0;\n  bottom: -2px;\n  height: 1px;\n  background: #a3a3a3;\n  transform: scaleX(1);\n  transform-origin: left;\n  transition:\n    transform 0.25s cubic-bezier(0.22, 1, 0.36, 1),\n    background 0.2s ease;\n}\n\n.alepha-blank-links a:hover {\n  color: #171717;\n}\n\n.alepha-blank-links a:hover::after {\n  background: #171717;\n  transform: scaleX(1.05);\n}\n\n.alepha-blank-slider {\n  display: flex;\n  align-items: center;\n  gap: 1rem;\n  margin-top: 2.5rem;\n}\n\n.alepha-blank-dots {\n  display: flex;\n  align-items: center;\n  gap: 0.5rem;\n}\n\n.alepha-blank-dot {\n  width: 8px;\n  height: 8px;\n  border-radius: 50%;\n  background: transparent;\n  border: 1.5px solid #d4d4d4;\n  padding: 0;\n  cursor: pointer;\n  transition: all 0.25s cubic-bezier(0.22, 1, 0.36, 1);\n}\n\n.alepha-blank-dot:hover {\n  border-color: #a3a3a3;\n  transform: scale(1.2);\n}\n\n.alepha-blank-dot:focus-visible {\n  outline: 2px solid #737373;\n  outline-offset: 2px;\n}\n\n.alepha-blank-dot.active {\n  background: #737373;\n  border-color: #737373;\n  transform: scale(1.1);\n}\n\n.alepha-blank-nav-btn {\n  width: 32px;\n  height: 32px;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  padding: 0;\n  font-family: inherit;\n  background: transparent;\n  color: #a3a3a3;\n  border: 1.5px solid transparent;\n  border-radius: 8px;\n  cursor: pointer;\n  transition: all 0.2s cubic-bezier(0.22, 1, 0.36, 1);\n}\n\n.alepha-blank-nav-btn:hover {\n  color: #525252;\n  background: #f0f0f0;\n}\n\n.alepha-blank-nav-btn:focus-visible {\n  outline: none;\n  border-color: #737373;\n  color: #525252;\n}\n\n.alepha-blank-nav-btn:active {\n  transform: scale(0.92);\n  background: #e5e5e5;\n}\n\n.alepha-blank-hint {\n  margin-top: 2rem;\n  font-size: 0.75rem;\n  color: #a3a3a3;\n  display: flex;\n  align-items: center;\n  gap: 0.375rem;\n  opacity: 0;\n  animation: alepha-blank-fadeIn 0.5s ease-out 0.5s forwards;\n}\n\n.alepha-blank-hint kbd {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 0.6875rem;\n  background: #f0f0f0;\n  border: 1px solid #e5e5e5;\n  border-radius: 4px;\n  padding: 0.125rem 0.375rem;\n  box-shadow: 0 1px 0 #d4d4d4;\n}\n\n@keyframes alepha-blank-fadeIn {\n  from {\n    opacity: 0;\n  }\n  to {\n    opacity: 1;\n  }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .alepha-blank-slide-next,\n  .alepha-blank-slide-prev,\n  .alepha-blank-links a,\n  .alepha-blank-hint,\n  .alepha-blank-step {\n    animation: none;\n    opacity: 1;\n  }\n\n  .alepha-blank-dot,\n  .alepha-blank-nav-btn,\n  .alepha-blank-links a,\n  .alepha-blank-links a::after {\n    transition: none;\n  }\n}\n`;\n"],"mappings":"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"}

package/dist/react/router/index.browser.js

@@ -2,7 +2,7 @@ import { $atom, $hook, $inject, $module, $state, Alepha, AlephaError, KIND, OPTI
 import { AlephaDateTime, DateTimeProvider } from "alepha/datetime";
 import { AlephaContext, AlephaReact, ClientOnly, ErrorBoundary, useAlepha, useEvents, useInject, useStore } from "alepha/react";
 import { AlephaReactHead, BrowserHeadProvider } from "alepha/react/head";
-import { AlephaServer, ForbiddenError } from "alepha/server";
+import { AlephaServer } from "alepha/server";
 import { AlephaServerLinks, LinkProvider } from "alepha/server/links";
 import { $cache } from "alepha/cache";
 import { $logger } from "alepha/logger";
@@ -1193,9 +1193,6 @@ var ReactBrowserRouterProvider = class extends RouterProvider {
 			const { route, params } = this.match(pathname);
 			const query = {};
 			if (search) for (const [key, value] of new URLSearchParams(search).entries()) query[key] = String(value);
-			if (route?.page.can) {
-				if (!route.page.can()) throw new ForbiddenError("Access denied to this page.");
-			}
 			state.name = route?.page.name;
 			state.query = query;
 			state.params = params ?? {};
@@ -1735,36 +1732,85 @@ const useActive = (args) => {
 //#region ../../src/react/router/hooks/useQueryParams.ts
 /**
 * Hook to manage query parameters in the URL using a defined schema.
+*
+* Two storage formats are supported via {@link UseQueryParamsHookOptions.format}:
+* - `"base64"` (default) packs the whole object into a single opaque param
+*   (named by `key`, default `q`) — e.g. `?q=eyJ0YWIiOiJzZWN1cml0eSJ9`.
+* - `"querystring"` spreads each schema field across its own readable param —
+*   e.g. `?tab=security`. In this mode `key` is ignored.
+*
+* By default the URL is updated with `replaceState` (no new history entry).
+* Pass `push: true` to add a history entry instead, so the browser back
+* button steps back through previous values.
+*
+* @example
+* const [params, setParams] = useQueryParams(
+*   t.object({ tab: t.optional(t.string()) }),
+*   { format: "querystring" },
+* );
+* // params.tab reads from `?tab=…`; setParams({ tab: "security" }) writes it.
 */
 const useQueryParams = (schema, options = {}) => {
 	const alepha = useAlepha();
-	const key = options.key ?? "q";
 	const router = useRouter();
-	const querystring = router.query[key];
-	const [queryParams = {}, setQueryParams] = useState(decode(alepha, schema, router.query[key]));
+	const key = options.key ?? "q";
+	const format = options.format ?? "base64";
+	const read = () => format === "querystring" ? decodeQueryString(alepha, schema, router.query) : decodeBase64(alepha, schema, router.query[key]);
+	const signature = format === "querystring" ? Object.keys(schema.properties).map((name) => `${name}=${router.query[name] ?? ""}`).join("&") : router.query[key];
+	const [queryParams = {}, setQueryParams] = useState(read());
 	useEffect(() => {
-		setQueryParams(decode(alepha, schema, querystring));
-	}, [querystring]);
-	return [queryParams, (queryParams) => {
-		setQueryParams(queryParams);
-		router.setQueryParams((data) => {
-			return {
-				...data,
-				[key]: encode(alepha, schema, queryParams)
-			};
-		});
+		setQueryParams(read());
+	}, [signature]);
+	return [queryParams, (next) => {
+		setQueryParams(next);
+		router.setQueryParams((data) => format === "querystring" ? writeQueryString(alepha, schema, data, next) : {
+			...data,
+			[key]: encodeBase64(alepha, schema, next)
+		}, { push: options.push });
 	}];
 };
-const encode = (alepha, schema, data) => {
+const encodeBase64 = (alepha, schema, data) => {
 	return btoa(JSON.stringify(alepha.codec.decode(schema, data)));
 };
-const decode = (alepha, schema, data) => {
+const decodeBase64 = (alepha, schema, data) => {
 	try {
 		return alepha.codec.decode(schema, JSON.parse(atob(decodeURIComponent(data))));
 	} catch {
 		return;
 	}
 };
+/**
+* querystring read: each schema field is its own URL param. Mirrors the
+* server's per-key query decode — `codec.decode(propertySchema, rawString)`
+* coerces the raw string into the declared type (number, boolean, …).
+*/
+const decodeQueryString = (alepha, schema, query) => {
+	try {
+		const out = {};
+		for (const name of Object.keys(schema.properties)) {
+			const raw = query[name];
+			if (raw != null && raw !== "") out[name] = alepha.codec.decode(schema.properties[name], raw);
+		}
+		return out;
+	} catch {
+		return;
+	}
+};
+/**
+* querystring write: spread the decoded object across individual params,
+* dropping empty values so the URL stays clean. Unrelated params (not part
+* of the schema) are preserved.
+*/
+const writeQueryString = (alepha, schema, current, next) => {
+	const decoded = alepha.codec.decode(schema, next);
+	const merged = { ...current };
+	for (const name of Object.keys(schema.properties)) {
+		const value = decoded?.[name];
+		if (value == null || value === "") delete merged[name];
+		else merged[name] = String(value);
+	}
+	return merged;
+};
 //#endregion
 //#region ../../src/react/router/index.browser.ts
 const AlephaReactRouter = $module({