@timber-js/app 0.2.0-alpha.12 → 0.2.0-alpha.121

package/src/config-validation.ts

@@ -0,0 +1,303 @@
+/**
+ * Config validation — validates timber.config.ts at startup.
+ *
+ * Runs in the plugin's configResolved hook (once, at startup/build).
+ * Each check produces a clear error message with the invalid value,
+ * what's expected, and how to fix it.
+ *
+ * Design doc: 18-build-system.md
+ */
+
+import { createRequire } from 'node:module';
+import type { TimberUserConfig } from './config-types.js';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ConfigError {
+  field: string;
+  message: string;
+  value?: unknown;
+  suggestion?: string;
+}
+
+// ─── Validation ─────────────────────────────────────────────────────────────
+
+/**
+ * Validate a TimberUserConfig object.
+ *
+ * Returns an array of errors. Empty array means the config is valid.
+ * Does not throw — the caller decides how to surface errors.
+ */
+export function validateConfig(config: TimberUserConfig): ConfigError[] {
+  const errors: ConfigError[] = [];
+
+  // output
+  if (config.output !== undefined && config.output !== 'server' && config.output !== 'static') {
+    errors.push({
+      field: 'output',
+      message: `Invalid output mode: "${String(config.output)}". Must be "server" or "static".`,
+      value: config.output,
+      suggestion: 'Use output: "server" (default) or output: "static" for static site generation.',
+    });
+  }
+
+  // pageExtensions
+  if (config.pageExtensions !== undefined) {
+    if (!Array.isArray(config.pageExtensions)) {
+      errors.push({
+        field: 'pageExtensions',
+        message: 'pageExtensions must be an array of strings.',
+        value: config.pageExtensions,
+        suggestion: 'Example: pageExtensions: ["tsx", "ts", "jsx", "js", "mdx"]',
+      });
+    } else {
+      for (const ext of config.pageExtensions) {
+        if (typeof ext !== 'string') {
+          errors.push({
+            field: 'pageExtensions',
+            message: `pageExtensions contains a non-string value: ${JSON.stringify(ext)}`,
+            value: ext,
+          });
+          break;
+        }
+        if (ext.startsWith('.')) {
+          errors.push({
+            field: 'pageExtensions',
+            message: `pageExtensions should not include the leading dot: "${ext}"`,
+            value: ext,
+            suggestion: `Use "${ext.slice(1)}" instead of "${ext}".`,
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  // slowRequestMs
+  if (config.slowRequestMs !== undefined) {
+    if (typeof config.slowRequestMs !== 'number' || config.slowRequestMs < 0) {
+      errors.push({
+        field: 'slowRequestMs',
+        message: `slowRequestMs must be a non-negative number (got ${JSON.stringify(config.slowRequestMs)}).`,
+        value: config.slowRequestMs,
+        suggestion: 'Use slowRequestMs: 3000 (default) or slowRequestMs: 0 to disable.',
+      });
+    }
+  }
+
+  // renderTimeoutMs
+  if (config.renderTimeoutMs !== undefined) {
+    if (typeof config.renderTimeoutMs !== 'number' || config.renderTimeoutMs < 0) {
+      errors.push({
+        field: 'renderTimeoutMs',
+        message: `renderTimeoutMs must be a non-negative number (got ${JSON.stringify(config.renderTimeoutMs)}).`,
+        value: config.renderTimeoutMs,
+        suggestion: 'Use renderTimeoutMs: 30000 (default) or renderTimeoutMs: 0 to disable.',
+      });
+    }
+  }
+
+  // serverTiming
+  if (config.serverTiming !== undefined) {
+    if (
+      config.serverTiming !== 'detailed' &&
+      config.serverTiming !== 'total' &&
+      config.serverTiming !== false
+    ) {
+      errors.push({
+        field: 'serverTiming',
+        message: `Invalid serverTiming value: ${JSON.stringify(config.serverTiming)}.`,
+        value: config.serverTiming,
+        suggestion: 'Use "detailed", "total", or false.',
+      });
+    }
+  }
+
+  // devBrowserLogs
+  if (config.devBrowserLogs !== undefined) {
+    const valid = ['error', 'warn', 'info', 'none'];
+    if (!valid.includes(config.devBrowserLogs)) {
+      errors.push({
+        field: 'devBrowserLogs',
+        message: `Invalid devBrowserLogs value: ${JSON.stringify(config.devBrowserLogs)}.`,
+        value: config.devBrowserLogs,
+        suggestion: `Use one of: ${valid.map((v) => `"${v}"`).join(', ')}.`,
+      });
+    }
+  }
+
+  // sitemap
+  if (config.sitemap != null && typeof config.sitemap === 'object') {
+    if (config.sitemap.enabled && !config.sitemap.baseUrl) {
+      errors.push({
+        field: 'sitemap.baseUrl',
+        message: 'sitemap.baseUrl is required when sitemap is enabled.',
+        suggestion: 'Add sitemap: { enabled: true, baseUrl: "https://example.com" }.',
+      });
+    }
+    if (
+      config.sitemap.defaultPriority !== undefined &&
+      (config.sitemap.defaultPriority < 0 || config.sitemap.defaultPriority > 1)
+    ) {
+      errors.push({
+        field: 'sitemap.defaultPriority',
+        message: `sitemap.defaultPriority must be between 0.0 and 1.0 (got ${config.sitemap.defaultPriority}).`,
+        value: config.sitemap.defaultPriority,
+      });
+    }
+  }
+
+  // Unknown top-level keys
+  const knownKeys = new Set([
+    'output',
+    'debug',
+    'clientJavascript',
+    'adapter',
+    'cacheHandler',
+    'allowedOrigins',
+    'csrf',
+    'limits',
+    'pageExtensions',
+    'slowRequestMs',
+    'renderTimeoutMs',
+    'devBrowserLogs',
+    'dev',
+    'serverTiming',
+    'appDir',
+    'mdx',
+    'actionEncryption',
+    'reactCompiler',
+    'sitemap',
+    'buildDir',
+    'topLoader',
+  ]);
+
+  for (const key of Object.keys(config)) {
+    if (!knownKeys.has(key)) {
+      errors.push({
+        field: key,
+        message: `Unknown config option: "${key}".`,
+        suggestion: `Check for typos. Known options: ${[...knownKeys].sort().join(', ')}.`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+// ─── Formatting ─────────────────────────────────────────────────────────────
+
+const RED = '\x1b[31m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+/**
+ * Format config errors for terminal output.
+ */
+export function formatConfigErrors(errors: ConfigError[]): string {
+  if (errors.length === 0) return '';
+
+  const lines: string[] = [];
+  lines.push(
+    `${RED}${BOLD}[timber]${RESET} ${RED}${errors.length} config error${errors.length !== 1 ? 's' : ''} in timber.config.ts:${RESET}`
+  );
+
+  for (const err of errors) {
+    lines.push('');
+    lines.push(`  ${RED}✗${RESET} ${BOLD}${err.field}${RESET}: ${err.message}`);
+    if (err.suggestion) {
+      lines.push(`    ${DIM}${err.suggestion}${RESET}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Virtual Module Name Mapping ────────────────────────────────────────────
+
+const VIRTUAL_MODULE_NAMES: Record<string, string> = {
+  'virtual:timber-rsc-entry': 'RSC entry (server component handler)',
+  'virtual:timber-ssr-entry': 'SSR entry (HTML renderer)',
+  'virtual:timber-browser-entry': 'Browser entry (client hydration)',
+  'virtual:timber-config': 'Runtime config (timber.config.ts)',
+  'virtual:timber-route-manifest': 'Route manifest (app/ file tree)',
+  'virtual:timber-instrumentation': 'Instrumentation (instrumentation.ts)',
+  'virtual:timber-cache-handler': 'Cache handler (cacheHandler config)',
+  'virtual:timber-build-manifest': 'Build manifest (asset mapping)',
+};
+
+/**
+ * Add timber-specific context to an error message that references virtual modules.
+ *
+ * If the error message contains a `virtual:timber-*` ID, appends a
+ * human-readable explanation. Does not replace the original message.
+ */
+export function addVirtualModuleContext(errorMessage: string): string {
+  for (const [id, name] of Object.entries(VIRTUAL_MODULE_NAMES)) {
+    if (errorMessage.includes(id)) {
+      return `${errorMessage}\n\n  [timber] This error references "${id}" — timber's ${name}.\n  This is an internal module. The issue is likely in your app code or timber configuration.`;
+    }
+  }
+  return errorMessage;
+}
+
+// ─── Peer Dependency Check ──────────────────────────────────────────────────
+
+interface PeerDepResult {
+  name: string;
+  status: 'ok' | 'missing';
+}
+
+/**
+ * Required (non-optional) peer dependencies that must be installed.
+ */
+const REQUIRED_PEERS = ['react', 'react-dom', '@vitejs/plugin-react', '@vitejs/plugin-rsc'];
+
+/**
+ * Check that required peer dependencies are installed.
+ *
+ * Uses require.resolve with a try/catch — no fs scanning.
+ * Returns only the missing packages.
+ */
+export function checkPeerDependencies(projectRoot: string): PeerDepResult[] {
+  const results: PeerDepResult[] = [];
+
+  // Use createRequire from the project root to resolve as the user would.
+  // `createRequire` MUST be a top-level ESM import — inline `require('node:module')`
+  // throws "Dynamic require not supported" in ESM and the catch below would
+  // mark every peer as missing. Same class of bug as TIM-796.
+  const userRequire = createRequire(`${projectRoot}/package.json`);
+
+  for (const name of REQUIRED_PEERS) {
+    try {
+      userRequire.resolve(name);
+      results.push({ name, status: 'ok' });
+    } catch {
+      results.push({ name, status: 'missing' });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Format missing peer dependencies as an actionable warning.
+ */
+export function formatMissingPeers(results: PeerDepResult[]): string {
+  const missing = results.filter((r) => r.status === 'missing');
+  if (missing.length === 0) return '';
+
+  const names = missing.map((r) => r.name);
+  const lines: string[] = [];
+  lines.push(`${RED}${BOLD}[timber]${RESET} ${RED}Missing required dependencies:${RESET}`);
+  lines.push('');
+  for (const name of names) {
+    lines.push(`  ${RED}✗${RESET} ${name}`);
+  }
+  lines.push('');
+  lines.push(`  ${DIM}Install with:${RESET}`);
+  lines.push(`  ${BOLD}pnpm add ${names.join(' ')}${RESET}`);
+
+  return lines.join('\n');
+}

package/src/content/index.ts

@@ -1,13 +1,5 @@
-/**
- * @timber-js/app/content — Public API for content collections.
- *
- * Re-exports from content-collections and provides timber-specific utilities.
- * Users can import directly from 'content-collections' for generated types,
- * or use this module for the re-exports.
- *
- * Design doc: 20-content-collections.md §"Querying Collections"
- */
-
-// Re-export defineCollection and defineConfig for convenience.
-// Users can also import these directly from @content-collections/core.
-export { defineCollection, defineConfig } from '@content-collections/core';
+// @timber-js/app/content entry point removed per TIM-722.
+//
+// Import defineCollection and defineConfig directly from @content-collections/core.
+// This file is kept for the content plugin which uses other files in this directory.
+export {};

package/src/cookies/define-cookie.ts

@@ -2,58 +2,170 @@
  * defineCookie — typed cookie definitions.
  *
  * Bundles name + codec + options into a reusable CookieDefinition<T>
- * with .get(), .set(), .delete() server methods and a .useCookie() client hook.
+ * with sync .get(), .set(), .delete() isomorphic methods (server + client)
+ * and a .useCookie() client hook.
  *
- * Reuses the SearchParamCodec protocol via fromSchema() bridge.
- * Validation on read returns the codec default (never throws).
+ * Environment detection is call-time: on the server, getCookieJar() is
+ * used directly (ALS-backed). On the client, document.cookie helpers
+ * and the useCookie hook are used. No registration pattern — imports
+ * resolve via the shims plugin (client bundle gets a stub for
+ * @timber-js/app/server).
+ *
+ * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected in
+ * the codec option — no explicit fromSchema() wrapper needed.
  *
  * See design/29-cookies.md §"Typed Cookies with Schema Validation"
  */
 
-import { cookies } from '#/server/request-context.js';
-import type { CookieOptions } from '#/server/request-context.js';
-import { useCookie as useRawCookie } from '#/client/use-cookie.js';
-import type { ClientCookieOptions } from '#/client/use-cookie.js';
+import type { CookieOptions } from '../server/cookie-context.js';
+import type { ClientCookieOptions } from '../client/use-cookie.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
+import type { Codec } from '../codec.js';
+import type { StandardSchemaV1 } from '../schema-bridge.js';
+
 /**
  * A codec that converts between string cookie values and typed values.
- * Intentionally identical to SearchParamCodec<T>.
+ * Type alias for the shared Codec<T> protocol.
  */
-export interface CookieCodec<T> {
-  parse(value: string | string[] | undefined): T;
-  serialize(value: T): string | null;
-}
+export type CookieCodec<T> = Codec<T>;
 
 /** Options for defineCookie: codec + CookieOptions merged. */
-export interface DefineCookieOptions<T> extends Omit<CookieOptions, 'signed'> {
-  /** Codec for parsing/serializing the cookie value. */
-  codec: CookieCodec<T>;
-  /** Sign the cookie with HMAC-SHA256. */
-  signed?: boolean;
+export interface DefineCookieOptions<T, HttpOnly extends boolean = boolean> extends CookieOptions {
+  /**
+   * Codec for parsing/serializing the cookie value.
+   * Accepts a Codec<T> or a Standard Schema object (Zod, Valibot, ArkType)
+   * which is auto-wrapped via fromSchema.
+   */
+  codec: CookieCodec<T> | StandardSchemaV1<T>;
+  /**
+   * Prevent client-side JS access. Default: true.
+   * When true (or omitted), client methods (useCookie, get/set/delete on
+   * client) are omitted from the return type and throw at runtime.
+   */
+  httpOnly?: HttpOnly;
 }
 
-/** A fully typed cookie definition with server and client methods. */
-export interface CookieDefinition<T> {
-  /** The cookie name. */
+/**
+ * Server-only cookie definition. Returned when httpOnly is true or omitted.
+ * Client methods are absent from the type — accessing them is a TS error.
+ */
+export interface ServerOnlyCookieDefinition<T> {
   readonly name: string;
-  /** The resolved cookie options (without codec). */
   readonly options: CookieOptions;
-  /** The codec used for parsing/serializing. */
   readonly codec: CookieCodec<T>;
 
-  /** Server: read the typed value from the current request. */
+  /** Read the typed value. Sync, isomorphic (server + client). */
   get(): T;
-  /** Server: set the typed value on the response. */
+  /** Set the typed value. Sync, isomorphic (server + client). */
   set(value: T): void;
-  /** Server: delete the cookie. */
+  /** Delete the cookie. Sync, isomorphic (server + client). */
   delete(): void;
+}
 
+/**
+ * Full cookie definition with client methods. Returned when httpOnly: false.
+ */
+export interface CookieDefinition<T> extends ServerOnlyCookieDefinition<T> {
   /** Client: React hook for reading/writing this cookie. Returns [value, setter, deleter]. */
   useCookie(): [T, (value: T) => void, () => void];
 }
 
+// ─── Direct Imports (no registration) ─────────────────────────────────────
+//
+// Server: getCookieJar is imported from @timber-js/app/server. In the client
+// bundle, the shims plugin replaces @timber-js/app/server with a stub module
+// where getCookieJar throws on call. We detect the environment at call time
+// by trying getCookieJar() — if it throws the stub error, we fall through
+// to the client path.
+//
+// Client: useCookie, getCookieValue, notifyCookieChange
+// are imported from use-cookie.ts. These are safe in all environments (no
+// node:async_hooks dependency).
+//
+// Schema: fromSchema is a pure function — safe in all environments.
+
+import { getCookieJar } from '@timber-js/app/server';
+import { fromSchema } from '../schema-bridge.js';
+import {
+  useCookie as useRawCookie,
+  notifyCookieChange,
+  getCookieValue,
+} from '../client/use-cookie.js';
+
+// ─── Environment Detection ────────────────────────────────────────────────
+
+/**
+ * Try to get the server cookie jar. Returns null if we're in the client
+ * environment (stub throws) or if there's no request context.
+ *
+ * On the server, getCookieJar() throws "outside of a request context" if
+ * called without an ALS store — this is a real error and is re-thrown.
+ * The client stub throws a different message — that's caught and returns null.
+ */
+function tryGetServerCookieJar(): ReturnType<typeof getCookieJar> | null {
+  try {
+    return getCookieJar();
+  } catch (e) {
+    // Server-side "no request context" error — re-throw as a real bug.
+    if (e instanceof Error && e.message.includes('outside of a request context')) {
+      throw e;
+    }
+    // Client stub error or other — fall through to client path.
+    return null;
+  }
+}
+
+// ─── Client Cookie Helpers ────────────────────────────────────────────────
+
+/** Write a cookie via document.cookie and notify useCookie subscribers. */
+function setClientCookie(name: string, value: string, options?: ClientCookieOptions): void {
+  const parts: string[] = [`${name}=${encodeURIComponent(value)}`];
+  const path = options?.path ?? '/';
+  parts.push(`Path=${path}`);
+  if (options?.domain) parts.push(`Domain=${options.domain}`);
+  if (options?.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`);
+  if (options?.expires) parts.push(`Expires=${options.expires.toUTCString()}`);
+  const sameSite = options?.sameSite ?? 'lax';
+  parts.push(`SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`);
+  if (options?.secure) parts.push('Secure');
+  document.cookie = parts.join('; ');
+  notifyCookieChange(name);
+}
+
+/** Delete a cookie via document.cookie and notify useCookie subscribers. */
+function deleteClientCookie(name: string, options?: ClientCookieOptions): void {
+  const path = options?.path ?? '/';
+  const domain = options?.domain;
+  let cookieStr = `${name}=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=${path}`;
+  if (domain) cookieStr += `; Domain=${domain}`;
+  document.cookie = cookieStr;
+  notifyCookieChange(name);
+}
+
+// ─── Standard Schema Auto-Detection ───────────────────────────────────────
+
+function resolveCodec<T>(codecOrSchema: CookieCodec<T> | StandardSchemaV1<T>): CookieCodec<T> {
+  // If it has parse + serialize, it's already a Codec
+  if (
+    typeof (codecOrSchema as Codec<T>).parse === 'function' &&
+    typeof (codecOrSchema as Codec<T>).serialize === 'function'
+  ) {
+    return codecOrSchema as CookieCodec<T>;
+  }
+
+  // Auto-detect Standard Schema
+  if (typeof codecOrSchema === 'object' && codecOrSchema !== null && '~standard' in codecOrSchema) {
+    return fromSchema(codecOrSchema as StandardSchemaV1<unknown>) as CookieCodec<T>;
+  }
+
+  throw new Error(
+    '[timber] defineCookie: codec must be a Codec<T> (with parse/serialize methods) ' +
+      'or a Standard Schema object (Zod, Valibot, ArkType).'
+  );
+}
+
 // ─── Factory ──────────────────────────────────────────────────────────────
 
 /**
@@ -61,64 +173,130 @@ export interface CookieDefinition<T> {
  *
  * ```ts
  * import { defineCookie } from '@timber-js/app/cookies';
- * import { fromSchema } from '@timber-js/app/search-params';
  * import { z } from 'zod/v4';
  *
+ * // httpOnly: false — client methods available
  * export const themeCookie = defineCookie('theme', {
- *   codec: fromSchema(z.enum(['light', 'dark', 'system']).default('system')),
+ *   codec: z.enum(['light', 'dark', 'system']).default('system'),
  *   httpOnly: false,
  *   maxAge: 60 * 60 * 24 * 365,
  * });
+ *
+ * // Server or client
+ * const theme = themeCookie.get();
+ * themeCookie.set('dark');
+ *
+ * // Client hook
+ * const [theme, setTheme] = themeCookie.useCookie();
+ *
+ * // httpOnly: true (default) — server-only, no client methods
+ * export const sessionCookie = defineCookie('session', {
+ *   codec: z.string(),
+ * });
+ * sessionCookie.get();       // works on server
+ * sessionCookie.useCookie(); // TS error — httpOnly cookie
  * ```
  */
-export function defineCookie<T>(
+export function defineCookie<T, HttpOnly extends boolean = true>(
   name: string,
-  options: DefineCookieOptions<T>
-): CookieDefinition<T> {
-  const { codec, ...cookieOpts } = options;
+  options: DefineCookieOptions<T, HttpOnly>
+): HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T> {
+  const { codec: codecOrSchema, ...cookieOpts } = options;
+  const codec = resolveCodec(codecOrSchema);
   const resolvedOptions: CookieOptions = { ...cookieOpts };
+  const isHttpOnly = options.httpOnly !== false; // default true
+
+  function getClientOpts(): ClientCookieOptions {
+    return {
+      path: resolvedOptions.path,
+      domain: resolvedOptions.domain,
+      maxAge: resolvedOptions.maxAge,
+      expires: resolvedOptions.expires,
+      sameSite: resolvedOptions.sameSite,
+      secure: resolvedOptions.secure,
+    };
+  }
 
-  return {
+  const base: ServerOnlyCookieDefinition<T> = {
     name,
     options: resolvedOptions,
     codec,
 
     get(): T {
-      const jar = cookies();
-      const raw = resolvedOptions.signed ? jar.getSigned(name) : jar.get(name);
+      const serverJar = tryGetServerCookieJar();
+      if (serverJar) {
+        return codec.parse(serverJar.get(name));
+      }
+      // Client path
+      if (isHttpOnly) {
+        throw new Error(
+          `[timber] defineCookie('${name}').get() cannot be used with httpOnly cookies — ` +
+            `the browser cannot access them. Set httpOnly: false to enable client access.`
+        );
+      }
+      const raw = getCookieValue(name);
       return codec.parse(raw);
     },
 
     set(value: T): void {
+      const serverJar = tryGetServerCookieJar();
+      if (serverJar) {
+        const serialized = codec.serialize(value);
+        if (serialized === null) {
+          serverJar.delete(name, {
+            path: resolvedOptions.path,
+            domain: resolvedOptions.domain,
+          });
+        } else {
+          serverJar.set(name, serialized, resolvedOptions);
+        }
+        return;
+      }
+      // Client path
+      if (isHttpOnly) {
+        throw new Error(
+          `[timber] defineCookie('${name}').set() cannot be used with httpOnly cookies — ` +
+            `the browser cannot access them. Set httpOnly: false to enable client access.`
+        );
+      }
       const serialized = codec.serialize(value);
       if (serialized === null) {
-        cookies().delete(name, {
-          path: resolvedOptions.path,
-          domain: resolvedOptions.domain,
-        });
+        deleteClientCookie(name, getClientOpts());
       } else {
-        cookies().set(name, serialized, resolvedOptions);
+        setClientCookie(name, serialized, getClientOpts());
       }
     },
 
     delete(): void {
-      cookies().delete(name, {
-        path: resolvedOptions.path,
-        domain: resolvedOptions.domain,
-      });
+      const serverJar = tryGetServerCookieJar();
+      if (serverJar) {
+        serverJar.delete(name, {
+          path: resolvedOptions.path,
+          domain: resolvedOptions.domain,
+        });
+        return;
+      }
+      // Client path
+      if (isHttpOnly) {
+        throw new Error(
+          `[timber] defineCookie('${name}').delete() cannot be used with httpOnly cookies — ` +
+            `the browser cannot access them. Set httpOnly: false to enable client access.`
+        );
+      }
+      deleteClientCookie(name, getClientOpts());
     },
+  };
 
-    useCookie(): [T, (value: T) => void, () => void] {
-      // Extract client-safe options (no httpOnly — client cookies can't be httpOnly)
-      const clientOpts: ClientCookieOptions = {
-        path: resolvedOptions.path,
-        domain: resolvedOptions.domain,
-        maxAge: resolvedOptions.maxAge,
-        expires: resolvedOptions.expires,
-        sameSite: resolvedOptions.sameSite,
-        secure: resolvedOptions.secure,
-      };
+  if (isHttpOnly) {
+    return base as HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T>;
+  }
 
+  // httpOnly: false — add useCookie client hook
+  const full: CookieDefinition<T> = {
+    ...base,
+
+    useCookie(): [T, (value: T) => void, () => void] {
+      const clientOpts = getClientOpts();
       const [raw, setRaw, deleteRaw] = useRawCookie(name, clientOpts);
       const parsed = codec.parse(raw);
 
@@ -134,4 +312,6 @@ export function defineCookie<T>(
       return [parsed, setTyped, deleteRaw];
     },
   };
+
+  return full as HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T>;
 }