@timber-js/app 0.2.0-alpha.100 → 0.2.0-alpha.102

package/dist/_chunks/define-cookie-BjpIt4UC.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"define-cookie-BjpIt4UC.js","names":[],"sources":["../../src/cookies/define-cookie.ts"],"sourcesContent":["/**\n * defineCookie — typed cookie definitions.\n *\n * Bundles name + codec + options into a reusable CookieDefinition<T>\n * with sync .get(), .set(), .delete() isomorphic methods (server + client)\n * and a .useCookie() client hook.\n *\n * Uses the registration pattern: server entry registers serverCookieImpl,\n * client entry registers clientCookieImpl. This avoids top-level value\n * imports from either environment and makes defineCookie isomorphic\n * without `typeof window` checks.\n *\n * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected in\n * the codec option — no explicit fromSchema() wrapper needed.\n *\n * See design/29-cookies.md §\"Typed Cookies with Schema Validation\"\n */\n\nimport type { CookieOptions } from '../server/cookie-context.js';\nimport type { ClientCookieOptions } from '../client/use-cookie.js';\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\nimport type { Codec } from '../codec.js';\nimport type { StandardSchemaV1 } from '../schema-bridge.js';\n\n/**\n * A codec that converts between string cookie values and typed values.\n * Type alias for the shared Codec<T> protocol.\n */\nexport type CookieCodec<T> = Codec<T>;\n\n/** Options for defineCookie: codec + CookieOptions merged. */\nexport interface DefineCookieOptions<T, HttpOnly extends boolean = boolean> extends CookieOptions {\n  /**\n   * Codec for parsing/serializing the cookie value.\n   * Accepts a Codec<T> or a Standard Schema object (Zod, Valibot, ArkType)\n   * which is auto-wrapped via fromSchema.\n   */\n  codec: CookieCodec<T> | StandardSchemaV1<T>;\n  /**\n   * Prevent client-side JS access. Default: true.\n   * When true (or omitted), client methods (useCookie, get/set/delete on\n   * client) are omitted from the return type and throw at runtime.\n   */\n  httpOnly?: HttpOnly;\n}\n\n/**\n * Server-only cookie definition. Returned when httpOnly is true or omitted.\n * Client methods are absent from the type — accessing them is a TS error.\n */\nexport interface ServerOnlyCookieDefinition<T> {\n  readonly name: string;\n  readonly options: CookieOptions;\n  readonly codec: CookieCodec<T>;\n\n  /** Read the typed value. Sync, isomorphic (server + client). */\n  get(): T;\n  /** Set the typed value. Sync, isomorphic (server + client). */\n  set(value: T): void;\n  /** Delete the cookie. Sync, isomorphic (server + client). */\n  delete(): void;\n}\n\n/**\n * Full cookie definition with client methods. Returned when httpOnly: false.\n */\nexport interface CookieDefinition<T> extends ServerOnlyCookieDefinition<T> {\n  /** Client: React hook for reading/writing this cookie. Returns [value, setter, deleter]. */\n  useCookie(): [T, (value: T) => void, () => void];\n}\n\n// ─── Registration Pattern ─────────────────────────────────────────────────\n//\n// Server and client entries register their implementations at module load\n// time. This avoids dynamic imports (which lose ALS context) and typeof\n// window checks (which are fragile).\n\n/** Server-side cookie impl: reads from ALS-backed cookie jar. */\nexport interface ServerCookieImpl {\n  getCookieJar(): {\n    get(name: string): string | undefined;\n    set(name: string, value: string, options?: CookieOptions): void;\n    delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void;\n  };\n}\n\n/** Client-side cookie impl: reads/writes document.cookie via useCookie hook. */\nexport interface ClientCookieImpl {\n  useCookie(\n    name: string,\n    options?: ClientCookieOptions\n  ): [string | undefined, (value: string, options?: ClientCookieOptions) => void, () => void];\n  getCookieValue(name: string): string | undefined;\n  setCookieValue(name: string, value: string, options?: ClientCookieOptions): void;\n  deleteCookieValue(name: string, options?: ClientCookieOptions): void;\n}\n\nlet _serverImpl: ServerCookieImpl | undefined;\nlet _clientImpl: ClientCookieImpl | undefined;\nlet _fromSchemaFn: ((schema: StandardSchemaV1<unknown>) => CookieCodec<unknown>) | undefined;\n\n/**\n * Register the server-side cookie implementation.\n * Called by server entry at module load time.\n * @internal\n */\nexport function _registerServerCookieImpl(impl: ServerCookieImpl): void {\n  _serverImpl = impl;\n}\n\n/**\n * Register the client-side cookie implementation.\n * Called by client entry at module load time.\n * @internal\n */\nexport function _registerClientCookieImpl(impl: ClientCookieImpl): void {\n  _clientImpl = impl;\n}\n\n/**\n * Register the fromSchema bridge function.\n * Called by server/client entry at module load time.\n * @internal\n */\nexport function _registerFromSchema(\n  fn: (schema: StandardSchemaV1<unknown>) => CookieCodec<unknown>\n): void {\n  _fromSchemaFn = fn;\n}\n\n// Legacy registration for useCookie module — still used by client/index.ts\nlet _useCookieModule: typeof import('../client/use-cookie.js') | undefined;\n\nfunction getUseCookieModule(): typeof import('../client/use-cookie.js') {\n  if (!_useCookieModule) {\n    throw new Error(\n      '[timber] defineCookie().useCookie() requires @timber-js/app/client to be loaded. ' +\n        'This hook can only be used in client components.'\n    );\n  }\n  return _useCookieModule;\n}\n\n/**\n * Register the client cookie module. Called by the client entry to wire\n * up the lazy reference without a top-level import.\n *\n * @internal — framework use only\n */\nexport function _registerUseCookieModule(mod: typeof import('../client/use-cookie.js')): void {\n  _useCookieModule = mod;\n  // Also register the client impl from the module\n  _clientImpl = {\n    useCookie: mod.useCookie,\n    getCookieValue: (name: string) => {\n      if (typeof document === 'undefined') return undefined;\n      const match = document.cookie.match(\n        new RegExp('(?:^|;\\\\s*)' + name.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&') + '\\\\s*=\\\\s*([^;]*)')\n      );\n      return match ? decodeURIComponent(match[1]) : undefined;\n    },\n    setCookieValue: (name: string, value: string, options?: ClientCookieOptions) => {\n      const parts: string[] = [`${name}=${encodeURIComponent(value)}`];\n      const path = options?.path ?? '/';\n      parts.push(`Path=${path}`);\n      if (options?.domain) parts.push(`Domain=${options.domain}`);\n      if (options?.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`);\n      if (options?.expires) parts.push(`Expires=${options.expires.toUTCString()}`);\n      const sameSite = options?.sameSite ?? 'lax';\n      parts.push(`SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`);\n      if (options?.secure) parts.push('Secure');\n      document.cookie = parts.join('; ');\n      // Notify useCookie subscribers so mounted hooks re-render\n      mod.notifyCookieChange(name);\n    },\n    deleteCookieValue: (name: string, options?: ClientCookieOptions) => {\n      const path = options?.path ?? '/';\n      const domain = options?.domain;\n      let cookieStr = `${name}=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=${path}`;\n      if (domain) cookieStr += `; Domain=${domain}`;\n      document.cookie = cookieStr;\n      mod.notifyCookieChange(name);\n    },\n  };\n}\n\n// ─── Standard Schema Auto-Detection ───────────────────────────────────────\n\nfunction resolveCodec<T>(codecOrSchema: CookieCodec<T> | StandardSchemaV1<T>): CookieCodec<T> {\n  // If it has parse + serialize, it's already a Codec\n  if (\n    typeof (codecOrSchema as Codec<T>).parse === 'function' &&\n    typeof (codecOrSchema as Codec<T>).serialize === 'function'\n  ) {\n    return codecOrSchema as CookieCodec<T>;\n  }\n\n  // Auto-detect Standard Schema\n  if (typeof codecOrSchema === 'object' && codecOrSchema !== null && '~standard' in codecOrSchema) {\n    if (!_fromSchemaFn) {\n      throw new Error(\n        '[timber] defineCookie: Standard Schema auto-detection requires @timber-js/app/server or ' +\n          '@timber-js/app/client to be loaded. Pass an explicit Codec<T> with parse/serialize methods, ' +\n          'or ensure the framework entry module is imported.'\n      );\n    }\n    return _fromSchemaFn(codecOrSchema as StandardSchemaV1<unknown>) as CookieCodec<T>;\n  }\n\n  throw new Error(\n    '[timber] defineCookie: codec must be a Codec<T> (with parse/serialize methods) ' +\n      'or a Standard Schema object (Zod, Valibot, ArkType).'\n  );\n}\n\n// ─── Factory ──────────────────────────────────────────────────────────────\n\n/**\n * Define a typed cookie.\n *\n * ```ts\n * import { defineCookie } from '@timber-js/app/cookies';\n * import { z } from 'zod/v4';\n *\n * // httpOnly: false — client methods available\n * export const themeCookie = defineCookie('theme', {\n *   codec: z.enum(['light', 'dark', 'system']).default('system'),\n *   httpOnly: false,\n *   maxAge: 60 * 60 * 24 * 365,\n * });\n *\n * // Server or client\n * const theme = themeCookie.get();\n * themeCookie.set('dark');\n *\n * // Client hook\n * const [theme, setTheme] = themeCookie.useCookie();\n *\n * // httpOnly: true (default) — server-only, no client methods\n * export const sessionCookie = defineCookie('session', {\n *   codec: z.string(),\n * });\n * sessionCookie.get();       // works on server\n * sessionCookie.useCookie(); // TS error — httpOnly cookie\n * ```\n */\nexport function defineCookie<T, HttpOnly extends boolean = true>(\n  name: string,\n  options: DefineCookieOptions<T, HttpOnly>\n): HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T> {\n  const { codec: codecOrSchema, ...cookieOpts } = options;\n  const codec = resolveCodec(codecOrSchema);\n  const resolvedOptions: CookieOptions = { ...cookieOpts };\n  const isHttpOnly = options.httpOnly !== false; // default true\n\n  function getClientOpts(): ClientCookieOptions {\n    return {\n      path: resolvedOptions.path,\n      domain: resolvedOptions.domain,\n      maxAge: resolvedOptions.maxAge,\n      expires: resolvedOptions.expires,\n      sameSite: resolvedOptions.sameSite,\n      secure: resolvedOptions.secure,\n    };\n  }\n\n  function assertNotHttpOnlyClient(method: string): void {\n    if (isHttpOnly && !_serverImpl) {\n      throw new Error(\n        `[timber] defineCookie('${name}').${method}() cannot be used with httpOnly cookies — ` +\n          `the browser cannot access them. Set httpOnly: false to enable client access.`\n      );\n    }\n  }\n\n  const base: ServerOnlyCookieDefinition<T> = {\n    name,\n    options: resolvedOptions,\n    codec,\n\n    get(): T {\n      if (_serverImpl) {\n        const jar = _serverImpl.getCookieJar();\n        const raw = jar.get(name);\n        return codec.parse(raw);\n      }\n      // Client path\n      assertNotHttpOnlyClient('get');\n      if (_clientImpl) {\n        const raw = _clientImpl.getCookieValue(name);\n        return codec.parse(raw);\n      }\n      throw new Error(\n        `[timber] defineCookie('${name}').get() — no environment registered. ` +\n          'Ensure @timber-js/app/server or @timber-js/app/client is imported.'\n      );\n    },\n\n    set(value: T): void {\n      if (_serverImpl) {\n        const jar = _serverImpl.getCookieJar();\n        const serialized = codec.serialize(value);\n        if (serialized === null) {\n          jar.delete(name, {\n            path: resolvedOptions.path,\n            domain: resolvedOptions.domain,\n          });\n        } else {\n          jar.set(name, serialized, resolvedOptions);\n        }\n        return;\n      }\n      // Client path\n      assertNotHttpOnlyClient('set');\n      if (_clientImpl) {\n        const serialized = codec.serialize(value);\n        if (serialized === null) {\n          _clientImpl.deleteCookieValue(name, getClientOpts());\n        } else {\n          _clientImpl.setCookieValue(name, serialized, getClientOpts());\n        }\n        return;\n      }\n      throw new Error(\n        `[timber] defineCookie('${name}').set() — no environment registered. ` +\n          'Ensure @timber-js/app/server or @timber-js/app/client is imported.'\n      );\n    },\n\n    delete(): void {\n      if (_serverImpl) {\n        const jar = _serverImpl.getCookieJar();\n        jar.delete(name, {\n          path: resolvedOptions.path,\n          domain: resolvedOptions.domain,\n        });\n        return;\n      }\n      // Client path\n      assertNotHttpOnlyClient('delete');\n      if (_clientImpl) {\n        _clientImpl.deleteCookieValue(name, getClientOpts());\n        return;\n      }\n      throw new Error(\n        `[timber] defineCookie('${name}').delete() — no environment registered. ` +\n          'Ensure @timber-js/app/server or @timber-js/app/client is imported.'\n      );\n    },\n  };\n\n  if (isHttpOnly) {\n    return base as HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T>;\n  }\n\n  // httpOnly: false — add useCookie client hook\n  const full: CookieDefinition<T> = {\n    ...base,\n\n    useCookie(): [T, (value: T) => void, () => void] {\n      const { useCookie: useRawCookie } = getUseCookieModule();\n\n      const clientOpts = getClientOpts();\n      const [raw, setRaw, deleteRaw] = useRawCookie(name, clientOpts);\n      const parsed = codec.parse(raw);\n\n      const setTyped = (value: T): void => {\n        const serialized = codec.serialize(value);\n        if (serialized === null) {\n          deleteRaw();\n        } else {\n          setRaw(serialized);\n        }\n      };\n\n      return [parsed, setTyped, deleteRaw];\n    },\n  };\n\n  return full as HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T>;\n}\n"],"mappings":"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"}

