@pattern-stack/frontend-patterns 0.2.0-alpha.18 → 0.2.0-alpha.20

package/dist/sync/createStore.d.ts

@@ -1,14 +1,39 @@
-import type { EntityHooks } from './types.js';
+import type { EntityHooks, LookupsEngine, UseDataOptions, UseDataResult } from './types.js';
+/**
+ * Row constraint shared by entity hooks — every entity row has an optional id.
+ */
+type AnyRow = object & {
+    id?: string | null;
+};
 /**
  * Configuration for store creation.
+ *
+ * `fields` and `lookups` are OPTIONAL — existing callers (and `useList`/
+ * `useGet`/mutations) keep working unchanged when they're omitted.
+ *
  * Uses `any` for collection types to avoid version mismatch issues
  * with TanStack DB beta types across npm link boundaries.
+ *
+ * @template TFields - Per-entity FieldMeta record map (consumer/codegen-owned;
+ *   the sync layer treats each entry generically — it never imports FieldMeta).
+ * @template TLookups - The hydrated lookups shape (consumer/codegen-owned).
  */
-export interface StoreConfig {
+export interface StoreConfig<TFields extends Record<string, any> = Record<string, unknown>, TLookups = unknown> {
     /** Entity hooks keyed by name */
     entities: Record<string, EntityHooks<any, any, any>>;
     /** Collections keyed by name */
     collections: Record<string, any>;
+    /**
+     * NEW — generated per-entity FieldMeta record, keyed by the same plural names
+     * as `entities`. Surfaced by `useData().meta`. Treated generically: the per
+     * entity meta type is `TFields[plural]`; the sync layer never inspects it.
+     */
+    fields?: TFields;
+    /**
+     * NEW — cross-entity lookups engine. `useData` hydrates it once on mount and
+     * returns `lookups.current`. See {@link LookupsEngine}.
+     */
+    lookups?: LookupsEngine<TLookups>;
 }
 /**
  * Resolver functions for FK lookups.
@@ -28,38 +53,76 @@ export interface Lookups {
     current: Record<string, LookupMap<unknown>> | null;
     clear: () => void;
 }
+/**
+ * The unified `useData` hook signature attached to each `store.<entity>`.
+ *
+ * @template TRow - The entity row type
+ * @template TMeta - The per-entity FieldMeta record (consumer/codegen-owned)
+ * @template TLookups - The hydrated lookups shape (consumer/codegen-owned)
+ */
+export type UseDataHook<TRow extends AnyRow, TMeta, TLookups> = (opts?: UseDataOptions) => UseDataResult<TRow, TMeta, TLookups>;
+/**
+ * An entity's hooks augmented with the store-level `useData` primitive.
+ *
+ * `useData` lives here (not on {@link EntityHooks}) because it composes
+ * cross-entity `lookups` + per-entity `fields`, which only the store knows.
+ *
+ * @template TEntity - The entity hooks (inferred per entity)
+ * @template TMeta - The per-entity FieldMeta type for this entity
+ * @template TLookups - The hydrated lookups shape
+ */
+export type EntityWithData<TEntity, TMeta, TLookups> = TEntity & (TEntity extends EntityHooks<infer TRow, any, any> ? {
+    useData: UseDataHook<TRow & AnyRow, TMeta, TLookups>;
+} : {
+    useData: UseDataHook<AnyRow, TMeta, TLookups>;
+});
 /**
  * The store type.
+ *
+ * Each entity gains `useData` (typed against its `fields[K]` meta, if provided,
+ * and the shared lookups type).
+ *
+ * @template TEntities - Entity hooks map
+ * @template TFields - Per-entity FieldMeta record map
+ * @template TLookups - Hydrated lookups shape
  */
-export type Store<TEntities extends Record<string, EntityHooks<any, any, any>>> = {
-    [K in keyof TEntities]: TEntities[K];
+export type Store<TEntities extends Record<string, EntityHooks<any, any, any>>, TFields extends Record<string, any> = Record<string, unknown>, TLookups = unknown> = {
+    [K in keyof TEntities]: EntityWithData<TEntities[K], K extends keyof TFields ? TFields[K] : unknown, TLookups>;
 } & {
     /** Direct collection access (for advanced use) */
     collections: Record<string, any>;
     /** FK resolution */
     resolve: Resolvers;
-    /** Lookup maps */
+    /** Lookup maps (legacy in-memory helper — distinct from the lookups engine) */
     lookups: Lookups;
 };
 /**
  * Create a typed store from entity hooks and collections.
  *
+ * Each `store.<entity>` exposes the existing `useList`/`useGet`/mutations plus a
+ * unified `useData()` — the data + metadata + pagination + hydration primitive.
+ * `useData` composes the entity's own `useList` (pagination/status, reused — not
+ * reimplemented) with per-entity `fields` meta and the cross-entity `lookups`
+ * engine (hydrated once on mount).
+ *
  * @example
  * ```typescript
  * export const store = createStore({
- *   entities: {
- *     transactions: transactionHooks,
- *     categories: categoryHooks,
- *   },
- *   collections: {
- *     transactions: transactionCollection,
- *     categories: categoryCollection,
- *   },
+ *   entities:    { people: peopleHooks, messages: messageHooks },
+ *   collections: { people: peopleCollection, messages: messageCollection },
+ *   fields:      { people: peopleFields, messages: messageFields },  // optional
+ *   lookups:     lookupsEngine,                                      // optional
  * })
+ *
+ * // typed: meta is the people FieldMeta record
+ * const { rows, meta, lookups, page, setPage } = store.people.useData({ pageSize: 50 })
  * ```
  */
-export declare function createStore<TEntities extends Record<string, EntityHooks<any, any, any>>>(config: {
+export declare function createStore<TEntities extends Record<string, EntityHooks<any, any, any>>, TFields extends Record<string, any> = Record<string, unknown>, TLookups = unknown>(config: {
     entities: TEntities;
     collections: Record<string, any>;
-}): Store<TEntities>;
+    fields?: TFields;
+    lookups?: LookupsEngine<TLookups>;
+}): Store<TEntities, TFields, TLookups>;
+export {};
 //# sourceMappingURL=createStore.d.ts.map

package/dist/sync/createStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createStore.d.ts","sourceRoot":"","sources":["../../src/sync/createStore.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;IAEpD,gCAAgC;IAEhC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,CAAC,UAAU,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,KAAK,OAAO,GAAG,SAAS,CAAA;CAC7E;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;AAEzC;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAA;IAC/C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,CAAA;IAClD,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,KAAK,CAAC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,IAAI;KAE/E,CAAC,IAAI,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC;CACrC,GAAG;IACF,kDAAkD;IAElD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAEhC,oBAAoB;IACpB,OAAO,EAAE,SAAS,CAAA;IAElB,kBAAkB;IAClB,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CACzB,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAC5D,MAAM,EAAE;IACR,QAAQ,EAAE,SAAS,CAAA;IAEnB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CACjC,GAAG,KAAK,CAAC,SAAS,CAAC,CAmDnB"}
+{"version":3,"file":"createStore.d.ts","sourceRoot":"","sources":["../../src/sync/createStore.ts"],"names":[],"mappings":"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"}

package/dist/sync/index.d.ts

@@ -1,6 +1,6 @@
 export { createEntityHooks } from './createEntityHooks.js';
 export { createStore } from './createStore.js';
 export { EntityStoreProvider, useStore } from './EntityStoreProvider.js';
-export type { EntityHookConfig, EntityHooks, EntityApi, EntityQueryKeys, ListParams, WhereClause, UseListOptions, UseGetOptions, UseListResult, UseGetResult, } from './types.js';
-export type { StoreConfig, Store, Resolvers, Lookups, LookupMap, } from './createStore.js';
+export type { EntityHookConfig, EntityHooks, EntityApi, EntityQueryKeys, Page, ListQuery, ListParams, WhereClause, UseListOptions, UseGetOptions, UseListResult, UseGetResult, UseDataOptions, UseDataResult, LookupsEngine, SortSpec, } from './types.js';
+export type { StoreConfig, Store, Resolvers, Lookups, LookupMap, EntityWithData, } from './createStore.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/sync/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AAExE,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,eAAe,EACf,UAAU,EACV,WAAW,EACX,cAAc,EACd,aAAa,EACb,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAA;AAEnB,YAAY,EACV,WAAW,EACX,KAAK,EACL,SAAS,EACT,OAAO,EACP,SAAS,GACV,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AAExE,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,eAAe,EACf,IAAI,EACJ,SAAS,EACT,UAAU,EACV,WAAW,EACX,cAAc,EACd,aAAa,EACb,aAAa,EACb,YAAY,EACZ,cAAc,EACd,aAAa,EACb,aAAa,EACb,QAAQ,GACT,MAAM,YAAY,CAAA;AAEnB,YAAY,EACV,WAAW,EACX,KAAK,EACL,SAAS,EACT,OAAO,EACP,SAAS,EACT,cAAc,GACf,MAAM,kBAAkB,CAAA"}

package/dist/sync/types.d.ts

@@ -71,9 +71,9 @@ export interface EntityApi<TEntity, TCreate, TUpdate> {
     /**
      * Fetch a list of entities with optional filtering/pagination.
      * @param params - Optional list parameters
-     * @returns Promise resolving to array of entities
+     * @returns Promise resolving to a {@link Page} envelope of entities
      */
-    list(params?: ListParams): Promise<TEntity[]>;
+    list(params?: ListQuery): Promise<Page<TEntity>>;
     /**
      * Fetch a single entity by ID.
      * @param id - The entity ID
@@ -107,31 +107,86 @@ export interface EntityApi<TEntity, TCreate, TUpdate> {
     }>;
 }
 /**
- * Common list parameters for API queries.
+ * Pagination request parameters sent to `api.list`.
+ *
+ * This is the request half of the pagination contract. The generated API
+ * client serializes these into the list endpoint's querystring; the backend
+ * returns a {@link Page} envelope. Engine is page-based (OFFSET) in v1, but
+ * `cursor` is part of the contract from day one (the keyset request-honoring
+ * upgrade is a deferred, seam-internal change — passing a cursor is accepted).
+ *
+ * Arbitrary additional keys are treated as `where` filters (pagination is
+ * orthogonal to filtering).
  *
  * @example
  * ```typescript
- * const params: ListParams = {
- *   skip: 0,
- *   limit: 20,
+ * const query: ListQuery = {
+ *   page: 2,
+ *   pageSize: 50,
  *   sort_by: 'created_at',
  *   sort_order: 'desc',
- *   status: 'active',  // Additional filter
+ *   status: 'active',  // Additional where filter
  * }
  * ```
  */
-export interface ListParams {
-    /** Number of items to skip (for pagination) */
-    skip?: number;
-    /** Maximum number of items to return */
-    limit?: number;
+export interface ListQuery {
+    /** 1-based page number to fetch (default: 1) */
+    page?: number;
+    /** Opaque keyset cursor (contract-stable; v1 OFFSET engine ignores it for fetching) */
+    cursor?: string;
+    /** Page size — number of items per page (default: 50, clamped server-side) */
+    pageSize?: number;
     /** Field to sort by */
     sort_by?: string;
     /** Sort direction */
     sort_order?: 'asc' | 'desc';
-    /** Additional filter parameters */
+    /** Additional filter parameters (where clause) */
     [key: string]: unknown;
 }
+/**
+ * Pagination response envelope returned by `api.list`.
+ *
+ * This is the response half of the pagination contract — the shape every
+ * codegen-generated list endpoint returns. Extends the proven
+ * `{ items, nextCursor }` keyset shape (jobs subsystem `JobRunPage`,
+ * observability) with `total`/`page`/`pageCount`/`pageSize` for numbered,
+ * jump-to-page UIs.
+ *
+ * @template T - The entity type
+ *
+ * @example
+ * ```typescript
+ * const page: Page<Transaction> = {
+ *   items: [...],
+ *   page: 1,
+ *   pageCount: 4,
+ *   total: 187,
+ *   pageSize: 50,
+ *   nextCursor: 'eyJjcmVhdGVkQXQiOiIuLi4ifQ==',
+ * }
+ * ```
+ */
+export interface Page<T> {
+    /** The rows for the current page */
+    items: T[];
+    /** 1-based number of the current page */
+    page: number;
+    /** Total number of pages for the (filtered) set */
+    pageCount: number;
+    /** Total number of rows in the (filtered) set, across all pages */
+    total: number;
+    /** Number of items per page */
+    pageSize: number;
+    /** Opaque cursor for the next page; null on the last page */
+    nextCursor: string | null;
+}
+/**
+ * Common list parameters for API queries.
+ *
+ * @deprecated Use {@link ListQuery} instead — `skip`/`limit` were never honored
+ * by `useList`. Retained as an alias for source compatibility; will be removed.
+ */
+export type ListParams = ListQuery;
 /**
  * Type-safe filter where value types match field types.
  *
@@ -162,23 +217,28 @@ export type WhereClause<TEntity> = {
  * const options: UseListOptions<Transaction> = {
  *   where: { state: 'active' },
  *   orderBy: { field: 'created_at', direction: 'desc' },
- *   skip: 0,
- *   limit: 20,
+ *   page: 2,
+ *   pageSize: 50,
  * }
  * ```
  */
 export interface UseListOptions<TEntity> {
-    /** Filter criteria - applied client-side to collection */
+    /** Filter criteria - sent to the server AND applied client-side to the page */
     where?: WhereClause<TEntity>;
     /** Sort configuration */
     orderBy?: {
         field: keyof TEntity;
         direction: 'asc' | 'desc';
     };
-    /** Number of items to skip (for pagination) */
-    skip?: number;
-    /** Maximum number of items to return */
-    limit?: number;
+    /**
+     * Initial 1-based page to fetch (default: 1). `useList` owns the live page
+     * state thereafter — use the returned `setPage`/`next`/`prev` to navigate.
+     */
+    page?: number;
+    /** Opaque keyset cursor (contract-stable; v1 OFFSET engine ignores it for fetching) */
+    cursor?: string;
+    /** Page size — number of items per page (default: server default, typically 50) */
+    pageSize?: number;
     /** Enable hook (default: true) */
     enabled?: boolean;
 }
@@ -203,16 +263,25 @@ export interface UseGetOptions {
  *
  * @example
  * ```typescript
- * const { data, isLoading, error, refetch, collection } = useTransactionList()
+ * const {
+ *   data, isLoading, error, refetch, collection,
+ *   page, pageCount, total, pageSize,
+ *   setPage, next, prev, hasNext, hasPrev,
+ * } = useTransactionList({ pageSize: 50 })
  *
  * if (isLoading) return <Spinner />
  * if (error) return <Error message={error.message} />
  *
- * return <DataTable data={data} />
+ * return (
+ *   <>
+ *     <DataTable data={data} />
+ *     <Pagination page={page} pageCount={pageCount} onPageChange={setPage} />
+ *   </>
+ * )
  * ```
  */
 export interface UseListResult<TEntity extends object> {
-    /** Array of entities (empty array if loading or error) */
+    /** The current page's entities (empty array if loading or error) */
     data: TEntity[];
     /** True while initial data is loading */
     isLoading: boolean;
@@ -224,6 +293,24 @@ export interface UseListResult<TEntity extends object> {
     refetch: () => void;
     /** Direct collection access for mutations */
     collection: Collection<TEntity, string>;
+    /** 1-based number of the current page */
+    page: number;
+    /** Total number of pages for the (filtered) set */
+    pageCount: number;
+    /** Total number of rows in the (filtered) set, across all pages */
+    total: number;
+    /** Number of items per page */
+    pageSize: number;
+    /** Jump to a specific 1-based page (clamped to [1, pageCount]) and refetch */
+    setPage: (page: number) => void;
+    /** Advance to the next page (no-op when on the last page) */
+    next: () => void;
+    /** Go back to the previous page (no-op when on the first page) */
+    prev: () => void;
+    /** True when a next page exists (page < pageCount) */
+    hasNext: boolean;
+    /** True when a previous page exists (page > 1) */
+    hasPrev: boolean;
 }
 /**
  * Result type for single entity hooks.
@@ -255,6 +342,112 @@ export interface UseGetResult<TEntity extends object> {
     /** Direct collection access for mutations */
     collection: Collection<TEntity, string>;
 }
+/**
+ * Cross-entity lookups engine consumed by the unified `useData` hook.
+ *
+ * Hydrates the FK-resolution sets used to render related entities (e.g. a
+ * message's author). Generated/consumer code provides the implementation; the
+ * sync layer treats `TLookups` generically (it never inspects the shape).
+ *
+ * Contract (matches codegen's emitted `createStore({ lookups })`):
+ * - `hydrate()` is called ONCE on mount of the first `useData` that needs it
+ *   (idempotent — callers may invoke it repeatedly; the engine should dedupe).
+ * - `current` is the hydrated value, or `null` until hydration resolves.
+ *
+ * @template TLookups - The hydrated lookups shape (consumer/codegen-owned)
+ *
+ * @example
+ * ```typescript
+ * const lookups: LookupsEngine<MyLookups> = {
+ *   hydrate: async () => { ... },        // fetch + cache, idempotent
+ *   get current() { return cache },      // null until ready
+ * }
+ * ```
+ */
+export interface LookupsEngine<TLookups = unknown> {
+    /** Hydrate the lookup sets once; resolves when ready. Should be idempotent. */
+    hydrate: () => Promise<TLookups>;
+    /** The hydrated lookups, or null until hydration resolves. */
+    readonly current: TLookups | null;
+}
+/**
+ * Result type for the unified `useData` hook.
+ *
+ * Composes the pagination + status surface of {@link UseListResult} (reused,
+ * not reimplemented) with entity FieldMeta (`meta`), hydrated cross-entity
+ * `lookups`, a stable `getRowId`, and reserved (inert, typed-not-wired) sort /
+ * filter slots for a future upgrade.
+ *
+ * @template TRow - The entity row type
+ * @template TMeta - The per-entity FieldMeta record (consumer/codegen-owned)
+ * @template TLookups - The hydrated lookups shape (consumer/codegen-owned)
+ *
+ * @example
+ * ```typescript
+ * const { rows, meta, lookups, page, setPage, total } =
+ *   store.people.useData({ pageSize: 50 })
+ * ```
+ */
+export interface UseDataResult<TRow extends object, TMeta = unknown, TLookups = unknown> {
+    /** The current page's rows */
+    rows: TRow[];
+    /** True while initial data is loading */
+    isLoading: boolean;
+    /** True if an error occurred */
+    isError: boolean;
+    /** Error object if an error occurred, null otherwise */
+    error: Error | null;
+    /** Function to manually refetch data */
+    refetch: () => void;
+    /** 1-based number of the current page */
+    page: number;
+    /** Total number of pages for the (filtered) set */
+    pageCount: number;
+    /** Total number of rows in the (filtered) set, across all pages */
+    total: number;
+    /** Number of items per page */
+    pageSize: number;
+    /** Jump to a specific 1-based page (clamped) and refetch */
+    setPage: (page: number) => void;
+    /** Advance to the next page (no-op on the last page) */
+    next: () => void;
+    /** Go back to the previous page (no-op on the first page) */
+    prev: () => void;
+    /** True when a next page exists */
+    hasNext: boolean;
+    /** True when a previous page exists */
+    hasPrev: boolean;
+    /** Stable row-id accessor (default: `(row) => row.id`) */
+    getRowId: (row: TRow) => string;
+    /** Per-entity FieldMeta record (from `createStore({ fields })`); undefined if not provided */
+    meta: TMeta | undefined;
+    /** Hydrated cross-entity lookups (from `createStore({ lookups })`); null until ready / if not provided */
+    lookups: TLookups | null;
+    /** RESERVED — current sort spec (always null in v1) */
+    sort: SortSpec<TRow> | null;
+    /** RESERVED — set the sort spec (no-op in v1) */
+    setSort: (sort: SortSpec<TRow> | null) => void;
+    /** RESERVED — current filter spec (always null in v1) */
+    filter: WhereClause<TRow> | null;
+    /** RESERVED — set the filter spec (no-op in v1) */
+    setFilter: (filter: WhereClause<TRow> | null) => void;
+}
+/**
+ * Sort specification for the reserved `useData` sort slot.
+ *
+ * @template TRow - The entity row type
+ */
+export interface SortSpec<TRow> {
+    field: keyof TRow;
+    direction: 'asc' | 'desc';
+}
+/**
+ * Options for the unified `useData` hook.
+ */
+export interface UseDataOptions {
+    /** Page size — number of items per page (default: server default, typically 50) */
+    pageSize?: number;
+}
 /**
  * Query key factory for cache management.
  *

package/dist/sync/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sync/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sync/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@pattern-stack/frontend-patterns",
   "description": "Production-ready React frontend template with atomic architecture patterns. Build ultra-lean applications by importing shared UI foundation patterns.",
   "private": false,
-  "version": "0.2.0-alpha.18",
+  "version": "0.2.0-alpha.20",
   "keywords": [
     "react",
     "typescript",
@@ -61,6 +61,7 @@
     "clean:temp": "rm -rf .playwright-mcp coverage .vite .turbo && find . -name '*.tgz' -delete && find . -name '.DS_Store' -delete",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
+    "lint:tokens": "node scripts/check-design-tokens.mjs",
     "lint:design-system": "eslint . --ext .tsx,.ts --config eslint.config.js",
     "style:check": "npm run lint:design-system",
     "style:fix": "npm run lint:fix && npm run style:check",