docs(skills): Improve skills

Author: ntucker

.cursor/skills/data-client-schema/SKILL.md

@@ -65,8 +65,8 @@ to represent the data expected.
 
 ## 3. Entity lifecycle methods
 
-- Normalize order: `process()` → `pk()` → [validate()](references/validation.md) → **visit nested schemas** (recurse into `schema` fields) → `mergeWithStore()` which calls `shouldUpdate()` and maybe `shouldReorder()` + `merge()`; metadata via `mergeMetaWithStore()`.
-- Denormalize order: `createIfValid()` → [validate()](references/validation.md) → `fromJS()` → **unvisit nested schemas** (recurse into `schema` fields).
+- **Normalize** (JSON response → cache): operates on POJOs; output is JSON-serializable plain data stored in the normalized cache. Order: `process()` → `pk()` → [validate()](references/validation.md) → **visit nested schemas** (recurse into `schema` fields) → if existing: `mergeWithStore()` which calls `shouldUpdate()` and maybe `shouldReorder()` + `merge()`; metadata via `mergeMetaWithStore()`.
+- **Denormalize** (cache → component): creates Entity **class instances** via `fromJS()`, restoring prototype chain so getters, methods, and `schema` processing work. Order: `createIfValid()` → [validate()](references/validation.md) → `fromJS()` → **unvisit nested schemas** (recurse into `schema` fields).
 
 ---
 