package/dist/_chunks/merge-search-params-BphMdht_.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"merge-search-params-BphMdht_.js","names":[],"sources":["../../src/cookies/validation.ts","../../src/shared/merge-search-params.ts"],"sourcesContent":["/**\n * Cookie name and value validation per RFC 6265 §4.1.1.\n *\n * This module is pure — no server or client imports — so it can be loaded\n * by both `server/request-context.ts` (which guards `getCookies().set()`)\n * and `client/use-cookie.ts` (which guards `useCookie()`'s setter). The\n * shared validator gives both sides identical encoding contracts:\n * **the framework never silently encodes — callers emit `cookie-octet`\n * bytes or get a developer-facing error.**\n *\n * Why this matters: see ONGOING_SECURITY.md H-3 (TIM-868) and\n * design/29-cookies.md §\"Cookie Name and Value Validation\".\n */\n\n// ─── RFC 6265 cookie-octet ────────────────────────────────────────────────\n//\n//   cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E\n//\n// Equivalently: US-ASCII printable bytes excluding whitespace, `\"` (0x22),\n// `,` (0x2C), `;` (0x3B), `\\` (0x5C), and DEL (0x7F).\n\n/**\n * RFC 7230 §3.2.6 token characters used as the cookie-name production in\n * RFC 6265 §4.1.1. Anchored, non-empty match.\n *\n * Allowed: US-ASCII letters, digits, and `!#$%&'*+-.^_` `` ` `` `|~`.\n * Disallowed: whitespace, controls, delimiters\n * (`(` `)` `<` `>` `@` `,` `;` `:` `\\` `\"` `/` `[` `]` `?` `=` `{` `}`).\n */\nconst COOKIE_NAME_RE = /^[!#$%&'*+\\-.0-9A-Z^_`a-z|~]+$/;\n\n/**\n * Format a single byte for a clear error message — escape control bytes\n * and non-ASCII as `0x..` and quote printables.\n */\nfunction describeChar(value: string, index: number): string {\n  const code = value.charCodeAt(index);\n  if (code < 0x20 || code === 0x7f || code > 0x7e) {\n    return `0x${code.toString(16).padStart(2, '0')}`;\n  }\n  return JSON.stringify(value[index]);\n}\n\n/**\n * Validate a cookie name against RFC 6265 §4.1.1 / RFC 7230 token rules.\n * Throws a developer-facing error naming the offending byte and its index.\n */\nexport function assertValidCookieName(name: string): void {\n  if (typeof name !== 'string' || name.length === 0) {\n    throw new Error('[timber] cookie name must be a non-empty string.');\n  }\n  if (!COOKIE_NAME_RE.test(name)) {\n    for (let i = 0; i < name.length; i++) {\n      if (!COOKIE_NAME_RE.test(name[i])) {\n        throw new Error(\n          `[timber] invalid cookie name ${JSON.stringify(name)} — ` +\n            `disallowed character ${describeChar(name, i)} at index ${i}. ` +\n            `Cookie names must match the RFC 6265 §4.1.1 token grammar (US-ASCII letters, digits, ` +\n            `and \\`!#$%&'*+-.^_\\`|~\\`; no whitespace, controls, or delimiters).`\n        );\n      }\n    }\n    throw new Error(\n      `[timber] invalid cookie name ${JSON.stringify(name)} — ` +\n        `must match RFC 6265 §4.1.1 token grammar.`\n    );\n  }\n}\n\n/** Single-byte test for RFC 6265 §4.1.1 cookie-octet. */\nfunction isCookieOctet(code: number): boolean {\n  return (\n    code === 0x21 ||\n    (code >= 0x23 && code <= 0x2b) ||\n    (code >= 0x2d && code <= 0x3a) ||\n    (code >= 0x3c && code <= 0x5b) ||\n    (code >= 0x5d && code <= 0x7e)\n  );\n}\n\n/**\n * Validate a cookie value against the RFC 6265 §4.1.1 `cookie-value`\n * production:\n *\n *     cookie-value = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE )\n *     cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E\n *\n * Both the bare `*cookie-octet` form and the DQUOTE-wrapped form are\n * valid. The wrapped form is common in upstream `Set-Cookie` headers\n * (e.g. `sid=\"abc\"; Path=/`) and must be forwardable through\n * `setFromHeaders` verbatim — stripping or rejecting the surrounding\n * quotes would corrupt the on-the-wire bytes and break value semantics\n * for the upstream service.\n *\n * Excluded bytes (in either form): CTL, whitespace (CR/LF/TAB/SP),\n * interior DQUOTE, comma, semicolon, backslash, DEL, and anything\n * non-ASCII. The smuggling primitive (`;`) is rejected regardless of\n * wrapping.\n *\n * Throws a developer-facing error naming the offending byte and its\n * index. Callers passing user-controlled data through the default\n * `set()` path don't need to call this — `set()` auto-encodes via\n * `encodeURIComponent`, whose output is always valid cookie-octet.\n * This validator is for the `{ raw: true }` opt-out and for\n * `setFromHeaders` forwarding.\n */\nexport function assertValidCookieValue(name: string, value: string): void {\n  if (typeof value !== 'string') {\n    throw new Error(`[timber] cookie ${JSON.stringify(name)}: cookie value must be a string.`);\n  }\n  // Detect the DQUOTE-wrapped form: at least two characters and both\n  // endpoints are `\"`. The interior must be pure cookie-octet (no\n  // interior DQUOTEs allowed — the grammar says *cookie-octet, and\n  // cookie-octet excludes 0x22).\n  const wrapped =\n    value.length >= 2 &&\n    value.charCodeAt(0) === 0x22 &&\n    value.charCodeAt(value.length - 1) === 0x22;\n  const start = wrapped ? 1 : 0;\n  const end = wrapped ? value.length - 1 : value.length;\n  for (let i = start; i < end; i++) {\n    const code = value.charCodeAt(i);\n    if (!isCookieOctet(code)) {\n      throw new Error(\n        `[timber] cookie ${JSON.stringify(name)}: invalid cookie value — ` +\n          `disallowed character ${describeChar(value, i)} at index ${i}. ` +\n          `Cookie values must contain only RFC 6265 §4.1.1 cookie-octet bytes ` +\n          `(US-ASCII printable, excluding whitespace, \\`\"\\`, \\`,\\`, \\`;\\`, and \\`\\\\\\`), ` +\n          `optionally enclosed in a single DQUOTE pair. ` +\n          `Encode the value (e.g. encodeURIComponent or jsonCookieCodec) before storing it.`\n      );\n    }\n  }\n}\n","/**\n * Shared utility for merging preserved search params into a target URL.\n *\n * Used by both <Link> (client) and redirect() (server). Extracted to a shared\n * module to avoid importing client code ('use client') from server modules.\n */\n\n/**\n * Merge preserved search params from the current URL into a target href.\n *\n * When `preserve` is `true`, all current search params are merged.\n * When `preserve` is a `string[]`, only the named params are merged.\n *\n * The target href's own search params take precedence — preserved params\n * are only added if the target doesn't already define them.\n *\n * @param targetHref - The resolved target href (may already contain query string)\n * @param currentSearch - The current URL's search string (e.g. \"?private=access&page=2\")\n * @param preserve - `true` to preserve all, or `string[]` to preserve specific params\n * @returns The target href with preserved search params merged in\n */\nexport function mergePreservedSearchParams(\n  targetHref: string,\n  currentSearch: string,\n  preserve: true | string[]\n): string {\n  const currentParams = new URLSearchParams(currentSearch);\n  if (currentParams.size === 0) return targetHref;\n\n  // Split hash fragment from target before processing query params.\n  // Hash must come after query string: /path?query=value#hash\n  const hashIdx = targetHref.indexOf('#');\n  const hrefWithoutHash = hashIdx >= 0 ? targetHref.slice(0, hashIdx) : targetHref;\n  const hash = hashIdx >= 0 ? targetHref.slice(hashIdx) : '';\n\n  // Split target into path and existing query\n  const qIdx = hrefWithoutHash.indexOf('?');\n  const targetPath = qIdx >= 0 ? hrefWithoutHash.slice(0, qIdx) : hrefWithoutHash;\n  const targetParams = new URLSearchParams(qIdx >= 0 ? hrefWithoutHash.slice(qIdx + 1) : '');\n\n  // Collect params to preserve (that aren't already in the target)\n  const merged = new URLSearchParams(targetParams);\n  for (const [key, value] of currentParams) {\n    // Only preserve if: (a) not already in target, and (b) included in preserve list\n    if (!targetParams.has(key)) {\n      if (preserve === true || preserve.includes(key)) {\n        merged.append(key, value);\n      }\n    }\n  }\n\n  const qs = merged.toString();\n  const pathWithQuery = qs ? `${targetPath}?${qs}` : targetPath;\n  return pathWithQuery + hash;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA6BA,IAAM,iBAAiB;;;;;AAMvB,SAAS,aAAa,OAAe,OAAuB;CAC1D,MAAM,OAAO,MAAM,WAAW,MAAM;AACpC,KAAI,OAAO,MAAQ,SAAS,OAAQ,OAAO,IACzC,QAAO,KAAK,KAAK,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI;AAEhD,QAAO,KAAK,UAAU,MAAM,OAAO;;;;;;AAOrC,SAAgB,sBAAsB,MAAoB;AACxD,KAAI,OAAO,SAAS,YAAY,KAAK,WAAW,EAC9C,OAAM,IAAI,MAAM,mDAAmD;AAErE,KAAI,CAAC,eAAe,KAAK,KAAK,EAAE;AAC9B,OAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,IAC/B,KAAI,CAAC,eAAe,KAAK,KAAK,GAAG,CAC/B,OAAM,IAAI,MACR,gCAAgC,KAAK,UAAU,KAAK,CAAC,0BAC3B,aAAa,MAAM,EAAE,CAAC,YAAY,EAAE,2JAG/D;AAGL,QAAM,IAAI,MACR,gCAAgC,KAAK,UAAU,KAAK,CAAC,8CAEtD;;;;AAKL,SAAS,cAAc,MAAuB;AAC5C,QACE,SAAS,MACR,QAAQ,MAAQ,QAAQ,MACxB,QAAQ,MAAQ,QAAQ,MACxB,QAAQ,MAAQ,QAAQ,MACxB,QAAQ,MAAQ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8B7B,SAAgB,uBAAuB,MAAc,OAAqB;AACxE,KAAI,OAAO,UAAU,SACnB,OAAM,IAAI,MAAM,mBAAmB,KAAK,UAAU,KAAK,CAAC,kCAAkC;CAM5F,MAAM,UACJ,MAAM,UAAU,KAChB,MAAM,WAAW,EAAE,KAAK,MACxB,MAAM,WAAW,MAAM,SAAS,EAAE,KAAK;CACzC,MAAM,QAAQ,UAAU,IAAI;CAC5B,MAAM,MAAM,UAAU,MAAM,SAAS,IAAI,MAAM;AAC/C,MAAK,IAAI,IAAI,OAAO,IAAI,KAAK,IAE3B,KAAI,CAAC,cADQ,MAAM,WAAW,EAAE,CACR,CACtB,OAAM,IAAI,MACR,mBAAmB,KAAK,UAAU,KAAK,CAAC,gDACd,aAAa,OAAO,EAAE,CAAC,YAAY,EAAE,iRAKhE;;;;;;;;;;;;;;;;;;;;;;;;AC7GP,SAAgB,2BACd,YACA,eACA,UACQ;CACR,MAAM,gBAAgB,IAAI,gBAAgB,cAAc;AACxD,KAAI,cAAc,SAAS,EAAG,QAAO;CAIrC,MAAM,UAAU,WAAW,QAAQ,IAAI;CACvC,MAAM,kBAAkB,WAAW,IAAI,WAAW,MAAM,GAAG,QAAQ,GAAG;CACtE,MAAM,OAAO,WAAW,IAAI,WAAW,MAAM,QAAQ,GAAG;CAGxD,MAAM,OAAO,gBAAgB,QAAQ,IAAI;CACzC,MAAM,aAAa,QAAQ,IAAI,gBAAgB,MAAM,GAAG,KAAK,GAAG;CAChE,MAAM,eAAe,IAAI,gBAAgB,QAAQ,IAAI,gBAAgB,MAAM,OAAO,EAAE,GAAG,GAAG;CAG1F,MAAM,SAAS,IAAI,gBAAgB,aAAa;AAChD,MAAK,MAAM,CAAC,KAAK,UAAU,cAEzB,KAAI,CAAC,aAAa,IAAI,IAAI;MACpB,aAAa,QAAQ,SAAS,SAAS,IAAI,CAC7C,QAAO,OAAO,KAAK,MAAM;;CAK/B,MAAM,KAAK,OAAO,UAAU;AAE5B,SADsB,KAAK,GAAG,WAAW,GAAG,OAAO,cAC5B"}

