alepha 0.22.0 → 0.24.0

package/dist/server/cookies/index.browser.js

@@ -1,4 +1,4 @@
-import { $inject, $module, Alepha, AlephaError, KIND, Primitive, createPrimitive } from "alepha";
+import { $hook, $inject, $module, Alepha, AlephaError, KIND, Primitive, createPrimitive } from "alepha";
 import { AlephaServer } from "alepha/server";
 import { DateTimeProvider } from "alepha/datetime";
 //#region ../../src/server/cookies/services/CookieParser.ts
@@ -32,7 +32,7 @@ var CookieParser = class {
 		const parts = [];
 		parts.push(`${name}=${cookie.value}`);
 		if (cookie.path) parts.push(`Path=${cookie.path}`);
-		if (cookie.maxAge) parts.push(`Max-Age=${cookie.maxAge}`);
+		if (cookie.maxAge != null) parts.push(`Max-Age=${cookie.maxAge}`);
 		if (cookie.secure !== false && isHttps) parts.push("Secure");
 		if (cookie.httpOnly) parts.push("HttpOnly");
 		if (cookie.sameSite) parts.push(`SameSite=${cookie.sameSite}`);
@@ -41,6 +41,100 @@ var CookieParser = class {
 	}
 };
 //#endregion
+//#region ../../src/server/cookies/providers/AtomCookiePersistence.browser.ts
+/**
+* Browser variant of AtomCookiePersistence: reads `document.cookie` for every
+* `persist: "cookie"` atom, and writes it back on every mutation.
+*
+* Like the server variant, atoms are resolved from the `StateManager`
+* registry (`alepha.store.listAtoms()`) rather than from a map fed by
+* `state:register` — that event fires once, is never replayed, and
+* `$module.register()` registers `atoms[]` before the module's `services[]`
+* exist, so an event-sourced map would miss every atom declared the
+* documented way. The `configure` hook sweeps everything registered up to
+* boot; `state:register` covers atoms that first register later (lazily, on
+* first read).
+*
+* Cookie names are NOT APP_NAME-prefixed here, because `APP_NAME` is not
+* reachable in the browser: `BuildClientTask` only `define`s
+* `process.env.NODE_ENV` for the client bundle, and the SSR hydration
+* payload (`ReactServerTemplateProvider.buildHydrationData`) only carries
+* registered atom values + router layers — never the raw `env` store key.
+* The server variant (`AtomCookiePersistence.ts`) matches this by passing
+* `prefix: false` to `ServerCookiesProvider`, specifically for atom-cookie
+* traffic — every other server cookie ($cookie primitive) still gets the
+* APP_NAME namespace. See `ServerCookiesProvider.prefixName`.
+*/
+var AtomCookiePersistence = class {
+	alepha = $inject(Alepha);
+	cookieParser = $inject(CookieParser);
+	dateTime = $inject(DateTimeProvider);
+	onConfigure = $hook({
+		on: "configure",
+		handler: () => {
+			for (const atom of this.cookieAtoms()) this.read(atom);
+		}
+	});
+	onRegister = $hook({
+		on: "state:register",
+		handler: ({ atom }) => {
+			if (atom.options.persist !== "cookie") return;
+			this.read(atom);
+		}
+	});
+	onMutate = $hook({
+		on: "state:mutate",
+		handler: ({ key, value }) => {
+			const atom = this.alepha.store.getAtom(String(key));
+			if (!atom || atom.options.persist !== "cookie") return;
+			if (value === void 0) {
+				this.clearCookie(atom.key);
+				return;
+			}
+			const cookie = {
+				value: encodeURIComponent(JSON.stringify(value)),
+				path: "/",
+				sameSite: "lax",
+				maxAge: this.dateTime.duration([365, "days"]).as("seconds")
+			};
+			document.cookie = this.cookieParser.cookieToString(atom.key, cookie);
+		}
+	});
+	/**
+	* Every registered atom declared with `persist: "cookie"`, read live from
+	* the state manager's registry.
+	*/
+	cookieAtoms() {
+		return this.alepha.store.listAtoms().filter((atom) => atom.options.persist === "cookie");
+	}
+	/**
+	* Seed an atom's state from `document.cookie`, if a cookie exists for it.
+	* Idempotent: re-reading an atom that already holds the cookie's value is
+	* a no-op write of the same data.
+	*/
+	read(atom) {
+		const raw = this.cookieParser.parseRequestCookies(document.cookie)[atom.key];
+		if (!raw) return;
+		try {
+			this.alepha.store.set(atom.key, JSON.parse(decodeURIComponent(raw)), { skipEvents: true });
+		} catch {
+			this.clearCookie(atom.key);
+		}
+	}
+	/**
+	* Expire a cookie immediately, mirroring
+	* `ServerCookiesProvider.deleteCookie`'s `Max-Age=0` semantics.
+	*/
+	clearCookie(name) {
+		document.cookie = this.cookieParser.cookieToString(name, {
+			value: "",
+			path: "/",
+			sameSite: "lax",
+			maxAge: 0
+		});
+	}
+};
+//#endregion
 //#region ../../src/server/cookies/primitives/$cookie.browser.ts
 /**
 * Creates a browser-side cookie primitive for client-side cookie management.
@@ -56,7 +150,7 @@ var CookieParser = class {
 * class ClientCookies {
 *   preferences = $cookie({
 *     name: "user-prefs",
-*     schema: t.object({ theme: t.text(), language: t.text() }),
+*     schema: z.object({ theme: z.text(), language: z.text() }),
 *     ttl: [30, "days"]
 *   });
 *
@@ -148,9 +242,13 @@ $cookie[KIND] = BrowserCookiePrimitive;
 const AlephaServerCookies = $module({
 	name: "alepha.server.cookies",
 	primitives: [],
-	services: [AlephaServer]
+	services: [
+		AlephaServer,
+		CookieParser,
+		AtomCookiePersistence
+	]
 });
 //#endregion
-export { $cookie, AlephaServerCookies, BrowserCookiePrimitive };
+export { $cookie, AlephaServerCookies, AtomCookiePersistence, BrowserCookiePrimitive };
 
 //# sourceMappingURL=index.browser.js.map

package/dist/server/cookies/index.browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.browser.js","names":[],"sources":["../../../src/server/cookies/services/CookieParser.ts","../../../src/server/cookies/primitives/$cookie.browser.ts","../../../src/server/cookies/index.browser.ts"],"sourcesContent":["import type { Cookie } from \"../primitives/$cookie.ts\";\n\nexport class CookieParser {\n  public parseRequestCookies(header: string): Record<string, string> {\n    const cookies: Record<string, string> = {};\n    const parts = header.split(\";\");\n    for (const part of parts) {\n      const eqIndex = part.indexOf(\"=\");\n      if (eqIndex === -1) {\n        continue;\n      }\n\n      const key = part.slice(0, eqIndex).trim();\n      const value = part.slice(eqIndex + 1).trim();\n\n      if (!key || !value) {\n        continue;\n      }\n\n      cookies[key] = value;\n    }\n\n    return cookies;\n  }\n\n  public serializeResponseCookies(\n    cookies: Record<string, Cookie | null>,\n    isHttps: boolean,\n  ): string[] {\n    const headers = [];\n\n    for (const [name, cookie] of Object.entries(cookies)) {\n      // If the cookie is null, we need to delete it\n      if (cookie == null) {\n        headers.push(`${name}=; Path=/; Max-Age=0`);\n        continue;\n      }\n\n      if (!cookie.value) {\n        continue;\n      }\n\n      headers.push(this.cookieToString(name, cookie, isHttps));\n    }\n\n    return headers;\n  }\n\n  public cookieToString(\n    name: string,\n    cookie: Cookie,\n    isHttps?: boolean,\n  ): string {\n    const parts: string[] = [];\n\n    parts.push(`${name}=${cookie.value}`);\n\n    if (cookie.path) {\n      parts.push(`Path=${cookie.path}`);\n    }\n    if (cookie.maxAge) {\n      parts.push(`Max-Age=${cookie.maxAge}`);\n    }\n    if (cookie.secure !== false && isHttps) {\n      parts.push(\"Secure\");\n    }\n    if (cookie.httpOnly) {\n      parts.push(\"HttpOnly\");\n    }\n    if (cookie.sameSite) {\n      parts.push(`SameSite=${cookie.sameSite}`);\n    }\n    if (cookie.domain) {\n      parts.push(`Domain=${cookie.domain}`);\n    }\n\n    return parts.join(\"; \");\n  }\n}\n","import {\n  $inject,\n  Alepha,\n  AlephaError,\n  createPrimitive,\n  KIND,\n  Primitive,\n  type Static,\n  type TSchema,\n} from \"alepha\";\nimport { DateTimeProvider } from \"alepha/datetime\";\nimport { CookieParser } from \"../services/CookieParser.ts\";\nimport type {\n  AbstractCookiePrimitive,\n  Cookie,\n  CookiePrimitiveOptions,\n  Cookies,\n} from \"./$cookie.ts\";\n\n/**\n * Creates a browser-side cookie primitive for client-side cookie management.\n *\n * Browser-specific version of $cookie that uses document.cookie API. Supports type-safe\n * cookie operations with schema validation but excludes encryption/signing (use server-side\n * $cookie for secure operations).\n *\n * **Note**: This is the browser version - encryption, signing, and compression are not supported.\n *\n * @example\n * ```ts\n * class ClientCookies {\n *   preferences = $cookie({\n *     name: \"user-prefs\",\n *     schema: t.object({ theme: t.text(), language: t.text() }),\n *     ttl: [30, \"days\"]\n *   });\n *\n *   savePreferences() {\n *     this.preferences.set({ theme: \"dark\", language: \"en\" });\n *   }\n *\n *   getPreferences() {\n *     return this.preferences.get() ?? { theme: \"light\", language: \"en\" };\n *   }\n * }\n * ```\n */\nexport const $cookie = <T extends TSchema>(\n  options: CookiePrimitiveOptions<T>,\n  extendedOptions?: Omit<CookiePrimitiveOptions<T>, \"schema\">,\n): AbstractCookiePrimitive<T> => {\n  if (extendedOptions) {\n    options = {\n      key: options.key,\n      schema: options.schema,\n      ...extendedOptions,\n    };\n  }\n  return createPrimitive(BrowserCookiePrimitive<T>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class BrowserCookiePrimitive<T extends TSchema>\n  extends Primitive<CookiePrimitiveOptions<T>>\n  implements AbstractCookiePrimitive<T>\n{\n  protected cookieParser = $inject(CookieParser);\n  protected alepha = $inject(Alepha);\n  protected dateTimeProvider = $inject(DateTimeProvider);\n  protected cookie?: Cookie;\n\n  protected onInit() {\n    if (this.options.key) {\n      this.alepha.events.on(\"state:mutate\", ({ key, value }) => {\n        if (key === this.options.key) {\n          this.set(value);\n        }\n      });\n      this.alepha.events.on(\"configure\", () => {\n        try {\n          const value = this.get();\n          if (value !== undefined) {\n            this.alepha.set(this.options.key as any, value);\n          }\n        } catch {}\n      });\n    }\n  }\n\n  public get schema(): T {\n    return this.options.schema;\n  }\n\n  public get name(): string {\n    return this.options.name ?? `${this.config.propertyKey}`;\n  }\n\n  public set(data: Static<T>): void {\n    const value = JSON.stringify(this.alepha.codec.decode(this.schema, data));\n    const options = this.options;\n\n    if (options.compress) {\n      throw new AlephaError(\"Compression is not supported in browser cookies.\");\n    }\n\n    if (options.encrypt) {\n      throw new AlephaError(\"Encryption is not supported in browser cookies.\");\n    }\n\n    if (options.sign) {\n      throw new AlephaError(\"Signing is not supported in browser cookies.\");\n    }\n\n    const cookie: Cookie = {\n      value: encodeURIComponent(value),\n      path: options.path ?? \"/\",\n      sameSite: options.sameSite ?? \"lax\",\n      secure: false,\n      httpOnly: false,\n      domain: options.domain,\n    };\n\n    if (options.ttl) {\n      cookie.maxAge = this.dateTimeProvider.duration(options.ttl).as(\"seconds\");\n    }\n\n    // biome-ignore lint/suspicious/noDocumentCookie: ...\n    document.cookie = this.cookieParser.cookieToString(this.name, cookie);\n  }\n\n  public get(options?: { cookies?: Cookies }): Static<T> | undefined {\n    const cookie = this.cookieParser.parseRequestCookies(document.cookie)[\n      this.name\n    ];\n    if (!cookie) {\n      return undefined;\n    }\n\n    const rawValue = decodeURIComponent(cookie);\n\n    if (this.options.compress) {\n      throw new AlephaError(\"Compression is not supported in browser cookies.\");\n    }\n\n    if (this.options.encrypt) {\n      throw new AlephaError(\"Encryption is not supported in browser cookies.\");\n    }\n\n    if (this.options.sign) {\n      throw new AlephaError(\"Signing is not supported in browser cookies.\");\n    }\n\n    return this.alepha.codec.decode(this.schema, JSON.parse(rawValue));\n  }\n\n  public del(): void {\n    const options = this.options;\n    const cookie: Cookie = {\n      value: \"\",\n      path: options.path ?? \"/\",\n      sameSite: options.sameSite ?? \"lax\",\n      secure: false,\n      httpOnly: false,\n      domain: options.domain,\n      maxAge: 0, // Set maxAge to 0 to delete the cookie\n    };\n\n    // biome-ignore lint/suspicious/noDocumentCookie: ...\n    document.cookie = this.cookieParser.cookieToString(this.name, cookie);\n  }\n}\n\n$cookie[KIND] = BrowserCookiePrimitive;\n","import { $module } from \"alepha\";\nimport { AlephaServer } from \"alepha/server\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$cookie.browser.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport const AlephaServerCookies = $module({\n  name: \"alepha.server.cookies\",\n  primitives: [],\n  services: [AlephaServer],\n});\n"],"mappings":"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"}
+{"version":3,"file":"index.browser.js","names":[],"sources":["../../../src/server/cookies/services/CookieParser.ts","../../../src/server/cookies/providers/AtomCookiePersistence.browser.ts","../../../src/server/cookies/primitives/$cookie.browser.ts","../../../src/server/cookies/index.browser.ts"],"sourcesContent":["import type { Cookie } from \"../primitives/$cookie.ts\";\n\nexport class CookieParser {\n  public parseRequestCookies(header: string): Record<string, string> {\n    const cookies: Record<string, string> = {};\n    const parts = header.split(\";\");\n    for (const part of parts) {\n      const eqIndex = part.indexOf(\"=\");\n      if (eqIndex === -1) {\n        continue;\n      }\n\n      const key = part.slice(0, eqIndex).trim();\n      const value = part.slice(eqIndex + 1).trim();\n\n      if (!key || !value) {\n        continue;\n      }\n\n      cookies[key] = value;\n    }\n\n    return cookies;\n  }\n\n  public serializeResponseCookies(\n    cookies: Record<string, Cookie | null>,\n    isHttps: boolean,\n  ): string[] {\n    const headers = [];\n\n    for (const [name, cookie] of Object.entries(cookies)) {\n      // If the cookie is null, we need to delete it\n      if (cookie == null) {\n        headers.push(`${name}=; Path=/; Max-Age=0`);\n        continue;\n      }\n\n      if (!cookie.value) {\n        continue;\n      }\n\n      headers.push(this.cookieToString(name, cookie, isHttps));\n    }\n\n    return headers;\n  }\n\n  public cookieToString(\n    name: string,\n    cookie: Cookie,\n    isHttps?: boolean,\n  ): string {\n    const parts: string[] = [];\n\n    parts.push(`${name}=${cookie.value}`);\n\n    if (cookie.path) {\n      parts.push(`Path=${cookie.path}`);\n    }\n    // `!= null`, not truthy: `maxAge: 0` is the standard \"delete this\n    // cookie now\" value (used by AtomCookiePersistence.browser.ts's\n    // clearCookie() and BrowserCookiePrimitive.del()). A truthy check would\n    // silently drop `Max-Age` for exactly that value, turning a deletion\n    // into a plain (non-expiring-until-session-end) write.\n    if (cookie.maxAge != null) {\n      parts.push(`Max-Age=${cookie.maxAge}`);\n    }\n    if (cookie.secure !== false && isHttps) {\n      parts.push(\"Secure\");\n    }\n    if (cookie.httpOnly) {\n      parts.push(\"HttpOnly\");\n    }\n    if (cookie.sameSite) {\n      parts.push(`SameSite=${cookie.sameSite}`);\n    }\n    if (cookie.domain) {\n      parts.push(`Domain=${cookie.domain}`);\n    }\n\n    return parts.join(\"; \");\n  }\n}\n","import { $hook, $inject, Alepha, type Atom, type State } from \"alepha\";\nimport { DateTimeProvider } from \"alepha/datetime\";\nimport type { Cookie } from \"../primitives/$cookie.ts\";\nimport { CookieParser } from \"../services/CookieParser.ts\";\n\n/**\n * Browser variant of AtomCookiePersistence: reads `document.cookie` for every\n * `persist: \"cookie\"` atom, and writes it back on every mutation.\n *\n * Like the server variant, atoms are resolved from the `StateManager`\n * registry (`alepha.store.listAtoms()`) rather than from a map fed by\n * `state:register` — that event fires once, is never replayed, and\n * `$module.register()` registers `atoms[]` before the module's `services[]`\n * exist, so an event-sourced map would miss every atom declared the\n * documented way. The `configure` hook sweeps everything registered up to\n * boot; `state:register` covers atoms that first register later (lazily, on\n * first read).\n *\n * Cookie names are NOT APP_NAME-prefixed here, because `APP_NAME` is not\n * reachable in the browser: `BuildClientTask` only `define`s\n * `process.env.NODE_ENV` for the client bundle, and the SSR hydration\n * payload (`ReactServerTemplateProvider.buildHydrationData`) only carries\n * registered atom values + router layers — never the raw `env` store key.\n * The server variant (`AtomCookiePersistence.ts`) matches this by passing\n * `prefix: false` to `ServerCookiesProvider`, specifically for atom-cookie\n * traffic — every other server cookie ($cookie primitive) still gets the\n * APP_NAME namespace. See `ServerCookiesProvider.prefixName`.\n */\nexport class AtomCookiePersistence {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly cookieParser = $inject(CookieParser);\n  protected readonly dateTime = $inject(DateTimeProvider);\n\n  protected readonly onConfigure = $hook({\n    on: \"configure\",\n    handler: () => {\n      for (const atom of this.cookieAtoms()) {\n        this.read(atom);\n      }\n    },\n  });\n\n  protected readonly onRegister = $hook({\n    on: \"state:register\",\n    handler: ({ atom }) => {\n      if (atom.options.persist !== \"cookie\") {\n        return;\n      }\n      this.read(atom);\n    },\n  });\n\n  protected readonly onMutate = $hook({\n    on: \"state:mutate\",\n    handler: ({ key, value }) => {\n      const atom = this.alepha.store.getAtom(String(key));\n      if (!atom || atom.options.persist !== \"cookie\") {\n        return;\n      }\n\n      if (value === undefined) {\n        // Without this branch, `store.del(atom)` would write the literal\n        // string \"undefined\", and the next read's `JSON.parse(\"undefined\")`\n        // would throw into the catch in `read()` on every page load.\n        this.clearCookie(atom.key);\n        return;\n      }\n\n      const cookie: Cookie = {\n        value: encodeURIComponent(JSON.stringify(value)),\n        path: \"/\",\n        sameSite: \"lax\",\n        maxAge: this.dateTime.duration([365, \"days\"]).as(\"seconds\"),\n      };\n      // biome-ignore lint/suspicious/noDocumentCookie: cookie persistence adapter\n      document.cookie = this.cookieParser.cookieToString(atom.key, cookie);\n    },\n  });\n\n  /**\n   * Every registered atom declared with `persist: \"cookie\"`, read live from\n   * the state manager's registry.\n   */\n  protected cookieAtoms(): Array<Atom<any, any>> {\n    return this.alepha.store\n      .listAtoms()\n      .filter((atom) => atom.options.persist === \"cookie\");\n  }\n\n  /**\n   * Seed an atom's state from `document.cookie`, if a cookie exists for it.\n   * Idempotent: re-reading an atom that already holds the cookie's value is\n   * a no-op write of the same data.\n   */\n  protected read(atom: Atom<any, any>): void {\n    const raw = this.cookieParser.parseRequestCookies(document.cookie)[\n      atom.key\n    ];\n    if (!raw) {\n      return;\n    }\n\n    try {\n      this.alepha.store.set(\n        atom.key as keyof State,\n        JSON.parse(decodeURIComponent(raw)),\n        { skipEvents: true },\n      );\n    } catch {\n      // Corrupted cookie (invalid JSON/encoding, or a value that no longer\n      // matches the atom's schema — `store.set` validates against it) —\n      // clear it instead of leaving it to keep throwing on every future\n      // read. Mirrors the web-storage adapter's parity\n      // (StateManager.bindWebStorage removes the bad entry too).\n      this.clearCookie(atom.key);\n    }\n  }\n\n  /**\n   * Expire a cookie immediately, mirroring\n   * `ServerCookiesProvider.deleteCookie`'s `Max-Age=0` semantics.\n   */\n  protected clearCookie(name: string): void {\n    const cookie: Cookie = {\n      value: \"\",\n      path: \"/\",\n      sameSite: \"lax\",\n      maxAge: 0,\n    };\n    // biome-ignore lint/suspicious/noDocumentCookie: cookie persistence adapter\n    document.cookie = this.cookieParser.cookieToString(name, cookie);\n  }\n}\n","import {\n  $inject,\n  Alepha,\n  AlephaError,\n  createPrimitive,\n  KIND,\n  Primitive,\n  type Static,\n  type TSchema,\n} from \"alepha\";\nimport { DateTimeProvider } from \"alepha/datetime\";\nimport { CookieParser } from \"../services/CookieParser.ts\";\nimport type {\n  AbstractCookiePrimitive,\n  Cookie,\n  CookiePrimitiveOptions,\n  Cookies,\n} from \"./$cookie.ts\";\n\n/**\n * Creates a browser-side cookie primitive for client-side cookie management.\n *\n * Browser-specific version of $cookie that uses document.cookie API. Supports type-safe\n * cookie operations with schema validation but excludes encryption/signing (use server-side\n * $cookie for secure operations).\n *\n * **Note**: This is the browser version - encryption, signing, and compression are not supported.\n *\n * @example\n * ```ts\n * class ClientCookies {\n *   preferences = $cookie({\n *     name: \"user-prefs\",\n *     schema: z.object({ theme: z.text(), language: z.text() }),\n *     ttl: [30, \"days\"]\n *   });\n *\n *   savePreferences() {\n *     this.preferences.set({ theme: \"dark\", language: \"en\" });\n *   }\n *\n *   getPreferences() {\n *     return this.preferences.get() ?? { theme: \"light\", language: \"en\" };\n *   }\n * }\n * ```\n */\nexport const $cookie = <T extends TSchema>(\n  options: CookiePrimitiveOptions<T>,\n  extendedOptions?: Omit<CookiePrimitiveOptions<T>, \"schema\">,\n): AbstractCookiePrimitive<T> => {\n  if (extendedOptions) {\n    options = {\n      key: options.key,\n      schema: options.schema,\n      ...extendedOptions,\n    };\n  }\n  return createPrimitive(BrowserCookiePrimitive<T>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class BrowserCookiePrimitive<T extends TSchema>\n  extends Primitive<CookiePrimitiveOptions<T>>\n  implements AbstractCookiePrimitive<T>\n{\n  protected cookieParser = $inject(CookieParser);\n  protected alepha = $inject(Alepha);\n  protected dateTimeProvider = $inject(DateTimeProvider);\n  protected cookie?: Cookie;\n\n  protected onInit() {\n    if (this.options.key) {\n      this.alepha.events.on(\"state:mutate\", ({ key, value }) => {\n        if (key === this.options.key) {\n          this.set(value);\n        }\n      });\n      this.alepha.events.on(\"configure\", () => {\n        try {\n          const value = this.get();\n          if (value !== undefined) {\n            this.alepha.set(this.options.key as any, value);\n          }\n        } catch {}\n      });\n    }\n  }\n\n  public get schema(): T {\n    return this.options.schema;\n  }\n\n  public get name(): string {\n    return this.options.name ?? `${this.config.propertyKey}`;\n  }\n\n  public set(data: Static<T>): void {\n    const value = JSON.stringify(this.alepha.codec.decode(this.schema, data));\n    const options = this.options;\n\n    if (options.compress) {\n      throw new AlephaError(\"Compression is not supported in browser cookies.\");\n    }\n\n    if (options.encrypt) {\n      throw new AlephaError(\"Encryption is not supported in browser cookies.\");\n    }\n\n    if (options.sign) {\n      throw new AlephaError(\"Signing is not supported in browser cookies.\");\n    }\n\n    const cookie: Cookie = {\n      value: encodeURIComponent(value),\n      path: options.path ?? \"/\",\n      sameSite: options.sameSite ?? \"lax\",\n      secure: false,\n      httpOnly: false,\n      domain: options.domain,\n    };\n\n    if (options.ttl) {\n      cookie.maxAge = this.dateTimeProvider.duration(options.ttl).as(\"seconds\");\n    }\n\n    // biome-ignore lint/suspicious/noDocumentCookie: ...\n    document.cookie = this.cookieParser.cookieToString(this.name, cookie);\n  }\n\n  public get(options?: { cookies?: Cookies }): Static<T> | undefined {\n    const cookie = this.cookieParser.parseRequestCookies(document.cookie)[\n      this.name\n    ];\n    if (!cookie) {\n      return undefined;\n    }\n\n    const rawValue = decodeURIComponent(cookie);\n\n    if (this.options.compress) {\n      throw new AlephaError(\"Compression is not supported in browser cookies.\");\n    }\n\n    if (this.options.encrypt) {\n      throw new AlephaError(\"Encryption is not supported in browser cookies.\");\n    }\n\n    if (this.options.sign) {\n      throw new AlephaError(\"Signing is not supported in browser cookies.\");\n    }\n\n    return this.alepha.codec.decode(this.schema, JSON.parse(rawValue));\n  }\n\n  public del(): void {\n    const options = this.options;\n    const cookie: Cookie = {\n      value: \"\",\n      path: options.path ?? \"/\",\n      sameSite: options.sameSite ?? \"lax\",\n      secure: false,\n      httpOnly: false,\n      domain: options.domain,\n      maxAge: 0, // Set maxAge to 0 to delete the cookie\n    };\n\n    // biome-ignore lint/suspicious/noDocumentCookie: ...\n    document.cookie = this.cookieParser.cookieToString(this.name, cookie);\n  }\n}\n\n$cookie[KIND] = BrowserCookiePrimitive;\n","import { $module } from \"alepha\";\nimport { AlephaServer } from \"alepha/server\";\nimport { AtomCookiePersistence } from \"./providers/AtomCookiePersistence.browser.ts\";\nimport { CookieParser } from \"./services/CookieParser.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$cookie.browser.ts\";\nexport * from \"./providers/AtomCookiePersistence.browser.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport const AlephaServerCookies = $module({\n  name: \"alepha.server.cookies\",\n  primitives: [],\n  services: [AlephaServer, CookieParser, AtomCookiePersistence],\n});\n"],"mappings":"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"}