@@ -105,11 +105,20 @@ export const EventResource = resource({
 
 ### pk routing
 
-`pk()` uses `nestKey(parent, key)` when nested in an Entity and available; otherwise it uses `argsKey(...args)`, then serializes the result. Without options, it defaults to `argsKey: params => ({ ...params })`, using all endpoint args as the collection key. Provide both `argsKey` and `nestKey` to reuse one Collection definition top-level and nested.
+`pk()` uses `nestKey(parent, key)` when nested in an Entity and available; otherwise it uses `argsKey(...args)`, then serializes the result. Without options, it defaults to `argsKey: params => ({ ...params })`, using all endpoint args as the collection key.
 
 - `argsKey` — derive pk from endpoint arguments (default)
 - `nestKey` — derive pk from parent entity for nested shared-state collections
 
+Define **both** on the same `Collection` to reuse one definition top-level and nested. When `argsKey(args)` and `nestKey(parent)` produce the same object shape, the top-level fetch and the nested read resolve to the **same (referentially equal) array/map** — push/unshift/assign/move/remove on either updates both:
+
+```ts
+const userTodos = new Collection([Todo], {
+  argsKey: ({ userId }: { userId?: string }) => ({ userId }),
+  nestKey: (parent: User) => ({ userId: parent.id }),
+});
+```
+
 ### nonFilterArgumentKeys
 
 Default `createCollectionFilter` uses `nonFilterArgumentKeys` (default: keys starting with `'order'`) to exclude non-filter args when matching collections. This affects which existing collections receive new items from `push`/`unshift`/`assign`/`move`.

.cursor/skills/data-client-vue-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: data-client-vue-testing
-description: Test @data-client/vue composables and components - renderDataCompose, mountDataClient, fixtures, jest, nock, Vue 3 reactive props, useSuspense testing
+description: Test @data-client/vue composables and components - renderDataCompose, mountDataClient, fixtures, jest, nock HTTP mocking, polling/subscription tests with fake timers, useSuspense, useLive, useSubscription, Vue 3 reactive props
 license: Apache 2.0
 ---
 
@@ -251,73 +251,63 @@ await nextTick();
 
 ## Testing with nock (HTTP Mocking)
 
+Use nock when a test must exercise the real fetch path — verifying URL construction, headers, request bodies, retries, or anything in your `RestEndpoint`/`Resource` networking layer. For pure store/state behavior, prefer `initialFixtures`/`resolverFixtures` (lighter and faster).
+
+Minimal shape:
+
 ```typescript
 import nock from 'nock';
 
 beforeAll(() => {
   nock(/.*/)
     .persist()
-    .defaultReplyHeaders({
-      'Access-Control-Allow-Origin': '*',
-      'Content-Type': 'application/json',
-    })
-    .options(/.*/)
-    .reply(200)
-    .get('/article/5')
-    .reply(200, { id: 5, title: 'hi ho' });
+    .defaultReplyHeaders({ 'Access-Control-Allow-Origin': '*', 'Content-Type': 'application/json' })
+    .options(/.*/).reply(200)            // CORS preflight (required in JSDOM)
+    .get('/article/5').reply(200, { id: 5, title: 'hi ho' });
 });
 
-afterAll(() => {
-  nock.cleanAll();
-});
+afterAll(() => nock.cleanAll());
 ```
 
-**Dynamic responses with nock:**
-```typescript
-const fetchMock = jest.fn(() => payload);
-nock(/.*/)
-  .get(`/article/${payload.id}`)
-  .reply(200, fetchMock);
+For dynamic server state, mutating-closure replies, request spying with `jest.fn()`, error responses, and mixing nock with fixtures, see [references/nock-http-mocking.md](references/nock-http-mocking.md).
 
-// Later verify:
-expect(fetchMock).toHaveBeenCalledTimes(1);
-```
+## Testing Polling and Subscriptions
 
-## Testing Polling/Subscriptions
+For composables with `pollFrequency`, `useLive`, or `useSubscription`, use fake timers so polls fire deterministically. Core flow:
+
+1. `jest.useFakeTimers()` **before** mount/render (so the interval is created under fake timers).
+2. Render, then `jest.advanceTimersByTime(frequency)` to drive the initial fetch.
+3. Mutate the response (e.g. `responseMock.mockReturnValue(...)`), advance time again, `await allSettled()` and `await nextTick()`.
+4. Restore real timers in `afterEach`: `jest.useRealTimers()`.
+
+Quick example:
 
 ```typescript
-it('should poll and update', async () => {
-  jest.useFakeTimers();
-  let serverData = { id: 5, title: 'Original' };
+jest.useFakeTimers();
+const responseMock = jest.fn(() => payload);
 
-  nock(/.*/)
-    .persist()
-    .get('/article/5')
-    .reply(200, () => serverData);
-
-  const { wrapper } = mountDataClient(PollingComponent);
-  
-  // Wait for initial render
-  for (let i = 0; i < 100 && !wrapper.find('h3').exists(); i++) {
-    await jest.advanceTimersByTimeAsync(frequency / 10);
-    await nextTick();
-  }
-  expect(wrapper.find('h3').text()).toBe('Original');
+const { result, allSettled, waitForNextUpdate, cleanup } = await renderDataCompose(
+  () => useSuspense(PollingArticleResource.get, { id: payload.id }),
+  { resolverFixtures: [{ endpoint: PollingArticleResource.get, response: responseMock }] },
+);
 
-  // Simulate server update
-  serverData = { id: 5, title: 'Updated' };
+jest.advanceTimersByTime(frequency);
+await allSettled();
+await waitForNextUpdate();
+const articleRef = await result;
 
-  // Advance timers to trigger poll
-  for (let i = 0; i < 20 && wrapper.find('h3').text() !== 'Updated'; i++) {
-    await jest.advanceTimersByTimeAsync(frequency / 10);
-    await nextTick();
-  }
-  expect(wrapper.find('h3').text()).toBe('Updated');
+responseMock.mockReturnValue({ ...payload, title: 'updated' });
+jest.advanceTimersByTime(frequency);
+await allSettled();
+await nextTick();
 
-  jest.useRealTimers();
-});
+expect(articleRef!.value.title).toBe('updated');
+jest.useRealTimers();
+cleanup();
 ```
 
+For unsubscribe patterns, component-level polling tests, fake-timer-safe `flushUntil`, polling via nock, and common pitfalls, see [references/polling-subscriptions.md](references/polling-subscriptions.md).
+
 ## Vue Suspense Behavior
 
 **useSuspense() returns Promise → ComputedRef:**
@@ -380,6 +370,8 @@ For detailed API documentation, see the [references](references/) directory:
 
 - [Fixtures](references/Fixtures.md) - Fixture format reference
 - [unit-testing-hooks](references/unit-testing-hooks.md) - Hook/composable testing guide
+- [nock-http-mocking](references/nock-http-mocking.md) - Full nock setup, dynamic server state, request spying, errors, pitfalls
+- [polling-subscriptions](references/polling-subscriptions.md) - Fake-timer patterns for `useLive`/`useSubscription`/`pollFrequency`, unsubscribe verification, polling via nock
 
 ## Common Patterns
 

.cursor/skills/data-client-vue-testing/references/nock-http-mocking.md

@@ -0,0 +1,133 @@
+# Nock HTTP Mocking (Vue Testing)
+
+Use `nock` instead of fixtures when you want a real fetch round-trip — for example, when verifying URL construction, headers, request bodies, retry logic, or anything that exercises the actual networking layer of your `RestEndpoint`/`Resource` definitions. For pure store/state behavior, prefer `initialFixtures`/`resolverFixtures` (lighter, faster, no global setup).
+
+## Standard Setup
+
+CORS preflight handling and a permissive default header set are required because the test environment runs in JSDOM and `fetch` performs OPTIONS preflights for non-simple requests.
+
+```typescript
+import nock from 'nock';
+
+beforeAll(() => {
+  nock(/.*/)
+    .persist()
+    .defaultReplyHeaders({
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Headers': 'Access-Token',
+      'Content-Type': 'application/json',
+    })
+    .options(/.*/)
+    .reply(200)
+    .get(`/article/${payload.id}`)
+    .reply(200, payload)
+    .put(`/article/${payload.id}`)
+    .reply(200, (uri, requestBody: any) => ({
+      ...payload,
+      ...requestBody,
+    }));
+});
+
+afterAll(() => {
+  nock.cleanAll();
+});
+```
+
+Key points:
+
+- `nock(/.*/)` matches any host (matches your `urlPrefix` whether it's `/`, `https://example.com`, etc.).
+- `.persist()` keeps the interceptors alive across multiple requests in the test file. Without it, each interceptor fires once and is consumed.
+- `.options(/.*/).reply(200)` blanket-handles preflight — without it, mutations like PUT/POST/DELETE will hang or fail in JSDOM.
+
+## Dynamic Server State
+
+To simulate a server whose data changes during the test (mutations, polling, optimistic updates), reply with a function that returns a closure-bound variable. Reassign the variable to "update the server".
+
+```typescript
+let currentPayload = { ...payload };
+
+beforeAll(() => {
+  nock(/.*/)
+    .persist()
+    .defaultReplyHeaders({
+      'Access-Control-Allow-Origin': '*',
+      'Content-Type': 'application/json',
+    })
+    .options(/.*/)
+    .reply(200)
+    .get(`/article/${payload.id}`)
+    .reply(200, () => currentPayload)
+    .put(`/article/${payload.id}`)
+    .reply(200, (uri, requestBody: any) => ({
+      ...currentPayload,
+      ...requestBody,
+    }));
+});
+
+it('reflects updated server data on next fetch', async () => {
+  // ... initial render ...
+
+  // Mutate "server" state
+  currentPayload = { ...currentPayload, title: 'updated' };
+
+  // Trigger a refetch (e.g. via controller.fetch, polling, or invalidate)
+  // ... assert new value ...
+});
+```
+
+## Spying on Requests
+
+Use `jest.fn()` as the reply handler to assert call counts and inspect request bodies.
+
+```typescript
+const fetchMock = jest.fn(() => payload);
+
+nock(/.*/)
+  .persist()
+  .defaultReplyHeaders({ 'Access-Control-Allow-Origin': '*' })
+  .options(/.*/)
+  .reply(200)
+  .get(`/article/${payload.id}`)
+  .reply(200, fetchMock);
+
+// ... run test interactions ...
+
+expect(fetchMock).toHaveBeenCalledTimes(1);
+```
+
+For mutations, the second argument to the reply callback is the request body:
+
+```typescript
+const updateMock = jest.fn((uri, requestBody) => ({ ...payload, ...requestBody }));
+
+nock(/.*/)
+  .persist()
+  .put(`/article/${payload.id}`)
+  .reply(200, updateMock);
+```
+
+## Errors and Status Codes
+
+```typescript
+nock(/.*/)
+  .get('/article/missing')
+  .reply(404, { detail: 'not found' });
+
+nock(/.*/)
+  .get('/article/broken')
+  .replyWithError('network down');
+```
+
+When testing error paths in components, also catch the error in your composable or wrap with `AsyncBoundary` so the test doesn't fail with an unhandled rejection.
+
+## Combining nock With Fixtures
+
+You can mix both within the same test file: use `initialFixtures` to pre-populate store state cheaply, and let nock handle any subsequent live requests (refetch, polling, mutation). The store will hydrate from fixtures first, then nock interceptors take over for actual fetches.
+
+## Common Pitfalls
+
+- **Hanging mutations** → missing `.options(/.*/).reply(200)` for CORS preflight.
+- **Interceptor consumed after one call** → forgot `.persist()`.
+- **Stale data after "server update"** → you reassigned the closure variable but never triggered a new fetch (no poll, no invalidate, no controller.fetch).
+- **`Nock: No match for request`** → the URL or method differs from what your endpoint actually sends. Add `nock.recorder.rec()` temporarily, or check `urlPrefix` and `path` template substitution.
+- **Cross-test pollution** → always `nock.cleanAll()` in `afterAll` (or `afterEach` for stricter isolation).