package/dist/plugins/server-action-exports.d.ts

@@ -1,26 +0,0 @@
-import type { Plugin } from 'vite';
-/**
- * Rewrite 'use server' module exports to bypass RSC plugin AST validation.
- *
- * The RSC plugin's client/SSR proxy transform (transformProxyExport) requires
- * all `export const` initializers to be `async ArrowFunctionExpression`. But
- * `createActionClient().action()` and `validated()` return async functions via
- * CallExpressions — valid at runtime but rejected by the static AST check.
- *
- * This plugin rewrites non-function-expression exports from:
- *
- *   export const foo = someCall();
- *
- * to:
- *
- *   const foo = someCall();
- *   export { foo };
- *
- * The `export { name }` form bypasses the RSC plugin's validation without
- * changing runtime semantics. Function expression exports (async arrows,
- * async function expressions) are left untouched.
- *
- * See design/08-forms-and-actions.md §"Middleware for Server Actions"
- */
-export declare function timberServerActionExports(): Plugin;
-//# sourceMappingURL=server-action-exports.d.ts.map

package/dist/plugins/server-action-exports.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"server-action-exports.d.ts","sourceRoot":"","sources":["../../src/plugins/server-action-exports.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAOnC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAelD"}

package/dist/routing/status-file-lint.d.ts