package/dist/server/cookies/index.d.ts

@@ -1,7 +1,6 @@
-import { Alepha, KIND, Primitive, Static, TSchema } from "alepha";
+import { Alepha, Atom, KIND, Primitive, Static, TSchema } from "alepha";
 import { SecretProvider } from "alepha/crypto";
 import { DateTimeProvider, DurationLike } from "alepha/datetime";
-
 //#region ../../src/server/cookies/services/CookieParser.d.ts
 declare class CookieParser {
   parseRequestCookies(header: string): Record<string, string>;
@@ -24,9 +23,29 @@ declare class ServerCookiesProvider {
   readonly onAction: import("alepha").HookPrimitive<"action:onRequest">;
   readonly onSend: import("alepha").HookPrimitive<"server:onSend">;
   protected getCookiesFromContext(cookies?: Cookies): Cookies;
+  /**
+   * Namespaces a cookie name with the app's `APP_NAME` (lowercased) so that
+   * two Alepha apps sharing a cookie jar do not collide.
+   *
+   * Cookies are scoped by host + path only — never by port — so two apps on
+   * `localhost:3000` and `localhost:4000` would otherwise both read/write a
+   * cookie literally named `tokens` and silently clobber each other (and,
+   * because each encrypts with its own `APP_SECRET`, the foreign cookie fails
+   * to decrypt and gets deleted, logging the user out).
+   *
+   * When `APP_NAME` is unset the name is returned unchanged, so existing
+   * single-app deployments keep their current cookie names. Same convention as
+   * the `APP_NAME` prefix used by R2 storage and server-timing.
+   *
+   * Pass `prefix = false` to skip the namespace entirely — used for
+   * `persist: "cookie"` atoms, whose browser-side counterpart cannot see
+   * `APP_NAME` and therefore always uses the bare name. See
+   * `CookiePrimitiveOptions.prefix`.
+   */
+  protected prefixName(name: string, prefix?: boolean): string;
   getCookie<T extends TSchema>(name: string, options: CookiePrimitiveOptions<T>, contextCookies?: Cookies): Static<T> | undefined;
   setCookie<T extends TSchema>(name: string, options: CookiePrimitiveOptions<T>, data: Static<T>, contextCookies?: Cookies): void;
-  deleteCookie<T extends TSchema>(name: string, contextCookies?: Cookies): void;
+  deleteCookie<T extends TSchema>(name: string, contextCookies?: Cookies, prefix?: boolean): void;
   protected encrypt(text: string): string;
   protected decrypt(encryptedText: string): string;
   /**
@@ -96,6 +115,21 @@ interface CookiePrimitiveOptions<T extends TSchema> {
    * Optional key to link this cookie to an Atom, enabling automatic synchronization between the cookie and the Atom's state.
    */
   key?: string;
+  /**
+   * Internal escape hatch: when explicitly set to `false`, the server skips
+   * the `APP_NAME` cookie-name namespace applied by
+   * `ServerCookiesProvider.prefixName()`.
+   *
+   * Used by `AtomCookiePersistence` so the cookie name the server
+   * reads/writes for a `persist: "cookie"` atom matches the bare name its
+   * browser variant uses — `APP_NAME` is not reachable client-side (not
+   * baked into the client bundle, not part of SSR hydration), so the
+   * browser can only ever use the bare atom key.
+   *
+   * Application code declaring `$cookie(...)` directly should leave this
+   * unset — it defaults to `true` (prefixed), matching every other cookie.
+   */
+  prefix?: boolean;
 }
 interface AbstractCookiePrimitive<T extends TSchema> {
   readonly name: string;
@@ -150,6 +184,54 @@ interface Cookie {
   domain?: string;
 }
 //#endregion
+//#region ../../src/server/cookies/providers/AtomCookiePersistence.d.ts
+/**
+ * Binds every atom declared with `persist: "cookie"` to an HTTP cookie.
+ *
+ * - `server:onRequest` — seeds the request-scoped state from the cookie, so
+ *   SSR renders with the persisted value.
+ * - `state:mutate` — writes the new value back as a Set-Cookie header.
+ * - `state:register` — an atom registering lazily *during* a request (first
+ *   touched by an SSR render, after `server:onRequest` already ran) reads
+ *   its cookie right away, so that render still sees the persisted value.
+ *
+ * Atoms are resolved from the `StateManager` registry
+ * (`alepha.store.listAtoms()`) on every request and every mutation, never
+ * from a map built up from `state:register` events. That event fires exactly
+ * once per atom and is never replayed, while `$module.register()` registers
+ * `atoms[]` BEFORE it wires `imports[]` and injects `services[]` — so the
+ * documented `$module({ atoms, imports: [AlephaServerCookies], services })`
+ * shape registers every atom before this provider exists. An event-sourced
+ * map would stay empty forever there, making `persist: "cookie"` a silent
+ * no-op in both directions. Reading the registry on demand is
+ * order-independent.
+ *
+ * The cookie is named after the atom key, lives 365 days, SameSite=lax,
+ * path "/". For custom cookie options (encryption, signing, custom TTL),
+ * declare an explicit `$cookie({ key: atom.key, ... })` binding instead.
+ */
+declare class AtomCookiePersistence {
+  protected readonly alepha: Alepha;
+  protected readonly log: import("alepha/logger").Logger;
+  protected readonly serverCookies: ServerCookiesProvider;
+  protected readonly onRequest: import("alepha").HookPrimitive<"server:onRequest">;
+  protected readonly onRegister: import("alepha").HookPrimitive<"state:register">;
+  protected readonly onMutate: import("alepha").HookPrimitive<"state:mutate">;
+  /**
+   * Every registered atom declared with `persist: "cookie"`, read live from
+   * the state manager's registry.
+   */
+  protected cookieAtoms(): Array<Atom<any, any>>;
+  protected read(atom: Atom<any, any>, cookies?: Cookies): void;
+  protected cookieOptions(atom: Atom<any, any>): {
+    schema: any;
+    path: string;
+    sameSite: "lax";
+    ttl: DurationLike;
+    prefix: boolean;
+  };
+}
+//#endregion
 //#region ../../src/server/cookies/index.d.ts
 declare module "alepha/server" {
   interface ServerRequest {
@@ -166,5 +248,5 @@ declare module "alepha/server" {
  */
 declare const AlephaServerCookies: import("alepha").Service<import("alepha").Module>;
 //#endregion
-export { $cookie, AbstractCookiePrimitive, AlephaServerCookies, Cookie, CookiePrimitive, CookiePrimitiveOptions, Cookies, ServerCookiesProvider };
+export { $cookie, AbstractCookiePrimitive, AlephaServerCookies, AtomCookiePersistence, Cookie, CookiePrimitive, CookiePrimitiveOptions, Cookies, ServerCookiesProvider };
 //# sourceMappingURL=index.d.ts.map

package/dist/server/cookies/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/server/cookies/services/CookieParser.ts","../../../src/server/cookies/providers/ServerCookiesProvider.ts","../../../src/server/cookies/primitives/$cookie.ts","../../../src/server/cookies/index.ts"],"mappings":";;;;;cAEa,YAAA;EACJ,mBAAA,CAAoB,MAAA,WAAiB,MAAA;EAsBrC,wBAAA,CACL,OAAA,EAAS,MAAA,SAAe,MAAA,UACxB,OAAA;EAqBK,cAAA,CACL,IAAA,UACA,MAAA,EAAQ,MAAA,EACR,OAAA;AAAA;;;cCxBS,qBAAA;EAAA,mBACQ,MAAA,EAAM,MAAA;EAAA,mBACN,GAAA,0BAAG,MAAA;EAAA,mBACH,YAAA,EAAY,YAAA;EAAA,mBACZ,gBAAA,EAAgB,gBAAA;EAAA,mBAChB,cAAA,EAAc,cAAA;EAAA,mBAGd,SAAA;EAAA,mBACA,SAAA;EAAA,mBACA,eAAA;EAAA,mBACA,gBAAA;EAAA,SAEH,SAAA,mBAAS,aAAA;EAAA,SAYT,QAAA,mBAAQ,aAAA;EAAA,SAYR,MAAA,mBAAM,aAAA;EAAA,UAeZ,qBAAA,CAAsB,OAAA,GAAU,OAAA,GAAU,OAAA;EAW7C,SAAA,WAAoB,OAAA,EACzB,IAAA,UACA,OAAA,EAAS,sBAAA,CAAuB,CAAA,GAChC,cAAA,GAAiB,OAAA,GAChB,MAAA,CAAO,CAAA;EA6CH,SAAA,WAAoB,OAAA,EACzB,IAAA,UACA,OAAA,EAAS,sBAAA,CAAuB,CAAA,GAChC,IAAA,EAAM,MAAA,CAAO,CAAA,GACb,cAAA,GAAiB,OAAA;EAoCZ,YAAA,WAAuB,OAAA,EAC5B,IAAA,UACA,cAAA,GAAiB,OAAA;EAAA,UAQT,OAAA,CAAQ,IAAA;EAAA,UAWR,OAAA,CAAQ,aAAA;EDtJR;;;;EAAA,UC+KA,SAAA,IAAa,MAAA;EAAA,UAIb,IAAA,CAAK,IAAA;AAAA;;;;;ADnOjB;;;cEca,OAAA;EAAA,WAAqB,OAAA,EAAO,OAAA,EAC9B,sBAAA,CAAuB,CAAA,GAAE,eAAA,GAChB,IAAA,CAAK,sBAAA,CAAuB,CAAA,eAC7C,uBAAA,CAAwB,CAAA;EAAA;;UAaV,sBAAA,WAAiC,OAAA;EFkBhC;;;EEdhB,MAAA,EAAQ,CAAA;EFXD;;;EEgBP,IAAA;EFdE;;;EEmBF,IAAA;EFIE;;;EECF,GAAA,GAAM,YAAA;;;;EAKN,MAAA;ED7BgC;;;ECkChC,QAAA;ED9BmC;;;ECmCnC,QAAA;EDwB2B;;;ECnB3B,MAAA;EDuBU;;;EClBV,QAAA;EDiEW;;;EC5DX,OAAA;EDkG8B;;;EC7F9B,IAAA;ED2I6B;;;ECtI7B,GAAA;AAAA;AAAA,UAGe,uBAAA,WAAkC,OAAA;EAAA,SACxC,IAAA;EAAA,SACA,OAAA,EAAS,sBAAA,CAAuB,CAAA;EACzC,GAAA,CACE,KAAA,EAAO,MAAA,CAAO,CAAA,GACd,OAAA;IAAY,OAAA,GAAU,OAAA;IAAS,GAAA,GAAM,YAAA;EAAA;EAEvC,GAAA,CAAI,OAAA;IAAY,OAAA,GAAU,OAAA;EAAA,IAAY,MAAA,CAAO,CAAA;EAC7C,GAAA,CAAI,OAAA;IAAY,OAAA,GAAU,OAAA;EAAA;AAAA;AAAA,cAGf,eAAA,WAA0B,OAAA,UAC7B,SAAA,CAAU,sBAAA,CAAuB,CAAA,cAC9B,uBAAA,CAAwB,CAAA;EAAA,mBAEhB,qBAAA,EAAqB,qBAAA;EAAA,UAE9B,MAAA;EAAA,IAoBC,MAAA,IAAU,CAAA;EAAA,IAIV,IAAA;EDxDyC;;;EC+D7C,GAAA,CACL,KAAA,EAAO,MAAA,CAAO,CAAA,GACd,OAAA;IAAY,OAAA,GAAU,OAAA;IAAS,GAAA,GAAM,YAAA;EAAA;EDpDrC;;;ECoEK,GAAA,CAAI,OAAA;IAAY,OAAA,GAAU,OAAA;EAAA,IAAY,MAAA,CAAO,CAAA;EDrBnC;;;ECgCV,GAAA,CAAI,OAAA;IAAY,OAAA,GAAU,OAAA;EAAA;AAAA;AAAA,UASlB,OAAA;EACf,GAAA,EAAK,MAAA;EACL,GAAA,EAAK,MAAA,SAAe,MAAA;AAAA;AAAA,UAGL,MAAA;EACf,KAAA;EACA,IAAA;EACA,MAAA;EACA,MAAA;EACA,QAAA;EACA,QAAA;EACA,MAAA;AAAA;;;;YClLU,aAAA;IACR,OAAA,EAAS,OAAO;EAAA;AAAA;;;;;;;;;cAYP,mBAAA,mBAAmB,OAAA,kBAAA,MAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/server/cookies/services/CookieParser.ts","../../../src/server/cookies/providers/ServerCookiesProvider.ts","../../../src/server/cookies/primitives/$cookie.ts","../../../src/server/cookies/providers/AtomCookiePersistence.ts","../../../src/server/cookies/index.ts"],"mappings":";;;;cAEa;EACJ,oBAAoB,iBAAiB;EAsBrC,yBACL,SAAS,eAAe,gBACxB;EAqBK,eACL,cACA,QAAQ,QACR;;;;cCxBS;qBACQ,QAAM;qBACN,6BAAG;qBACH,cAAY;qBACZ,kBAAgB;qBAChB,gBAAc;qBAGd;qBACA;qBACA;qBACA;WAEH,4BAAS;WAYT,2BAAQ;WAYR,yBAAM;YAeZ,sBAAsB,UAAU,UAAU;;;;;;;;;;;;;;;;;;;;YA8B1C,WAAW,cAAc;EAO5B,UAAU,UAAU,SACzB,cACA,SAAS,uBAAuB,IAChC,iBAAiB,UAChB,OAAO;EA8CH,UAAU,UAAU,SACzB,cACA,SAAS,uBAAuB,IAChC,MAAM,OAAO,IACb,iBAAiB;EAoCZ,aAAa,UAAU,SAC5B,cACA,iBAAiB,SACjB;YAQQ,QAAQ;YAWR,QAAQ;;;;;YAyBR,aAAa;YAIb,KAAK;;;;;;;;;cCjPJ;GAAW,UAAU,SAAO,SAC9B,uBAAuB,IAAE,kBAChB,KAAK,uBAAuB,gBAC7C,wBAAwB;;;UAaV,uBAAuB,UAAU;;;;EAIhD,QAAQ;;;;EAKR;;;;EAKA;;;;EAKA,MAAM;;;;EAKN;;;;EAKA;;;;EAKA;;;;EAKA;;;;EAKA;;;;EAKA;;;;EAKA;;;;EAKA;;;;;;;;;;;;;;;EAgBA;;UAGe,wBAAwB,UAAU;WACxC;WACA,SAAS,uBAAuB;EACzC,IACE,OAAO,OAAO,IACd;IAAY,UAAU;IAAS,MAAM;;EAEvC,IAAI;IAAY,UAAU;MAAY,OAAO;EAC7C,IAAI;IAAY,UAAU;;;cAGf,gBAAgB,UAAU,iBAC7B,UAAU,uBAAuB,eAC9B,wBAAwB;qBAEhB,uBAAqB;YAE9B;MAoBC,UAAU;MAIV;;;;EAOJ,IACL,OAAO,OAAO,IACd;IAAY,UAAU;IAAS,MAAM;;;;;EAgBhC,IAAI;IAAY,UAAU;MAAY,OAAO;;;;EAW7C,IAAI;IAAY,UAAU;;;UASlB;EACf,KAAK;EACL,KAAK,eAAe;;UAGL;EACf;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cCjLW;qBACQ,QAAM;qBACN,6BAAG;qBACH,eAAa;qBAEb,4BAAS;qBAmBT,6BAAU;qBAeV,2BAAQ;;;;;YAwBjB,eAAe,MAAM;YAMrB,KAAK,MAAM,gBAAgB,UAAU;YA+BrC,cAAc,MAAM;IAE1B;IACA;IACA;IACA,KAAsB;IAQtB;;;;;;YChIM;IACR,SAAS;;;;;;;;;;;cAYA,sCAAmB,yBAAA"}

package/dist/server/cookies/index.js

@@ -36,7 +36,7 @@ var CookieParser = class {
 		const parts = [];
 		parts.push(`${name}=${cookie.value}`);
 		if (cookie.path) parts.push(`Path=${cookie.path}`);
-		if (cookie.maxAge) parts.push(`Max-Age=${cookie.maxAge}`);
+		if (cookie.maxAge != null) parts.push(`Max-Age=${cookie.maxAge}`);
 		if (cookie.secure !== false && isHttps) parts.push("Secure");
 		if (cookie.httpOnly) parts.push("HttpOnly");
 		if (cookie.sameSite) parts.push(`SameSite=${cookie.sameSite}`);
@@ -89,9 +89,35 @@ var ServerCookiesProvider = class {
 		if (contextCookies) return contextCookies;
 		throw new AlephaError("Cookie context is not available. This method must be called within a server request cycle.");
 	}
+	/**
+	* Namespaces a cookie name with the app's `APP_NAME` (lowercased) so that
+	* two Alepha apps sharing a cookie jar do not collide.
+	*
+	* Cookies are scoped by host + path only — never by port — so two apps on
+	* `localhost:3000` and `localhost:4000` would otherwise both read/write a
+	* cookie literally named `tokens` and silently clobber each other (and,
+	* because each encrypts with its own `APP_SECRET`, the foreign cookie fails
+	* to decrypt and gets deleted, logging the user out).
+	*
+	* When `APP_NAME` is unset the name is returned unchanged, so existing
+	* single-app deployments keep their current cookie names. Same convention as
+	* the `APP_NAME` prefix used by R2 storage and server-timing.
+	*
+	* Pass `prefix = false` to skip the namespace entirely — used for
+	* `persist: "cookie"` atoms, whose browser-side counterpart cannot see
+	* `APP_NAME` and therefore always uses the bare name. See
+	* `CookiePrimitiveOptions.prefix`.
+	*/
+	prefixName(name, prefix = true) {
+		if (!prefix) return name;
+		const app = this.alepha.env.APP_NAME;
+		if (!app) return name;
+		return `${String(app).toLowerCase()}.${name}`;
+	}
 	getCookie(name, options, contextCookies) {
 		const cookies = this.getCookiesFromContext(contextCookies);
-		let rawValue = cookies.req[name];
+		const prefixed = options.prefix !== false;
+		let rawValue = cookies.req[this.prefixName(name, prefixed)];
 		if (!rawValue) return void 0;
 		try {
 			rawValue = decodeURIComponent(rawValue);
@@ -110,7 +136,7 @@ var ServerCookiesProvider = class {
 			return this.alepha.codec.decode(options.schema, JSON.parse(rawValue));
 		} catch (error) {
 			this.log.warn(`Failed to parse cookie "${name}"`, error);
-			this.deleteCookie(name, cookies);
+			this.deleteCookie(name, cookies, prefixed);
 			return;
 		}
 	}
@@ -129,11 +155,11 @@ var ServerCookiesProvider = class {
 			domain: options.domain
 		};
 		if (options.ttl) cookie.maxAge = this.dateTimeProvider.duration(options.ttl).as("seconds");
-		cookies.res[name] = cookie;
+		cookies.res[this.prefixName(name, options.prefix !== false)] = cookie;
 	}
-	deleteCookie(name, contextCookies) {
+	deleteCookie(name, contextCookies, prefix = true) {
 		const cookies = this.getCookiesFromContext(contextCookies);
-		cookies.res[name] = null;
+		cookies.res[this.prefixName(name, prefix)] = null;
 	}
 	encrypt(text) {
 		const iv = randomBytes(this.IV_LENGTH);
@@ -226,6 +252,92 @@ var CookiePrimitive = class extends Primitive {
 };
 $cookie[KIND] = CookiePrimitive;
 //#endregion
+//#region ../../src/server/cookies/providers/AtomCookiePersistence.ts
+/**
+* Binds every atom declared with `persist: "cookie"` to an HTTP cookie.
+*
+* - `server:onRequest` — seeds the request-scoped state from the cookie, so
+*   SSR renders with the persisted value.
+* - `state:mutate` — writes the new value back as a Set-Cookie header.
+* - `state:register` — an atom registering lazily *during* a request (first
+*   touched by an SSR render, after `server:onRequest` already ran) reads
+*   its cookie right away, so that render still sees the persisted value.
+*
+* Atoms are resolved from the `StateManager` registry
+* (`alepha.store.listAtoms()`) on every request and every mutation, never
+* from a map built up from `state:register` events. That event fires exactly
+* once per atom and is never replayed, while `$module.register()` registers
+* `atoms[]` BEFORE it wires `imports[]` and injects `services[]` — so the
+* documented `$module({ atoms, imports: [AlephaServerCookies], services })`
+* shape registers every atom before this provider exists. An event-sourced
+* map would stay empty forever there, making `persist: "cookie"` a silent
+* no-op in both directions. Reading the registry on demand is
+* order-independent.
+*
+* The cookie is named after the atom key, lives 365 days, SameSite=lax,
+* path "/". For custom cookie options (encryption, signing, custom TTL),
+* declare an explicit `$cookie({ key: atom.key, ... })` binding instead.
+*/
+var AtomCookiePersistence = class {
+	alepha = $inject(Alepha);
+	log = $logger();
+	serverCookies = $inject(ServerCookiesProvider);
+	onRequest = $hook({
+		on: "server:onRequest",
+		after: [this.serverCookies],
+		handler: ({ request }) => {
+			for (const atom of this.cookieAtoms()) this.read(atom, request.cookies);
+		}
+	});
+	onRegister = $hook({
+		on: "state:register",
+		handler: ({ atom }) => {
+			if (atom.options.persist !== "cookie") return;
+			if (this.alepha.store.get("alepha.http.request")) this.read(atom);
+		}
+	});
+	onMutate = $hook({
+		on: "state:mutate",
+		handler: ({ key, value }) => {
+			const atom = this.alepha.store.getAtom(String(key));
+			if (!atom || atom.options.persist !== "cookie") return;
+			try {
+				this.serverCookies.setCookie(atom.key, this.cookieOptions(atom), value);
+			} catch (error) {
+				this.log.debug(`Cannot persist atom "${atom.key}" to cookie`, { error });
+			}
+		}
+	});
+	/**
+	* Every registered atom declared with `persist: "cookie"`, read live from
+	* the state manager's registry.
+	*/
+	cookieAtoms() {
+		return this.alepha.store.listAtoms().filter((atom) => atom.options.persist === "cookie");
+	}
+	read(atom, cookies) {
+		if (!this.alepha.context.exists()) {
+			this.log.debug(`Skipping cookie read for atom "${atom.key}": no active request context.`);
+			return;
+		}
+		try {
+			const value = this.serverCookies.getCookie(atom.key, this.cookieOptions(atom), cookies);
+			if (value !== void 0) this.alepha.store.set(atom.key, value, { skipEvents: true });
+		} catch (error) {
+			this.log.debug(`Cannot read cookie for atom "${atom.key}"`, { error });
+		}
+	}
+	cookieOptions(atom) {
+		return {
+			schema: atom.schema,
+			path: "/",
+			sameSite: "lax",
+			ttl: [365, "days"],
+			prefix: false
+		};
+	}
+};
+//#endregion
 //#region ../../src/server/cookies/index.ts
 /**
 * Server and browser-safe cookie handling.
@@ -241,10 +353,11 @@ const AlephaServerCookies = $module({
 	services: [
 		AlephaServer,
 		ServerCookiesProvider,
-		CookieParser
+		CookieParser,
+		AtomCookiePersistence
 	]
 });
 //#endregion
-export { $cookie, AlephaServerCookies, CookiePrimitive, ServerCookiesProvider };
+export { $cookie, AlephaServerCookies, AtomCookiePersistence, CookiePrimitive, ServerCookiesProvider };
 
 //# sourceMappingURL=index.js.map