@agjs/tsforge 0.2.9 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agjs/tsforge",
   "type": "module",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "license": "MIT",
   "description": "TypeScript coding harness with a deterministic gate, stack-aware guardrails, and stream-level correction.",
   "repository": {

package/scripts/benchmark-catalog.ts

@@ -313,7 +313,7 @@ Co-locate by domain under \`src/features/<domain>/\`:
   <domain>.types.ts        — entity types, discriminated unions, branded IDs
   <domain>.constants.ts    — \`as const\` registries / label maps (typed Record<Union, V>)
   <domain>.service.ts      — async data access (seeded/mock async with latency + failure paths)
-  <domain>.hooks.ts        — ONLY genuine derived/computed state (the data hook is the SDK's useCollection; do NOT write a fetch/query wrapper)
+  <domain>.hooks.ts        — ONLY genuine derived/computed state (the data hook is the SDK's useResource; do NOT write a fetch/query wrapper)
   <PascalCase>.tsx         — ONE component per file
   index.ts                 — barrel re-exporting the public surface
 Shared shadcn primitives live in \`src/components/ui/\` (already scaffolded). Routes/pages are TanStack files under \`src/routes/\`.

package/src/agent/model-agent.ts

@@ -10,6 +10,7 @@ import { readFiles, type IFileView } from "../lib/fs";
 import { EDIT_TOOL, CREATE_TOOL, TOOL_NAME } from "./agent.constants";
 import { toEdits, toCreate } from "./tools";
 import { ruleHelp } from "../loop/feedback";
+import { DEFAULT_TEMPERATURE } from "../loop/loop.constants";
 
 /**
  * The errors the agent can actually act on: those in its editable files (plus
@@ -54,7 +55,7 @@ export function modelAgent(
           toolChoice: "auto",
           // Temp 0 by default — the eval sweep showed it's decisively better for
           // convergence on coding tasks (temp 0: 100% pass vs temp 0.5: 0%).
-          temperature: options.temperature ?? 0,
+          temperature: options.temperature ?? DEFAULT_TEMPERATURE,
           // Cap reasoning so the quality-repair pass can't ramble unbounded
           // ("writing novels"): the budget that bounds the implement loop must
           // bound this agent too, or the cap leaks.

package/src/browser/oracle.ts

@@ -389,20 +389,11 @@ async function crawlRoutes(
   for (const route of routes) {
     try {
       await page.goto(`${base}${route}`, { waitUntil: "load", timeout });
-      // Let the client router + first paint settle before the blank check (the
-      // shell/nav renders immediately, so this only flags genuinely dead routes).
-      await page.waitForTimeout(150);
 
-      const blank = await page.evaluate(() => {
-        const root =
-          document.querySelector("#root") ??
-          document.querySelector("#app") ??
-          document.body;
-
-        return root.children.length === 0 || root.textContent.trim() === "";
-      });
-
-      if (blank) {
+      // Poll for first paint before the blank check, so a route that mounts
+      // ASYNCHRONOUSLY (after MSW's worker.start() resolves, or any await-before-
+      // render bootstrap) isn't misjudged dead. Only a genuinely empty root fails.
+      if (!(await waitForMount(page))) {
         errors.push(`route ${route} rendered blank`);
         continue;
       }
@@ -433,15 +424,30 @@ const SMOKE_CLICK_LIMIT = 5;
  * or console error surfaces via the page handlers wired in renderCheck. No per-app
  * knowledge, so it never needs the model to author (flaky) checks.
  */
-async function runSmoke(page: Page, errors: string[]): Promise<void> {
-  const mounted = await page.evaluate(() => {
-    const root =
-      document.querySelector("#root") ??
-      document.querySelector("#app") ??
-      document.body;
+/** Wait for the app to paint content into its root — polls up to `timeoutMs`, so an
+ *  app that renders ASYNCHRONOUSLY (after MSW's worker.start() resolves, or any
+ *  await-before-mount bootstrap) is not misjudged "blank" by a check that fires the
+ *  instant `load` does. Returns true once mounted, false on timeout. */
+async function waitForMount(page: Page, timeoutMs = 5000): Promise<boolean> {
+  return page
+    .waitForFunction(
+      () => {
+        const root =
+          document.querySelector("#root") ??
+          document.querySelector("#app") ??
+          document.body;
 
-    return root.children.length > 0 && root.textContent.trim() !== "";
-  });
+        return root.children.length > 0 && root.textContent.trim() !== "";
+      },
+      undefined,
+      { timeout: timeoutMs, polling: 100 }
+    )
+    .then(() => true)
+    .catch(() => false);
+}
+
+async function runSmoke(page: Page, errors: string[]): Promise<void> {
+  const mounted = await waitForMount(page);
 
   if (!mounted) {
     errors.push("app did not mount: root is blank after load");

package/src/detect-gate.ts

@@ -349,17 +349,53 @@ export function webGuidance(framework: WebFramework): string {
  *  progress to the terminal. Required before the gate's tsc + vite build can run.
  *  Skipped when deps are already present. Returns false on a failed install. */
 export async function installWebDeps(cwd: string): Promise<boolean> {
-  if (await Bun.file(join(cwd, "node_modules", ".bin", "vite")).exists()) {
-    return true;
+  if (!(await Bun.file(join(cwd, "node_modules", ".bin", "vite")).exists())) {
+    const proc = Bun.spawn(["bun", "install"], {
+      cwd,
+      stdout: "inherit",
+      stderr: "inherit",
+    });
+
+    if ((await proc.exited) !== 0) {
+      return false;
+    }
   }
 
-  const proc = Bun.spawn(["bun", "install"], {
-    cwd,
-    stdout: "inherit",
-    stderr: "inherit",
-  });
+  await initMswWorker(cwd);
 
-  return (await proc.exited) === 0;
+  return true;
+}
+
+/** Lay down `public/mockServiceWorker.js` via the MSW CLI — the in-browser mock
+ *  API the React scaffold relies on. The worker script is version-matched to the
+ *  installed msw (so we never ship a stale, version-pinned blob) and Vite copies
+ *  `public/` into `dist/`, so the gate's built-app smoke serves it at
+ *  `/mockServiceWorker.js`. No-op when msw isn't installed (e.g. the vanilla
+ *  scaffold) or the worker already exists; best-effort so it never breaks install. */
+async function initMswWorker(cwd: string): Promise<void> {
+  const hasMsw = await Bun.file(
+    join(cwd, "node_modules", "msw", "package.json")
+  ).exists();
+  const alreadyInit = await Bun.file(
+    join(cwd, "public", "mockServiceWorker.js")
+  ).exists();
+
+  if (!hasMsw || alreadyInit) {
+    return;
+  }
+
+  try {
+    // No `--save`: that rewrites package.json (non-prettier, fails the gate's
+    // format check) just to record the worker dir. The worker lands at the default
+    // `/mockServiceWorker.js`, which `worker.start()` finds without any config.
+    await Bun.spawn(["bunx", "msw", "init", "public"], {
+      cwd,
+      stdout: "inherit",
+      stderr: "inherit",
+    }).exited;
+  } catch {
+    // best-effort — a missing worker surfaces as a clear runtime error in the gate
+  }
 }
 
 /** The full web ladder: `vite build` + tsc strict + web eslint (vendored-exempt) +

package/src/lib/scope/scope.constants.ts

@@ -1,3 +1,23 @@
 /** A throwaway prefix the model may always write to — `scratch/` experiments are
  *  ignored by the gate, so it can test hypotheses by running code. */
 export const SCRATCH_PREFIX = "scratch/";
+
+/**
+ * VENDORED, harness-authored files the model must NEVER edit or create. These are
+ * tested, already-type-correct SDK/primitive/generated files: the web scaffold's
+ * `src/lib/**` toolkit, the `src/components/ui/**` primitives, the MSW mock
+ * machinery (`src/mocks/db.ts` + `src/mocks/browser.ts`), and any `*.gen.ts`
+ * codegen output (TanStack's route tree). They are eslint- and prettier-ignored,
+ * so a model that touches them sees tsc errors it cannot fix and — with
+ * eslint-disable + `@ts-*` suppressions banned — has no escape, looping to the
+ * turn cap. A write to any of these is rejected: a type error involving them is
+ * always a wrong CALL SITE, never the library. (`src/mocks/handlers.ts` is NOT
+ * vendored — the model registers its mock resources there.)
+ */
+export const VENDORED_PATTERNS = [
+  "src/lib/**",
+  "src/components/ui/**",
+  "src/mocks/db.ts",
+  "src/mocks/browser.ts",
+  "**/*.gen.ts",
+] as const;

package/src/lib/scope/scope.ts

@@ -1,5 +1,5 @@
 import { resolve, relative } from "node:path";
-import { SCRATCH_PREFIX } from "./scope.constants";
+import { SCRATCH_PREFIX, VENDORED_PATTERNS } from "./scope.constants";
 
 /**
  * Normalize a model-supplied path against the workspace root, fixing the common
@@ -27,6 +27,13 @@ export function isInScope(file: string, patterns: string[]): boolean {
   return patterns.some((pattern) => new Bun.Glob(pattern).match(file));
 }
 
+/** True when `file` is a VENDORED, harness-authored file the model must not
+ *  touch (`src/lib/**`, `src/components/ui/**`, the MSW machinery, `*.gen.ts`).
+ *  Expects the workspace-relative form (`normalizeWorkspacePath` first). */
+export function isVendored(file: string): boolean {
+  return VENDORED_PATTERNS.some((pattern) => new Bun.Glob(pattern).match(file));
+}
+
 /** A file the model may write: its editable scope, OR a throwaway scratch file.
  *  A path that escapes the workspace (`../…`) or is absolute is NEVER writable —
  *  a recursive glob would otherwise match a traversal path. Normalize with

package/src/loop/feedback/rule-docs.ts

@@ -144,6 +144,11 @@ const RULE_DOCS: Record<string, IRuleDoc> = {
     bad: "<ul>{items.filter((i) => i.visible).map((i) => <li key={i.id}>{i.label}</li>)}</ul>",
     good: "const rows = useMemo(() => items.filter(...).map(...), [items]); return <ul>{rows}</ul>;",
   },
+  "tsforge/no-loading-text-use-skeleton": {
+    what: "Loading states render a <Skeleton/> shaped like the content — never 'Loading…' text or a spinner. Add `skeleton` via scaffold_ui.",
+    bad: "if (isLoading) { return <p>Loading…</p>; }",
+    good: 'if (isLoading) { return <Skeleton className="h-8 w-full" />; }',
+  },
   "tsforge/no-state-in-component-body": {
     what: "State hooks (`useState`, `useEffect`, `useMemo`, …) belong in `Component.hooks.ts`, not in the `.tsx` component body.",
     bad: "export function Button() { const [open, setOpen] = useState(false); return <button />; }",

package/src/loop/loop.constants.ts

@@ -17,6 +17,10 @@ export const SPEC_STATUS = {
   blocked: "blocked",
 } as const;
 
+/** Default sampling temperature for main agent turns (Session, runTask, modelAgent).
+ *  Auxiliary one-shot calls (compaction, plan summary, judge) stay at 0. */
+export const DEFAULT_TEMPERATURE = 0.2;
+
 /**
  * Loop tuning — kept with the loop domain (not a global bucket). Each value's
  * rationale lives here so a tuning pass sees the whole budget at a glance.

package/src/loop/run.ts

@@ -3,7 +3,12 @@ import type { IChatMessage, IModelResponse, IProvider } from "../inference";
 import { validate, type ErrorParser } from "../validate";
 import { parseEslintJson } from "../validate";
 import { readFiles } from "../lib/fs";
-import { RUN_STATUS, STUCK_REASON, LOOP_LIMITS } from "./loop.constants";
+import {
+  DEFAULT_TEMPERATURE,
+  RUN_STATUS,
+  STUCK_REASON,
+  LOOP_LIMITS,
+} from "./loop.constants";
 import type {
   IRunResult,
   IRunOptions,
@@ -215,7 +220,7 @@ export async function runTask(
 ): Promise<IRunResult> {
   const { parse, enableThinking, thinkingTokenBudget } = opts;
   const effectiveParse = effectiveParserFor(parse);
-  const temperature = opts.temperature ?? 0;
+  const temperature = opts.temperature ?? DEFAULT_TEMPERATURE;
   const maxTurns = opts.maxTurns ?? LOOP_LIMITS.maxTurns;
   // Buffer every event so the post-run memory hook can mine the run for
   // failure→fix lessons, while still forwarding live to the real reporter.

package/src/loop/session.ts

@@ -27,7 +27,7 @@ import {
 } from "../config/tsforge-config";
 import { connectMcpServers } from "../mcp";
 import { loadAndRegisterPlugins } from "../config/external-plugins";
-import { LOOP_LIMITS, RUN_STATUS } from "./loop.constants";
+import { DEFAULT_TEMPERATURE, LOOP_LIMITS, RUN_STATUS } from "./loop.constants";
 import type { Reporter, ILoopEvent } from "./loop.types";
 import type { TtsrManager } from "./ttsr";
 import { initTtsrManager, applyTtsrInterrupt } from "./ttsr-init";
@@ -263,15 +263,16 @@ const INTERIM_CHECK_NOTE =
 const IMPLEMENT_STEP =
   "STEP 2 of 2 — build the app in THIS ORDER, so every file compiles the moment " +
   "you write it (each step depends only on earlier ones — no forward references):\n" +
-  "1) DATA LAYER — each domain's seed + service (`createCollection`). Small files; " +
-  "emit them together.\n" +
+  "1) DATA LAYER — each domain's faker seed (in <feature>.constants.ts) + ONE " +
+  "`mockResource('/api/x', SEED)` line registered in src/mocks/handlers.ts. Small " +
+  "files; emit them together.\n" +
   "2) ROUTES — call `scaffold_routes` ONCE with EVERY page the app needs (list, " +
   "detail with $param like /accounts/$accountId, and create/edit like " +
   "/deals/create). This writes all route files at once, so from here every " +
   "<Link to>/navigate target type-checks — NEVER hand-write a route file.\n" +
   "3) SHELL — the app-shell layout + nav linking those routes.\n" +
   "4) FILL, FEATURE BY FEATURE — replace each route's placeholder with its real " +
-  "component (import your types + `useCollection(service)` + @/components/ui + " +
+  "component (import your types + `useResource('/api/x')` + @/components/ui + " +
   "<Link> to any route). FINISH one feature before starting the next.\n" +
   "PACE: write ONE coherent slice per turn — a single feature's few files together " +
   "(or one file if it's large) — then let the gate check it. Do NOT dump the whole " +
@@ -1054,7 +1055,7 @@ export class Session {
 
     const res = await this.provider.complete(ctx.messages, {
       tools: offeredTools,
-      temperature: this.cfg.temperature ?? 0,
+      temperature: this.cfg.temperature ?? DEFAULT_TEMPERATURE,
       toolChoice,
       ...(enableThinking === undefined ? {} : { enableThinking }),
       ...(this.cfg.thinkingTokenBudget === undefined

package/src/loop/tools/file-ops.ts

@@ -2,7 +2,7 @@ import { join } from "node:path";
 import { applyEdits } from "../../files/edit";
 import { applyCreate } from "../../files/create";
 import { EDIT_FAIL_REASON } from "../../files";
-import { writable, normalizeWorkspacePath } from "../../lib/scope";
+import { writable, normalizeWorkspacePath, isVendored } from "../../lib/scope";
 import { LOOP_LIMITS } from "../loop.constants";
 import { toEdits, toCreate, toRun, toRead, runCommand } from "../../agent";
 import { ruleHelpFromOutput } from "../feedback/rule-docs";
@@ -179,6 +179,17 @@ export async function runShell(
   return `exit ${res.exitCode}\n${output}${guidance}`;
 }
 
+/**
+ * The rejection shown when the model tries to write a VENDORED file. These are
+ * tested, already-type-correct harness files (the SDK in `src/lib/`, the UI
+ * primitives in `src/components/ui/`, the MSW machinery, `*.gen.ts`). The whole
+ * point is to break the loop where a model "fixes" generic SDK types it can never
+ * satisfy: the message redirects it to its own call site.
+ */
+function vendoredRejectMessage(op: "edit" | "create", file: string): string {
+  return `${op} ${file} REJECTED: this is a VENDORED, already-type-correct harness file you must NOT modify. A type error involving it means the bug is at YOUR CALL SITE — fix how you USE it (the types/args you pass), not the file itself.`;
+}
+
 export async function doEdit(
   args: Record<string, unknown>,
   ctx: IToolContext
@@ -195,6 +206,14 @@ export async function doEdit(
 
   edit.file = normalizeWorkspacePath(ctx.cwd, edit.file);
 
+  if (isVendored(edit.file)) {
+    return reject(
+      ctx,
+      "edit:vendored",
+      vendoredRejectMessage("edit", edit.file)
+    );
+  }
+
   if (!writable(edit.file, ctx.files)) {
     return reject(
       ctx,
@@ -293,6 +312,14 @@ export async function doCreate(
 
   create.file = normalizeWorkspacePath(ctx.cwd, create.file);
 
+  if (isVendored(create.file)) {
+    return reject(
+      ctx,
+      "create:vendored",
+      vendoredRejectMessage("create", create.file)
+    );
+  }
+
   if (!writable(create.file, ctx.files)) {
     return reject(
       ctx,

package/src/loop/tools/scaffold-routes.ts

@@ -61,7 +61,7 @@ export async function doScaffoldRoutes(
     `scaffold_routes: created ${String(written.length)} NEW route stub(s)${keptNote}. ` +
     `It is ADDITIVE and safe to call again — it NEVER overwrites a route you've already ` +
     `built, only adds missing ones. New stubs are PLACEHOLDERS (data-tsforge-stub): replace ` +
-    `EACH with the real page (its list/detail/form using your types + useCollection(service) ` +
+    `EACH with the real page (its list/detail/form using your types + useResource('/api/x') ` +
     `+ @/components/ui). The gate FAILS while any stub remains. To FILL a route, EDIT its file ` +
     `directly — do NOT call scaffold_routes again to "reset" it.`
   );

package/src/meta-rules/context.ts

@@ -50,7 +50,14 @@ function collectSourceFiles(root: string): string[] {
         } else if (stat.isFile()) {
           const ext = extname(entry);
 
-          if (ext === ".ts" || ext === ".tsx") {
+          // Skip generated output (*.gen.ts — e.g. TanStack's route tree). It
+          // ships with `/* eslint-disable */` + `@ts-nocheck`, which the
+          // source-text meta-rules (no-eslint-disable-comments,
+          // no-ts-suppressions) would otherwise flag. The model cannot write
+          // *.gen.ts (vendored scope), so the only such file is harness/codegen
+          // output — hand-written files stay fully covered, keeping the bypass
+          // ban airtight where it matters.
+          if ((ext === ".ts" || ext === ".tsx") && !entry.endsWith(".gen.ts")) {
             out.push(rel);
           }
         }

package/src/rule-packs/react-component-architecture/index.ts

@@ -12,6 +12,7 @@ import { noCrossFeatureImportsRule } from "./rules/no-cross-feature-imports";
 import { noDerivedStateInEffectRule } from "./rules/no-derived-state-in-effect";
 import { noInlineJsxFunctionsRule } from "./rules/no-inline-jsx-functions";
 import { noJsxComputationRule } from "./rules/no-jsx-computation";
+import { noLoadingTextUseSkeletonRule } from "./rules/no-loading-text-use-skeleton";
 import { noNestedComponentRule } from "./rules/no-nested-component";
 import { noReactFcRule } from "./rules/no-react-fc";
 import { noStateInComponentBodyRule } from "./rules/no-state-in-component-body";
@@ -30,6 +31,7 @@ const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
   "no-derived-state-in-effect": noDerivedStateInEffectRule,
   "no-inline-jsx-functions": noInlineJsxFunctionsRule,
   "no-jsx-computation": noJsxComputationRule,
+  "no-loading-text-use-skeleton": noLoadingTextUseSkeletonRule,
   "no-nested-component": noNestedComponentRule,
   "no-react-fc": noReactFcRule,
   "no-state-in-component-body": noStateInComponentBodyRule,
@@ -53,6 +55,7 @@ export const reactComponentArchitecturePack: IRulePack = {
     "no-derived-state-in-effect": "warn",
     "no-inline-jsx-functions": "warn",
     "no-jsx-computation": "error",
+    "no-loading-text-use-skeleton": "error",
     "no-nested-component": "error",
     "no-react-fc": "error",
     "no-state-in-component-body": "error",

package/src/rule-packs/react-component-architecture/rules/no-loading-text-use-skeleton.ts

@@ -0,0 +1,63 @@
+import { type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import { isStoryFile, isTestFile } from "../utils";
+
+export const RULE_NAME = "no-loading-text-use-skeleton";
+
+type RuleOptions = [];
+type MessageIds = "useSkeleton";
+
+/** A loading PLACEHOLDER text node: "Loading", "Loading…", "Loading...",
+ *  "loading data" — the spinner-era text models reach for. Matched
+ *  case-insensitively against the trimmed text; an ordinary sentence that merely
+ *  CONTAINS the word "loading" mid-string is NOT flagged (anchored at start). */
+const LOADING_TEXT = /^loading\b[\s.…!]*$/iu;
+
+function isLoadingText(raw: string): boolean {
+  return LOADING_TEXT.test(raw.trim());
+}
+
+export const noLoadingTextUseSkeletonRule = createRule<RuleOptions, MessageIds>(
+  {
+    name: RULE_NAME,
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "Loading states must render a <Skeleton/>, not loading text or a spinner",
+      },
+      schema: [],
+      messages: {
+        useSkeleton:
+          "Render a <Skeleton/> shaped like the content, not loading text. Every isLoading/isPending branch shows skeletons — never a spinner or 'Loading…' text.",
+      },
+    },
+    defaultOptions: [],
+    create(context) {
+      const filename = context.filename;
+
+      if (isStoryFile(filename) || isTestFile(filename)) {
+        return {};
+      }
+
+      return {
+        JSXText(node: TSESTree.JSXText) {
+          if (isLoadingText(node.value)) {
+            context.report({ node, messageId: "useSkeleton" });
+          }
+        },
+        "JSXElement > Literal"(node: TSESTree.Literal) {
+          if (typeof node.value === "string" && isLoadingText(node.value)) {
+            context.report({ node, messageId: "useSkeleton" });
+          }
+        },
+        "JSXExpressionContainer > Literal"(node: TSESTree.Literal) {
+          if (typeof node.value === "string" && isLoadingText(node.value)) {
+            context.report({ node, messageId: "useSkeleton" });
+          }
+        },
+      };
+    },
+  }
+);

package/src/web-components.ts

@@ -34,6 +34,7 @@ export type ComponentName =
   | "select"
   | "badge"
   | "separator"
+  | "skeleton"
   | "table"
   // composition blocks (molecules) — the view chrome the model otherwise re-rolls
   | "app-shell"
@@ -52,6 +53,7 @@ export const COMPONENT_NAMES: readonly ComponentName[] = [
   "select",
   "badge",
   "separator",
+  "skeleton",
   "table",
   "app-shell",
   "page-header",
@@ -362,6 +364,23 @@ export function Separator({
     />
   );
 }
+`,
+  skeleton: `import { cn } from "@/lib/utils";
+
+// THE loading-state primitive. Render a Skeleton SHAPED like the content it
+// stands in for (a row, a card, a line of text) for every isLoading/isPending
+// branch — never a spinner, never "Loading…" text. Size it with className.
+export function Skeleton({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element {
+  return (
+    <div
+      className={cn("animate-pulse rounded-md bg-muted $DELTA", className)}
+      {...props}
+    />
+  );
+}
 `,
   table: `import { cn } from "@/lib/utils";
 

package/src/web-templates.ts

@@ -35,6 +35,9 @@ const PRETTIER_IGNORE = `node_modules
 dist
 src/components/ui
 src/lib
+src/mocks/db.ts
+src/mocks/browser.ts
+public/mockServiceWorker.js
 *.gen.ts
 `;
 
@@ -71,6 +74,7 @@ const REACT_PACKAGE_JSON = `{
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^4.3.4",
+    "msw": "^2.7.0",
     "tailwindcss": "^4.0.0",
     "tw-animate-css": "^1.0.0",
     "typescript": "^5.7.0",
@@ -336,6 +340,7 @@ import { createRoot } from "react-dom/client";
 import { RouterProvider, createRouter } from "@tanstack/react-router";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 
+import { worker } from "./mocks/browser";
 import { routeTree } from "./routeTree.gen";
 import "./index.css";
 
@@ -355,13 +360,23 @@ if (rootElement === null) {
   throw new Error("missing #root element");
 }
 
-createRoot(rootElement).render(
-  <StrictMode>
-    <QueryClientProvider client={queryClient}>
-      <RouterProvider router={router} />
-    </QueryClientProvider>
-  </StrictMode>
-);
+const root = createRoot(rootElement);
+
+// Start the MSW mock API BEFORE mounting — there is no real backend, so the app's
+// fetches must be intercepted from the very first render (in dev AND in the build).
+async function start(): Promise<void> {
+  await worker.start({ onUnhandledRequest: "bypass", quiet: true });
+
+  root.render(
+    <StrictMode>
+      <QueryClientProvider client={queryClient}>
+        <RouterProvider router={router} />
+      </QueryClientProvider>
+    </StrictMode>,
+  );
+}
+
+void start();
 `;
 
 // A STUB of TanStack Router's generated route tree, registering only the stock "/"
@@ -451,7 +466,7 @@ const REACT_GUIDANCE = [
   "        (NO `DealsTable` around <Table> — render <Table> with deal columns instead).",
   "      – <feature>.types.ts — the feature's interfaces/types (I-prefixed).",
   "      – <feature>.constants.ts — its `as const` registries/label maps/column specs.",
-  "      – (NO <feature>.hooks.ts query wrapper — the SDK's useCollection IS the data",
+  "      – (NO <feature>.hooks.ts query wrapper — the SDK's useResource IS the data",
   "        hook; add a hook file ONLY for genuine derived/computed state, never to fetch.)",
   "  • A component .tsx (index.tsx or components/<X>.tsx) = imports + the component,",
   "    nothing else. A constant (label map, column spec) → <feature>.constants.ts. A type",
@@ -515,9 +530,9 @@ const REACT_GUIDANCE = [
   "  • UI BUILDING BLOCKS — call `scaffold_ui` ONCE near the start to generate what",
   "    the app needs, themed to its vibe (minimal | warm | futuristic, from the",
   "    user's request). Two tiers, BOTH from @/components/ui: PRIMITIVES (button,",
-  "    card, input, label, textarea, select, badge, separator, table) AND COMPOSITION",
-  "    BLOCKS — app-shell (sidebar+nav layout, renders <Outlet/>), page-header, field",
-  "    (label+control+error), form-actions, toolbar, empty-state. COMPOSE these:",
+  "    card, input, label, textarea, select, badge, separator, skeleton, table) AND",
+  "    COMPOSITION BLOCKS — app-shell (sidebar+nav layout, renders <Outlet/>), page-",
+  "    header, field (label+control+error), form-actions, toolbar, empty-state. COMPOSE:",
   "    layout = app-shell; a list view = page-header + toolbar + table + empty-state;",
   "    a form = field × N + form-actions. NEVER hand-roll a component OR this view",
   "    chrome — it wastes time and breaks theme coherence. Write only feature wiring.",
@@ -525,14 +540,28 @@ const REACT_GUIDANCE = [
   "    => d.id} />`, where `dealColumns: readonly IColumn<IDeal>[]` is a feature CONSTANT",
   "    (in <feature>.constants.ts). Each column is `{ header, cell: (row) => …, className? }`.",
   "    Do NOT build a per-feature table component — pass columns to the one <Table>.",
-  "  • HARNESS SDK — USE IT, do NOT hand-roll the data layer (this is the biggest",
-  "    speed+quality lever). A tested generic toolkit is already in src/lib/:",
-  "      – createCollection(key, SEED) [from @/lib/collection] IS a feature's whole",
-  "        service: typed async CRUD + Result + latency. <feature>.service.ts (in the",
-  "        view folder) is ONE line: `export const items = createCollection('items', SEED_ITEMS)`.",
-  "      – useCollection(collection) [from @/lib/use-collection] IS the data hook:",
-  "        cached list, isLoading/error, and create/update/remove mutations WITH",
-  "        optimistic updates + rollback. Do NOT write a <feature>.hooks.ts query wrapper.",
+  "  • LOADING STATES ARE SKELETONS — every `isLoading`/`isPending` branch renders",
+  "    `<Skeleton/>` (from @/components/ui/skeleton) SHAPED like the content it stands",
+  "    in for: skeleton rows for a table, skeleton cards for a grid, a short skeleton",
+  '    line for a heading. NEVER render `"Loading…"`/`"Loading"` text and NEVER a',
+  "    spinner — the gate REJECTS loading text (no-loading-text-use-skeleton). Request",
+  "    `skeleton` from scaffold_ui. Pattern: `if (isLoading) return <Skeleton className=",
+  '    "h-9 w-full" />;` (size with Tailwind h-/w- classes; render several for a list).',
+  "  • DATA LAYER — a REAL mock API (MSW), do NOT hand-roll it (biggest speed+quality",
+  "    lever). The app does REAL `fetch()` to REST endpoints intercepted in-browser by",
+  "    Mock Service Worker — already wired and started in src/main.tsx. Two vendored",
+  "    generics (in src/lib + src/mocks; NEVER edit them — a type error involving them",
+  "    is a wrong CALL SITE) give you the whole loop in two lines per feature:",
+  "      – REGISTER the endpoint: in src/mocks/handlers.ts add ONE line —",
+  "        `...mockResource('/api/deals', SEED_DEALS)` [mockResource from @/mocks/db].",
+  "        It serves GET (list), GET /:id, POST, PATCH /:id, DELETE /:id over an in-",
+  "        memory faker-seeded store. handlers.ts is the ONLY mock file you edit.",
+  "      – CONSUME it: `const { items, isLoading, error, mutations } =",
+  "        useResource<IDeal>('/api/deals')` [useResource from @/lib/use-resource] IS",
+  "        the data hook — cached list, isLoading/error, and create/update/remove",
+  "        mutations WITH optimistic updates + rollback. Pass the SAME path string you",
+  "        registered. Do NOT write a <feature>.hooks.ts query wrapper or call fetch",
+  "        yourself — useResource is the only data access.",
   "      – useForm({ initial, validate, submit }) [from @/lib/use-form] IS form state:",
   "        values, per-field errors, async submit status. Do NOT hand-roll form state.",
   "      – SEED DATA — GENERATE with faker. NEVER hand-write literal arrays, and NEVER",
@@ -551,9 +580,11 @@ const REACT_GUIDANCE = [
   "          `    ['like','reply','follow']), from: faker.helpers.arrayElement(SEED_USERS),`",
   "          `    text: faker.lorem.sentence() }), { count: 15 });`",
   "        No `i`, no `arr[i % len]`, no undefined-guards, no parser — the type system +",
-  "        the factory return type ARE the validation. There is NO backend/localStorage,",
-  "        so NEVER write a runtime parser/validator (no parse<X>, no pObject, no `typeof`",
-  "        guards, no `as` casts).",
+  "        the factory return type ARE the validation. Define each SEED in the view's",
+  "        <feature>.constants.ts and pass it to mockResource. The mock API echoes your",
+  "        typed SEED and useResource<T> types the response, so the contract is proven",
+  "        end-to-end — NEVER write a runtime parser/validator (no parse<X>, no pObject,",
+  "        no `typeof` guards, no `as` casts) even though it now crosses a fetch.",
   "      – Result/ok/err [from @/lib/result] for any fallible op.",
   "      – objectKeys(x)/objectEntries(x) [from @/lib/object] for TYPED keys of an",
   "        `as const` object. NEVER write `Object.keys(x) as (keyof typeof x)[]` —",
@@ -569,10 +600,11 @@ const REACT_GUIDANCE = [
   "        `as const` and then index it `MAP[key as keyof typeof MAP]` — that `as` is",
   "        REJECTED. The map's KEY type, not a cast, is what makes the lookup type-check.",
   "    So a feature is mostly: src/views/<Feature>/{<feature>.types.ts + a `satisfies`-typed",
-  "    SEED const + one-line createCollection + index.tsx + components/} calling",
-  "    useCollection/useForm. Far fewer lines,",
-  "    fewer bugs. Only write a custom service/hook if the SDK genuinely can't express",
-  "    it. A QueryClientProvider is already wired in src/main.tsx.",
+  "    SEED const in <feature>.constants.ts + index.tsx + components/}, plus ONE",
+  "    `mockResource('/api/x', SEED)` line in src/mocks/handlers.ts, calling",
+  "    useResource/useForm. Far fewer lines, fewer bugs. Only write a custom hook if the",
+  "    SDK genuinely can't express it. QueryClientProvider + the MSW worker are already",
+  "    wired in src/main.tsx.",
   "  • Style with Tailwind classes via className using theme tokens",
   "    (bg-background, text-foreground, border-border), not raw colors.",
   "  • Need charts? `recharts` is installed — import from 'recharts'. Need drag-and-",
@@ -758,87 +790,67 @@ export function sortBy<T extends object>(
 }
 `;
 
-const SDK_COLLECTION_TS = `// createCollection — one tested generic that IS a domain's data layer: typed async
-// CRUD over an in-memory store, seeded from a typed const, with simulated latency +
-// a Result return. A domain's service becomes one line:
-//   export const items = createCollection("items", SEED_ITEMS)
+const SDK_API_TS = `// The typed fetch client — every data op goes over a REAL network call to a REST
+// endpoint, intercepted in-browser by MSW (see src/mocks/). Returns Result instead
+// of throwing, so callers handle failure explicitly. This is vendored + lint-exempt
+// (the boundary cast on the JSON body lives here, ONCE — your code never casts).
 import type { Result } from "@/lib/result";
 import { err, ok } from "@/lib/result";
 
-export interface IEntity {
-  readonly id: string;
-}
+async function request<T>(
+  method: string,
+  path: string,
+  body?: unknown
+): Promise<Result<T, string>> {
+  try {
+    const res = await fetch(path, {
+      method,
+      headers: body === undefined ? undefined : { "Content-Type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      return err(method + " " + path + " failed: " + String(res.status));
+    }
 
-export interface ICollection<T extends IEntity> {
-  readonly key: string;
-  list: () => Promise<Result<readonly T[], string>>;
-  get: (id: string) => Promise<Result<T, string>>;
-  create: (draft: Omit<T, "id">) => Promise<Result<T, string>>;
-  update: (id: string, patch: Partial<Omit<T, "id">>) => Promise<Result<T, string>>;
-  remove: (id: string) => Promise<Result<true, string>>;
-}
+    if (res.status === 204) {
+      return ok(undefined as T);
+    }
 
-const LATENCY_MS = 120;
+    return ok((await res.json()) as T);
+  } catch (error) {
+    return err(error instanceof Error ? error.message : "network error");
+  }
+}
 
-function delay(): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, LATENCY_MS));
+export function apiGet<T>(path: string): Promise<Result<T, string>> {
+  return request<T>("GET", path);
 }
 
-export function createCollection<T extends IEntity>(
-  key: string,
-  seed: readonly T[]
-): ICollection<T> {
-  const store = new Map<string, T>();
-  for (const entity of seed) {
-    store.set(entity.id, entity);
-  }
+export function apiPost<T>(path: string, body: unknown): Promise<Result<T, string>> {
+  return request<T>("POST", path, body);
+}
 
-  let counter = store.size;
-  const nextId = (): string => {
-    counter += 1;
-    return key + "-" + String(counter);
-  };
+export function apiPatch<T>(path: string, body: unknown): Promise<Result<T, string>> {
+  return request<T>("PATCH", path, body);
+}
 
-  return {
-    key,
-    async list() {
-      await delay();
-      return ok([...store.values()]);
-    },
-    async get(id) {
-      await delay();
-      const found = store.get(id);
-      return found === undefined ? err(key + " " + id + " not found") : ok(found);
-    },
-    async create(draft) {
-      await delay();
-      const entity = { ...draft, id: nextId() } as T;
-      store.set(entity.id, entity);
-      return ok(entity);
-    },
-    async update(id, patch) {
-      await delay();
-      const current = store.get(id);
-      if (current === undefined) {
-        return err(key + " " + id + " not found");
-      }
-      const updated = { ...current, ...patch };
-      store.set(id, updated);
-      return ok(updated);
-    },
-    async remove(id) {
-      await delay();
-      return store.delete(id) ? ok(true) : err(key + " " + id + " not found");
-    },
-  };
+export function apiDelete(path: string): Promise<Result<true, string>> {
+  return request<true>("DELETE", path);
 }
 `;
 
-const SDK_USE_COLLECTION_TS = `// useCollection — the TanStack Query layer for a collection, once: cached list,
+const SDK_USE_RESOURCE_TS = `// useResource — the TanStack Query layer for a REST resource, once: cached list,
 // loading/error state, and create/update/remove mutations with OPTIMISTIC updates
-// + rollback + invalidation built in. A domain's hooks file becomes one line.
+// + rollback + invalidation built in. Pass the resource's base path (the same one
+// you registered with mockResource in src/mocks/handlers.ts):
+//   const { items, isLoading, mutations } = useResource<IDeal>("/api/deals")
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import type { ICollection, IEntity } from "@/lib/collection";
+import { apiDelete, apiGet, apiPatch, apiPost } from "@/lib/api";
+
+export interface IEntity {
+  readonly id: string;
+}
 
 export interface IMutationApi<T extends IEntity> {
   create: (draft: Omit<T, "id">) => void;
@@ -847,7 +859,7 @@ export interface IMutationApi<T extends IEntity> {
   isPending: boolean;
 }
 
-export interface ICollectionApi<T extends IEntity> {
+export interface IResourceApi<T extends IEntity> {
   items: readonly T[];
   isLoading: boolean;
   error: string | undefined;
@@ -863,13 +875,13 @@ async function unwrap<T>(promise: Promise<{ ok: true; value: T } | { ok: false;
   return result.value;
 }
 
-export function useCollection<T extends IEntity>(collection: ICollection<T>): ICollectionApi<T> {
+export function useResource<T extends IEntity>(path: string): IResourceApi<T> {
   const client = useQueryClient();
-  const queryKey = [collection.key];
+  const queryKey = [path];
 
   const query = useQuery({
     queryKey,
-    queryFn: () => unwrap(collection.list()),
+    queryFn: () => unwrap(apiGet<readonly T[]>(path)),
   });
 
   const invalidate = (): void => {
@@ -877,13 +889,13 @@ export function useCollection<T extends IEntity>(collection: ICollection<T>): IC
   };
 
   const create = useMutation({
-    mutationFn: (draft: Omit<T, "id">) => unwrap(collection.create(draft)),
+    mutationFn: (draft: Omit<T, "id">) => unwrap(apiPost<T>(path, draft)),
     onSettled: invalidate,
   });
 
   const update = useMutation({
     mutationFn: (input: { readonly id: string; readonly patch: Partial<Omit<T, "id">> }) =>
-      unwrap(collection.update(input.id, input.patch)),
+      unwrap(apiPatch<T>(path + "/" + input.id, input.patch)),
     onMutate: async (input) => {
       await client.cancelQueries({ queryKey });
       const previous = client.getQueryData<readonly T[]>(queryKey);
@@ -904,7 +916,7 @@ export function useCollection<T extends IEntity>(collection: ICollection<T>): IC
   });
 
   const remove = useMutation({
-    mutationFn: (id: string) => unwrap(collection.remove(id)),
+    mutationFn: (id: string) => unwrap(apiDelete(path + "/" + id)),
     onSettled: invalidate,
   });
 
@@ -925,6 +937,79 @@ export function useCollection<T extends IEntity>(collection: ICollection<T>): IC
 }
 `;
 
+const SDK_MOCKS_DB_TS = `// mockResource — one tested generic that IS a REST endpoint set: in-memory CRUD
+// over a faker-seeded store, exposed as MSW handlers. Registering a resource is one
+// line in src/mocks/handlers.ts:
+//   ...mockResource("/api/deals", SEED_DEALS)
+// It serves GET (list), GET /:id, POST, PATCH /:id, DELETE /:id. Vendored + lint-
+// exempt (the boundary casts on request bodies live here, ONCE). NEVER edit this.
+import { http, HttpResponse, type RequestHandler } from "msw";
+import { faker } from "@faker-js/faker";
+
+export interface IEntity {
+  readonly id: string;
+}
+
+export function mockResource<T extends IEntity>(
+  path: string,
+  seed: readonly T[]
+): RequestHandler[] {
+  const store = new Map<string, T>();
+  for (const entity of seed) {
+    store.set(entity.id, entity);
+  }
+
+  return [
+    http.get(path, () => HttpResponse.json([...store.values()])),
+    http.get(path + "/:id", ({ params }) => {
+      const found = store.get(String(params.id));
+      return found === undefined
+        ? new HttpResponse(null, { status: 404 })
+        : HttpResponse.json(found);
+    }),
+    http.post(path, async ({ request }) => {
+      const draft = (await request.json()) as Omit<T, "id">;
+      const entity = { ...draft, id: faker.string.uuid() } as T;
+      store.set(entity.id, entity);
+      return HttpResponse.json(entity, { status: 201 });
+    }),
+    http.patch(path + "/:id", async ({ params, request }) => {
+      const current = store.get(String(params.id));
+      if (current === undefined) {
+        return new HttpResponse(null, { status: 404 });
+      }
+      const patch = (await request.json()) as Partial<Omit<T, "id">>;
+      const updated = { ...current, ...patch };
+      store.set(updated.id, updated);
+      return HttpResponse.json(updated);
+    }),
+    http.delete(path + "/:id", ({ params }) => {
+      const existed = store.delete(String(params.id));
+      return new HttpResponse(null, { status: existed ? 204 : 404 });
+    }),
+  ];
+}
+`;
+
+const SDK_MOCKS_BROWSER_TS = `// The MSW worker, wired from your handlers. Vendored — NEVER edit. Register your
+// resources in src/mocks/handlers.ts; main.tsx starts this before the app mounts.
+import { setupWorker } from "msw/browser";
+import { handlers } from "@/mocks/handlers";
+
+export const worker = setupWorker(...handlers);
+`;
+
+const MOCKS_HANDLERS_TS = `// YOUR mock API. Register each resource here with mockResource (one line per
+// resource), passing your faker-generated SEED. This is the ONLY mock file you
+// edit — src/mocks/db.ts and src/mocks/browser.ts are vendored.
+//   import { mockResource } from "@/mocks/db";
+//   import { SEED_DEALS } from "@/views/Deals/deals.constants";
+//   export const handlers: RequestHandler[] = [...mockResource("/api/deals", SEED_DEALS)];
+import { type RequestHandler } from "msw";
+
+export const handlers: RequestHandler[] = [];
+`;
+
 const SDK_USE_FORM_TS = `// useForm — declarative form state: values, per-field errors, async submit with
 // loading/success/error status. A form becomes initial + validate + submit; the
 // plumbing (touched, submitting, error/success handling) lives here, once.
@@ -995,9 +1080,12 @@ export const WEB_TEMPLATES: Record<WebFramework, IWebTemplate> = {
       "src/lib/result.ts": SDK_RESULT_TS,
       "src/lib/object.ts": SDK_OBJECT_TS,
       "src/lib/sort.ts": SDK_SORT_TS,
-      "src/lib/collection.ts": SDK_COLLECTION_TS,
-      "src/lib/use-collection.ts": SDK_USE_COLLECTION_TS,
+      "src/lib/api.ts": SDK_API_TS,
+      "src/lib/use-resource.ts": SDK_USE_RESOURCE_TS,
       "src/lib/use-form.ts": SDK_USE_FORM_TS,
+      "src/mocks/db.ts": SDK_MOCKS_DB_TS,
+      "src/mocks/browser.ts": SDK_MOCKS_BROWSER_TS,
+      "src/mocks/handlers.ts": MOCKS_HANDLERS_TS,
       "src/index.css": REACT_INDEX_CSS,
       "src/components/ui/button.tsx": BUTTON_TSX,
       "src/routes/__root.tsx": ROOT_ROUTE_TSX,
@@ -1005,7 +1093,14 @@ export const WEB_TEMPLATES: Record<WebFramework, IWebTemplate> = {
       "src/routeTree.gen.ts": ROUTE_TREE_GEN,
       "src/main.tsx": REACT_MAIN_TSX,
     },
-    eslintIgnore: ["src/components/ui/**", "src/lib/**", "**/*.gen.ts"],
+    eslintIgnore: [
+      "src/components/ui/**",
+      "src/lib/**",
+      "src/mocks/db.ts",
+      "src/mocks/browser.ts",
+      "public/mockServiceWorker.js",
+      "**/*.gen.ts",
+    ],
     guidance: REACT_GUIDANCE,
   },
   vanilla: {