@@ -1,34 +0,0 @@
-/**
- * Lint status files and error.tsx for missing 'use client' directive.
- *
- * Status files (error.tsx, 404.tsx, 4xx.tsx, 5xx.tsx, NNN.tsx) and legacy
- * compat files (not-found.tsx, forbidden.tsx, unauthorized.tsx) are passed
- * as fallbackComponent to TimberErrorBoundary — a 'use client' component.
- * RSC forbids passing server component functions as props to client
- * components, causing a hard-to-debug runtime error.
- *
- * This module provides a build/dev-time check that warns when these files
- * are missing the 'use client' directive.
- *
- * See design/10-error-handling.md §"Status-Code Files".
- */
-import type { RouteTree } from './types.js';
-export interface StatusFileLintWarning {
-    filePath: string;
-    fileType: string;
-}
-/**
- * Walk the route tree and check all status files and error files for
- * the 'use client' directive. Returns an array of warnings for files
- * that are missing it.
- *
- * MDX and JSON status files are excluded — MDX files are server components
- * by design (pre-rendered as elements via fallbackElement, see TIM-503),
- * and JSON files are data, not components.
- */
-export declare function lintStatusFileDirectives(tree: RouteTree): StatusFileLintWarning[];
-/**
- * Format warnings into human-readable console output.
- */
-export declare function formatStatusFileLintWarnings(warnings: StatusFileLintWarning[]): string;
-//# sourceMappingURL=status-file-lint.d.ts.map

package/dist/routing/status-file-lint.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"status-file-lint.d.ts","sourceRoot":"","sources":["../../src/routing/status-file-lint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAOzD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,SAAS,GAAG,qBAAqB,EAAE,CAIjF;AAqDD;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,qBAAqB,EAAE,GAAG,MAAM,CAiBtF"}

package/dist/utils/directive-parser.d.ts

@@ -1,28 +0,0 @@
-/**
- * AST-based directive detection for 'use client' and 'use server'.
- *
- * Uses acorn to parse source code and detect directives properly,
- * avoiding false positives from regex matching inside string literals,
- * comments, or template expressions.
- *
- * @module
- */
-export interface FileDirective {
-    /** The directive value, e.g. 'use client', 'use server' */
-    directive: string;
-    /** 1-based line number where the directive appears */
-    line: number;
-}
-/**
- * Detect a file-level directive ('use client', 'use server', etc.).
- *
- * Per the ECMAScript spec, directives are string literal expression
- * statements at the start of a program body (before any non-directive
- * statements). This function checks the AST `Program.body` for
- * `ExpressionStatement` nodes whose expression is a `Literal` string
- * matching a known directive.
- *
- * Returns the first matching directive, or null if none found.
- */
-export declare function detectFileDirective(code: string, directives?: string[]): FileDirective | null;
-//# sourceMappingURL=directive-parser.d.ts.map

package/dist/utils/directive-parser.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"directive-parser.d.ts","sourceRoot":"","sources":["../../src/utils/directive-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;CACd;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,MAAM,EAAiC,GAClD,aAAa,GAAG,IAAI,CAmCtB"}

package/src/plugins/server-action-exports.ts

@@ -1,220 +0,0 @@
-import type { Plugin } from 'vite';
-import { Parser } from 'acorn';
-import acornJsx from 'acorn-jsx';
-import { detectFileDirective } from '../utils/directive-parser.js';
-
-const jsxParser = Parser.extend(acornJsx());
-
-/**
- * Rewrite 'use server' module exports to bypass RSC plugin AST validation.
- *
- * The RSC plugin's client/SSR proxy transform (transformProxyExport) requires
- * all `export const` initializers to be `async ArrowFunctionExpression`. But
- * `createActionClient().action()` and `validated()` return async functions via
- * CallExpressions — valid at runtime but rejected by the static AST check.
- *
- * This plugin rewrites non-function-expression exports from:
- *
- *   export const foo = someCall();
- *
- * to:
- *
- *   const foo = someCall();
- *   export { foo };
- *
- * The `export { name }` form bypasses the RSC plugin's validation without
- * changing runtime semantics. Function expression exports (async arrows,
- * async function expressions) are left untouched.
- *
- * See design/08-forms-and-actions.md §"Middleware for Server Actions"
- */
-export function timberServerActionExports(): Plugin {
-  return {
-    name: 'timber-server-action-exports',
-    transform(code, id) {
-      // Skip non-JS/TS files
-      if (!/\.[jt]sx?$/.test(id)) return;
-      // Quick bail-out
-      if (!code.includes('use server')) return;
-      // Check for file-level directive
-      const directive = detectFileDirective(code, ['use server']);
-      if (!directive) return;
-
-      return rewriteServerActionExports(code);
-    },
-  };
-}
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type AcornNode = any;
-
-/**
- * Check if an AST node is an async function expression (arrow or regular).
- * These are handled correctly by the RSC plugin and don't need rewriting.
- */
-function isAsyncFunctionExpr(node: AcornNode): boolean {
-  if (!node) return false;
-  return (
-    (node.type === 'ArrowFunctionExpression' || node.type === 'FunctionExpression') && node.async
-  );
-}
-
-/**
- * Extract identifier names from a declarator's id pattern.
- * Handles simple identifiers and destructuring patterns.
- */
-function extractDeclNames(id: AcornNode): string[] {
-  if (id.type === 'Identifier') return [id.name];
-
-  // ObjectPattern: const { a, b } = ...
-  if (id.type === 'ObjectPattern') {
-    return id.properties.flatMap((p: AcornNode) => extractDeclNames(p.value ?? p.argument));
-  }
-
-  // ArrayPattern: const [a, b] = ...
-  if (id.type === 'ArrayPattern') {
-    return id.elements.filter(Boolean).flatMap((e: AcornNode) => extractDeclNames(e));
-  }
-
-  // RestElement: const [...rest] = ...
-  if (id.type === 'RestElement') {
-    return extractDeclNames(id.argument);
-  }
-
-  // AssignmentPattern: const { a = 1 } = ...
-  if (id.type === 'AssignmentPattern') {
-    return extractDeclNames(id.left);
-  }
-
-  return [];
-}
-
-interface RewriteTarget {
-  /** Start offset of the `export` keyword */
-  exportStart: number;
-  /** Start offset of the `const/let/var` keyword (right after `export `) */
-  declStart: number;
-  /** Names to re-export */
-  names: string[];
-}
-
-function rewriteServerActionExports(code: string): { code: string; map: null } | undefined {
-  let ast: AcornNode;
-  try {
-    ast = jsxParser.parse(code, {
-      ecmaVersion: 'latest',
-      sourceType: 'module',
-    });
-  } catch {
-    // TypeScript that esbuild hasn't stripped yet — use regex fallback
-    return rewriteServerActionExportsFallback(code);
-  }
-
-  const targets: RewriteTarget[] = [];
-
-  for (const node of ast.body) {
-    // Case 1: export const/let/var name = <non-function-expression>
-    if (
-      node.type === 'ExportNamedDeclaration' &&
-      node.declaration?.type === 'VariableDeclaration'
-    ) {
-      const hasNonFunctionInit = node.declaration.declarations.some(
-        (d: AcornNode) => d.init && !isAsyncFunctionExpr(d.init)
-      );
-      if (!hasNonFunctionInit) continue;
-
-      const names = node.declaration.declarations.flatMap((d: AcornNode) => extractDeclNames(d.id));
-      if (names.length === 0) continue;
-
-      targets.push({
-        exportStart: node.start,
-        declStart: node.declaration.start,
-        names,
-      });
-    }
-
-    // Case 2: export default <non-function-expression>
-    if (node.type === 'ExportDefaultDeclaration') {
-      const decl = node.declaration;
-      if (
-        decl.type !== 'FunctionDeclaration' &&
-        decl.type !== 'Identifier' &&
-        !isAsyncFunctionExpr(decl)
-      ) {
-        // export default someCall() → const $$default = someCall(); export default $$default;
-        targets.push({
-          exportStart: node.start,
-          declStart: -1, // sentinel for default export
-          names: ['default'],
-        });
-      }
-    }
-  }
-
-  if (targets.length === 0) return undefined;
-
-  // Process from end to start to preserve character positions
-  let result = code;
-  const reExports: string[] = [];
-
-  for (let i = targets.length - 1; i >= 0; i--) {
-    const target = targets[i];
-
-    if (target.declStart === -1) {
-      // export default <expr> → const $$default = <expr>;\nexport default $$default;
-      const node = ast.body.find(
-        (n: AcornNode) => n.type === 'ExportDefaultDeclaration' && n.start === target.exportStart
-      );
-      if (node) {
-        const exprCode = code.slice(node.declaration.start, node.declaration.end);
-        const replacement = `const $$default = ${exprCode};\nexport default $$default;`;
-        result = result.slice(0, node.start) + replacement + result.slice(node.end);
-      }
-      continue;
-    }
-
-    // Remove 'export ' from the declaration
-    result = result.slice(0, target.exportStart) + result.slice(target.declStart);
-    reExports.push(...target.names);
-  }
-
-  if (reExports.length > 0) {
-    result += '\nexport { ' + reExports.join(', ') + ' };\n';
-  }
-
-  return { code: result, map: null };
-}
-
-/**
- * Regex fallback for TypeScript files that acorn cannot parse.
- *
- * Matches `export const/let/var name = <expr>` where the initializer does
- * NOT start with `async function` or `async (` (i.e., not an async
- * function expression or async arrow function).
- */
-function rewriteServerActionExportsFallback(code: string): { code: string; map: null } | undefined {
-  // Match: export const/let/var <name> = <non-async-function-expr>
-  const pattern =
-    /^(export\s+)((?:const|let|var)\s+(\w+)\s*=\s*)(?!async\s+(?:function[\s(]|\())/gm;
-
-  const names: string[] = [];
-  let result = code;
-  let offset = 0;
-  let match;
-
-  while ((match = pattern.exec(code)) !== null) {
-    const exportKeyword = match[1]; // 'export ' (with trailing space)
-    const name = match[3];
-
-    // Remove 'export ' at this position (adjusted for prior removals)
-    const pos = match.index + offset;
-    result = result.slice(0, pos) + result.slice(pos + exportKeyword.length);
-    offset -= exportKeyword.length;
-    names.push(name);
-  }
-
-  if (names.length === 0) return undefined;
-
-  result += '\nexport { ' + names.join(', ') + ' };\n';
-  return { code: result, map: null };
-}

package/src/routing/status-file-lint.ts

@@ -1,115 +0,0 @@
-/**
- * Lint status files and error.tsx for missing 'use client' directive.
- *
- * Status files (error.tsx, 404.tsx, 4xx.tsx, 5xx.tsx, NNN.tsx) and legacy
- * compat files (not-found.tsx, forbidden.tsx, unauthorized.tsx) are passed
- * as fallbackComponent to TimberErrorBoundary — a 'use client' component.
- * RSC forbids passing server component functions as props to client
- * components, causing a hard-to-debug runtime error.
- *
- * This module provides a build/dev-time check that warns when these files
- * are missing the 'use client' directive.
- *
- * See design/10-error-handling.md §"Status-Code Files".
- */
-
-import { readFileSync } from 'node:fs';
-import type { RouteTree, SegmentNode } from './types.js';
-import { detectFileDirective } from '../utils/directive-parser.js';
-import { swallow } from '../server/logger.js';
-
-/** Extensions that require 'use client' (component files, not MDX/JSON). */
-const CLIENT_REQUIRED_EXTENSIONS = new Set(['tsx', 'jsx', 'ts', 'js']);
-
-export interface StatusFileLintWarning {
-  filePath: string;
-  fileType: string;
-}
-
-/**
- * Walk the route tree and check all status files and error files for
- * the 'use client' directive. Returns an array of warnings for files
- * that are missing it.
- *
- * MDX and JSON status files are excluded — MDX files are server components
- * by design (pre-rendered as elements via fallbackElement, see TIM-503),
- * and JSON files are data, not components.
- */
-export function lintStatusFileDirectives(tree: RouteTree): StatusFileLintWarning[] {
-  const warnings: StatusFileLintWarning[] = [];
-  walkNode(tree.root, warnings);
-  return warnings;
-}
-
-function walkNode(node: SegmentNode, warnings: StatusFileLintWarning[]): void {
-  // Check error.tsx
-  if (node.error) {
-    checkFile(node.error.filePath, node.error.extension, 'error', warnings);
-  }
-
-  // Check status-code files (404.tsx, 4xx.tsx, 5xx.tsx, etc.)
-  if (node.statusFiles) {
-    for (const [code, file] of Object.entries(node.statusFiles)) {
-      checkFile(file.filePath, file.extension, code, warnings);
-    }
-  }
-
-  // Check legacy compat files (not-found.tsx, forbidden.tsx, unauthorized.tsx)
-  if (node.legacyStatusFiles) {
-    for (const [name, file] of Object.entries(node.legacyStatusFiles)) {
-      checkFile(file.filePath, file.extension, name, warnings);
-    }
-  }
-
-  // Recurse into children and slots
-  for (const child of node.children) {
-    walkNode(child, warnings);
-  }
-  for (const slotNode of Object.values(node.slots)) {
-    walkNode(slotNode, warnings);
-  }
-}
-
-function checkFile(
-  filePath: string,
-  extension: string,
-  fileType: string,
-  warnings: StatusFileLintWarning[]
-): void {
-  if (!CLIENT_REQUIRED_EXTENSIONS.has(extension)) return;
-
-  let code: string;
-  try {
-    code = readFileSync(filePath, 'utf-8');
-  } catch (err) {
-    swallow(err, `status-file-lint: unreadable file ${filePath}`);
-    return;
-  }
-
-  const directive = detectFileDirective(code, ['use client']);
-  if (!directive) {
-    warnings.push({ filePath, fileType });
-  }
-}
-
-/**
- * Format warnings into human-readable console output.
- */
-export function formatStatusFileLintWarnings(warnings: StatusFileLintWarning[]): string {
-  const lines = [
-    `[timber] ${warnings.length} status/error file${warnings.length > 1 ? 's' : ''} missing 'use client' directive:`,
-    '',
-  ];
-
-  for (const w of warnings) {
-    lines.push(`  ${w.filePath}`);
-  }
-
-  lines.push('');
-  lines.push(
-    "  Status files and error.tsx are rendered inside TimberErrorBoundary (a 'use client' component)."
-  );
-  lines.push("  Add 'use client' as the first line of each file to avoid a runtime error.");
-
-  return lines.join('\n');
-}

package/src/utils/directive-parser.ts

@@ -1,140 +0,0 @@
-/**
- * AST-based directive detection for 'use client' and 'use server'.
- *
- * Uses acorn to parse source code and detect directives properly,
- * avoiding false positives from regex matching inside string literals,
- * comments, or template expressions.
- *
- * @module
- */
-
-import { Parser } from 'acorn';
-import acornJsx from 'acorn-jsx';
-
-// acorn parser with JSX support
-const jsxParser = Parser.extend(acornJsx());
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface FileDirective {
-  /** The directive value, e.g. 'use client', 'use server' */
-  directive: string;
-  /** 1-based line number where the directive appears */
-  line: number;
-}
-
-// ---------------------------------------------------------------------------
-// File-level directive detection
-// ---------------------------------------------------------------------------
-
-/**
- * Detect a file-level directive ('use client', 'use server', etc.).
- *
- * Per the ECMAScript spec, directives are string literal expression
- * statements at the start of a program body (before any non-directive
- * statements). This function checks the AST `Program.body` for
- * `ExpressionStatement` nodes whose expression is a `Literal` string
- * matching a known directive.
- *
- * Returns the first matching directive, or null if none found.
- */
-export function detectFileDirective(
-  code: string,
-  directives: string[] = ['use client', 'use server']
-): FileDirective | null {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let ast: any;
-  try {
-    ast = jsxParser.parse(code, {
-      ecmaVersion: 'latest',
-      sourceType: 'module',
-      locations: true,
-    });
-  } catch {
-    // If the file fails to parse (e.g. TypeScript syntax), fall back to
-    // a safe line-by-line check that only considers lines before any
-    // non-comment, non-whitespace, non-directive content.
-    return detectFileDirectiveFallback(code, directives);
-  }
-
-  for (const node of ast.body) {
-    if (
-      node.type === 'ExpressionStatement' &&
-      node.expression.type === 'Literal' &&
-      typeof node.expression.value === 'string'
-    ) {
-      if (directives.includes(node.expression.value)) {
-        return {
-          directive: node.expression.value,
-          line: node.loc.start.line,
-        };
-      }
-    } else {
-      // Directives must appear before any non-directive statements
-      break;
-    }
-  }
-
-  return null;
-}
-
-/**
- * Fallback for TypeScript files that acorn cannot parse.
- *
- * Scans lines from the top of the file. Skips blank lines and comments.
- * Checks if the first real statement is a directive string literal.
- */
-function detectFileDirectiveFallback(code: string, directives: string[]): FileDirective | null {
-  const lines = code.split('\n');
-  let inBlockComment = false;
-
-  for (let i = 0; i < lines.length; i++) {
-    let line = lines[i].trim();
-
-    // Handle block comments
-    if (inBlockComment) {
-      const endIdx = line.indexOf('*/');
-      if (endIdx === -1) continue;
-      line = line.slice(endIdx + 2).trim();
-      inBlockComment = false;
-      if (!line) continue;
-    }
-
-    // Skip blank lines
-    if (!line) continue;
-
-    // Skip line comments
-    if (line.startsWith('//')) continue;
-
-    // Skip block comment start
-    if (line.startsWith('/*')) {
-      const endIdx = line.indexOf('*/', 2);
-      if (endIdx === -1) {
-        inBlockComment = true;
-        continue;
-      }
-      line = line.slice(endIdx + 2).trim();
-      if (!line) continue;
-    }
-
-    // Check for directive
-    for (const dir of directives) {
-      // Match 'directive' or "directive" optionally followed by ;
-      if (
-        line === `'${dir}'` ||
-        line === `'${dir}';` ||
-        line === `"${dir}"` ||
-        line === `"${dir}";`
-      ) {
-        return { directive: dir, line: i + 1 };
-      }
-    }
-
-    // First non-comment, non-blank line is not a directive — stop
-    break;
-  }
-
-  return null;
-}