@agjs/tsforge 0.2.4 → 0.2.6

package/package.json

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

package/src/detect-gate.ts

@@ -367,7 +367,43 @@ export async function installWebDeps(cwd: string): Promise<boolean> {
  *  TanStack Router's routeTree.gen.ts) exists before tsc; `vite build` is itself
  *  the bundler oracle — it resolves imports, compiles JSX/Tailwind, fails on
  *  anything broken. */
-export function buildWebGate(framework: WebFramework): IGate {
+/** The packs the WEB eslint config must load by default so the React component
+ *  architecture rules (component-folder-structure, component-file-purity,
+ *  no-jsx-computation, …) actually run on a generated app. The web scaffold's
+ *  stack is fixed (React + TanStack), so this set is deterministic; callers may
+ *  pass a detected/overridden set instead. Without this the web gate ran the
+ *  bundled config with ZERO packs and the whole architecture layer was inert. */
+export const WEB_PACKS: readonly string[] = [
+  "typescript-core",
+  "react",
+  "react-component-architecture",
+  "tanstack-query",
+];
+
+/** Build the `KEY=val ` shell prefix that hands packs (+ rule overrides) to a
+ *  bundled eslint config, which reads them from the environment at load time.
+ *  JSON.stringify emits no spaces, so this survives a later whitespace-collapse. */
+function packEnvPrefix(
+  packs?: readonly string[],
+  ruleOverrides?: Readonly<Record<string, "error" | "warn" | "off">>
+): string {
+  const envParts: string[] = [];
+
+  if (packs !== undefined && packs.length > 0) {
+    envParts.push(`TSFORGE_PACKS=${packs.join(",")}`);
+  }
+
+  if (ruleOverrides !== undefined && Object.keys(ruleOverrides).length > 0) {
+    envParts.push(`TSFORGE_RULE_OVERRIDES=${JSON.stringify(ruleOverrides)}`);
+  }
+
+  return envParts.length > 0 ? `${envParts.join(" ")} ` : "";
+}
+
+export function buildWebGate(
+  framework: WebFramework,
+  packs: readonly string[] = WEB_PACKS
+): IGate {
   const template = WEB_TEMPLATES[framework];
   const ignores = template.eslintIgnore
     .map((glob) => `--ignore-pattern "${glob}"`)
@@ -375,7 +411,7 @@ export function buildWebGate(framework: WebFramework): IGate {
   const build = `bun run build`;
   const tsc = `"${TSC_BIN}" --noEmit -p tsconfig.json`;
   const lint =
-    `"${ESLINT_BIN}" --no-config-lookup -c "${STRICT_WEB_CONFIG}" ${ignores} --format json .`.replace(
+    `${packEnvPrefix(packs)}bun "${ESLINT_BIN}" --no-config-lookup -c "${STRICT_WEB_CONFIG}" ${ignores} --format json .`.replace(
       /\s+/g,
       " "
     );
@@ -415,14 +451,17 @@ export function buildWebGate(framework: WebFramework): IGate {
  * ALONE — caught small and isolated, before any component is built — instead of
  * as a 20-error avalanche at the very end (the Linear-clone failure mode).
  */
-export function buildWebTypeGate(framework: WebFramework): IGate {
+export function buildWebTypeGate(
+  framework: WebFramework,
+  packs: readonly string[] = WEB_PACKS
+): IGate {
   const template = WEB_TEMPLATES[framework];
   const ignores = template.eslintIgnore
     .map((glob) => `--ignore-pattern "${glob}"`)
     .join(" ");
   const tsc = `"${TSC_BIN}" --noEmit -p tsconfig.json`;
   const lint =
-    `"${ESLINT_BIN}" --no-config-lookup -c "${STRICT_WEB_CONFIG}" ${ignores} --format json .`.replace(
+    `${packEnvPrefix(packs)}bun "${ESLINT_BIN}" --no-config-lookup -c "${STRICT_WEB_CONFIG}" ${ignores} --format json .`.replace(
       /\s+/g,
       " "
     );
@@ -447,13 +486,16 @@ export function buildWebTscCheck(): string {
  * unfixable rules (`any`/`as`/`!`) still need the model. Best-effort: exits ignored,
  * `;` so prettier runs even when eslint reports remaining (unfixable) errors.
  */
-export function buildWebFix(framework: WebFramework): string {
+export function buildWebFix(
+  framework: WebFramework,
+  packs: readonly string[] = WEB_PACKS
+): string {
   const ignores = WEB_TEMPLATES[framework].eslintIgnore
     .map((glob) => `--ignore-pattern "${glob}"`)
     .join(" ");
 
   const lintFix =
-    `"${ESLINT_BIN}" --no-config-lookup -c "${STRICT_WEB_CONFIG}" ${ignores} --fix .`.replace(
+    `${packEnvPrefix(packs)}bun "${ESLINT_BIN}" --no-config-lookup -c "${STRICT_WEB_CONFIG}" ${ignores} --fix .`.replace(
       /\s+/g,
       " "
     );
@@ -478,6 +520,47 @@ export function buildCoreFix(): string {
   return `${lintFix} ; ${format}`;
 }
 
+/**
+ * Auto-format ONE just-written file in place: `eslint --fix` (squashes the
+ * auto-fixable mechanical rules — padding-line, curly, prefer-template, quotes)
+ * then `prettier --write` (whitespace/quotes/width). Run at WRITE time (in the
+ * write guard) so the model never sees — nor hand-chases — formatting noise.
+ * Deferring all of this to the settle-time gate let the model self-run eslint
+ * mid-build, see the un-squashed mechanical lint, and spiral fixing blank lines
+ * and braces by hand to the turn cap. Best-effort + per-file (cheap): any failure
+ * is swallowed and the settle gate stays the authority.
+ */
+export async function formatFile(cwd: string, file: string): Promise<void> {
+  const abs = join(cwd, file);
+
+  try {
+    await Bun.spawn(
+      [
+        "bun",
+        ESLINT_BIN,
+        "--no-config-lookup",
+        "-c",
+        STRICT_CONFIG,
+        "--fix",
+        abs,
+      ],
+      { cwd, stdout: "ignore", stderr: "ignore" }
+    ).exited;
+  } catch {
+    // best-effort — the settle gate still fixes + validates
+  }
+
+  try {
+    await Bun.spawn(["bun", PRETTIER_BIN, "--write", abs], {
+      cwd,
+      stdout: "ignore",
+      stderr: "ignore",
+    }).exited;
+  } catch {
+    // best-effort
+  }
+}
+
 async function ensureFile(
   cwd: string,
   name: string,
@@ -650,24 +733,8 @@ function lintPart(
   packs?: readonly string[],
   ruleOverrides?: Readonly<Record<string, "error" | "warn" | "off">>
 ): IGate {
-  const envParts: string[] = [];
-
-  if (packs !== undefined && packs.length > 0) {
-    envParts.push(`TSFORGE_PACKS=${packs.join(",")}`);
-  }
-
-  if (
-    ruleOverrides !== undefined &&
-    typeof ruleOverrides === "object" &&
-    Object.keys(ruleOverrides).length > 0
-  ) {
-    envParts.push(`TSFORGE_RULE_OVERRIDES=${JSON.stringify(ruleOverrides)}`);
-  }
-
-  const envPrefix = envParts.length > 0 ? `${envParts.join(" ")} ` : "";
-
   return {
-    command: `${envPrefix}bun "${ESLINT_BIN}" --no-config-lookup -c "${STRICT_CONFIG}" --format json .`,
+    command: `${packEnvPrefix(packs, ruleOverrides)}bun "${ESLINT_BIN}" --no-config-lookup -c "${STRICT_CONFIG}" --format json .`,
     label: "strict TypeScript (tsforge)",
   };
 }

package/src/inference/request.ts

@@ -19,7 +19,21 @@ function interpolateEnv(
 }
 
 function style(cfg: IOpenAICompatibleConfig): ReasoningStyle {
-  return cfg.reasoning ?? "qwen";
+  if (cfg.reasoning !== undefined) {
+    return cfg.reasoning;
+  }
+
+  // Auto-detect DeepSeek when not explicitly configured, so its thinking-mode
+  // round-trip works out of the box: DeepSeek requires each prior assistant
+  // turn's `reasoning_content` replayed, and 400s otherwise ("The
+  // reasoning_content in the thinking mode must be passed back to the API").
+  // Without this, a DeepSeek model added with just { baseUrl, model } gets the
+  // `qwen` default, which strips reasoning_content on replay → that 400.
+  if (`${cfg.baseUrl} ${cfg.model}`.toLowerCase().includes("deepseek")) {
+    return "deepseek";
+  }
+
+  return "qwen";
 }
 
 /** Provider-specific reasoning/thinking fields for the request body. */

package/src/loop/prompt/prompt.ts

@@ -11,6 +11,7 @@ export const SYSTEM = [
   "Tools: `read` (inspect a file), `edit` (replace an exact, unique snippet), `create` (a new file), `run` (execute any shell command and see its output).",
   "Lead with action: write the implementation FIRST (one `create`/`edit`) — do NOT deliberate at length before writing any code.",
   "After every edit the harness AUTOMATICALLY runs the gate and gives you the result (the errors + fix guidance for the failing rules). You do NOT need to run the acceptance command yourself — read that result and fix exactly what it reports, then edit again. Keep going until it reports green; the harness ends the task at that point.",
+  "The harness also AUTO-FIXES mechanical formatting on every file you write — blank lines, braces, quotes, semicolons, import order, `prefer-template`. NEVER hand-fix or chase those, and do NOT run `tsc`/`eslint`/the gate yourself to look for them. Fix only what the gate explicitly hands back (`as`/`any`/`!`, `I`-prefix, real type errors), then stop.",
   "Test hypotheses by RUNNING them, never by reasoning them out. Unsure about an edge case, rounding, or ordering (`Math.floor(100/3)`, largest-remainder ties)? `run` a quick `bun -e '…console.log(…)'`, or write a throwaway `scratch/check.ts` importing your impl and `run` it. `scratch/` is yours — the gate ignores it.",
   "The gate is `tsc` strict + eslint with every rule an error, so write TypeScript that satisfies it: interfaces are `I`-prefixed; `===`; no `var`; never the non-null `!` — guard index access (`const x = arr[i]; if (x === undefined) {...}`); no `any` and no `as` — type every parameter (e.g. `.reduce((acc: number, r: number) => …, 0)`); explicit boolean conditions. When the gate flags errors in read-only files (tests/types), they come from your editable file being missing or wrong-shaped and vanish once it's correct — don't edit them.",
 ].join("\n");

package/src/loop/turn.ts

@@ -34,6 +34,7 @@ import {
 import { TsService, type ITsDiagnostic } from "../lsp";
 import type { McpRegistry } from "../mcp";
 import type { FileLinter, IFileLintProblem } from "../detect-gate";
+import { formatFile } from "../detect-gate";
 import {
   buildMetaRuleContext,
   runMetaRules,
@@ -322,6 +323,12 @@ async function writeGuard(
     });
   }
 
+  // Auto-format this file NOW (eslint --fix + prettier) — not at the settle
+  // gate. Otherwise the mechanical lint (blank lines, braces, quotes) sits
+  // unfixed between writes, and when the model self-runs the gate it sees the
+  // noise and hand-chases it to the turn cap. Best-effort; gate stays authority.
+  await formatFile(cwd, file);
+
   tsService.refresh(file);
 
   const typeErrors = tsService

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

@@ -1,6 +1,7 @@
 import type { TSESLint } from "@typescript-eslint/utils";
 
 import { dangerousHtmlRequiresSanitizeRule } from "./rules/dangerous-html-requires-sanitize";
+import { componentFilePurityRule } from "./rules/component-file-purity";
 import { componentFolderStructureRule } from "./rules/component-folder-structure";
 import { forwardrefDisplayNameRule } from "./rules/forwardref-display-name";
 import { indexMustReexportDefaultRule } from "./rules/index-must-reexport-default";
@@ -17,6 +18,7 @@ import { noStateInComponentBodyRule } from "./rules/no-state-in-component-body";
 import type { IRulePack } from "../rule-packs.types";
 
 const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "component-file-purity": componentFilePurityRule,
   "component-folder-structure": componentFolderStructureRule,
   "dangerous-html-requires-sanitize": dangerousHtmlRequiresSanitizeRule,
   "forwardref-display-name": forwardrefDisplayNameRule,
@@ -39,6 +41,7 @@ export const reactComponentArchitecturePack: IRulePack = {
     "Component structure, composition, and file organization for React",
   rules,
   rulesConfig: {
+    "component-file-purity": "error",
     "component-folder-structure": "error",
     "dangerous-html-requires-sanitize": "error",
     "forwardref-display-name": "error",

package/src/rule-packs/react-component-architecture/rules/component-file-purity.ts

@@ -0,0 +1,105 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import {
+  isComponentDeclaration,
+  isInShadcnUi,
+  isRouteFile,
+  isStoryFile,
+  isTestFile,
+  unwrapExport,
+} from "../utils";
+
+export const RULE_NAME = "component-file-purity";
+
+type MessageIds = "inlineType" | "inlineConstant" | "inlineHelper";
+
+/** Map an offending top-level declaration to the message that tells the model
+ *  where it belongs. Returns null for declarations that are allowed to sit
+ *  beside a component (none today — the component itself is filtered earlier). */
+function messageForDeclaration(node: TSESTree.Node): MessageIds | null {
+  switch (node.type) {
+    case AST_NODE_TYPES.TSInterfaceDeclaration:
+    case AST_NODE_TYPES.TSTypeAliasDeclaration:
+    case AST_NODE_TYPES.TSEnumDeclaration:
+      return "inlineType";
+    case AST_NODE_TYPES.VariableDeclaration:
+      return "inlineConstant";
+    case AST_NODE_TYPES.FunctionDeclaration:
+      return "inlineHelper";
+    default:
+      return null;
+  }
+}
+
+export const componentFilePurityRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "A component .tsx contains only imports and the component itself — types go to <feature>.types.ts, constants to <feature>.constants.ts, helpers to src/lib",
+    },
+    schema: [],
+    messages: {
+      inlineType:
+        "No inline types in a component file — move this to <feature>.types.ts (or src/shared/shared.types.ts if cross-feature) and import it.",
+      inlineConstant:
+        "No inline constants in a component file — move this to <feature>.constants.ts and import it. A component file holds only imports and the component.",
+      inlineHelper:
+        "No inline helper functions in a component file — move pure helpers (formatters, etc.) to src/lib and import them. A component file holds only imports and the component.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    const filename = context.filename;
+
+    if (!filename.endsWith(".tsx")) {
+      return {};
+    }
+
+    // Primitives (cva variant consts) and route shells (`const Route = …`)
+    // legitimately carry non-component module declarations. Tests/stories too.
+    if (
+      isInShadcnUi(filename) ||
+      isRouteFile(filename) ||
+      isStoryFile(filename) ||
+      isTestFile(filename)
+    ) {
+      return {};
+    }
+
+    return {
+      Program(program) {
+        const unwrapped = program.body.map((s) => ({
+          stmt: s,
+          decl: unwrapExport(s),
+        }));
+
+        // Only enforce purity on files that actually define a component; a .tsx
+        // with no component isn't a "component file" this rule governs.
+        const hasComponent = unwrapped.some((u) =>
+          isComponentDeclaration(u.decl)
+        );
+
+        if (!hasComponent) {
+          return;
+        }
+
+        for (const { decl } of unwrapped) {
+          if (isComponentDeclaration(decl)) {
+            continue;
+          }
+
+          const messageId = messageForDeclaration(decl);
+
+          if (messageId === null) {
+            continue;
+          }
+
+          context.report({ node: decl, messageId });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/react-component-architecture/rules/component-folder-structure.ts

@@ -1,44 +1,34 @@
-import { existsSync } from "fs";
-import { dirname, join } from "path";
 import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
 
 import { createRule } from "../../create-rule";
-import { getComponentName, isComponentFile, isInShadcnUi } from "../utils";
+import {
+  getComponentName,
+  isComponentFile,
+  isInShadcnUi,
+  isRouteFile,
+} from "../utils";
 
 export const RULE_NAME = "component-folder-structure";
 
 export interface ComponentFolderStructureOptions {
-  readonly requiredSiblings?: readonly string[];
+  /** Substrings; a component file whose path matches any is left alone. */
   readonly ignorePaths?: readonly string[];
 }
 
 type RuleOptions = [ComponentFolderStructureOptions];
-type MessageIds = "missingSiblings";
-
-const DEFAULT_SIBLINGS = [
-  "<Name>.hooks.ts",
-  "<Name>.types.ts",
-  "<Name>.stories.tsx",
-  "<Name>.test.ts",
-  "index.ts",
-];
-
-const DEFAULT_IGNORE_PATHS = [
-  "src/components/ui/",
-  "tests/",
-  "e2e/",
-  ".storybook/",
-  "node_modules",
-];
+type MessageIds = "wrongLocation";
+
+const DEFAULT_IGNORE_PATHS = ["tests/", "e2e/", ".storybook/", "node_modules"];
+
+/** A feature component lives at src/views/<Feature>/components/<X>.tsx (nesting
+ *  under components/ is allowed). The view root is src/views/<Feature>/index.tsx
+ *  (lowercase ⇒ not a PascalCase component file, so it never reaches here). */
+const FEATURE_COMPONENT = /(^|\/)src\/views\/[^/]+\/components\//;
 
 const optionSchema: JSONSchema4 = {
   type: "object",
   additionalProperties: false,
   properties: {
-    requiredSiblings: {
-      type: "array",
-      items: { type: "string" },
-    },
     ignorePaths: {
       type: "array",
       items: { type: "string" },
@@ -53,20 +43,15 @@ export const componentFolderStructureRule = createRule<RuleOptions, MessageIds>(
       type: "problem",
       docs: {
         description:
-          "Enforce required sibling files in component folders (hooks, types, stories, test, index)",
+          "A component .tsx must live in src/views/<Feature>/components/ (feature component), src/components/ui/ (shared primitive), or be the view root src/views/<Feature>/index.tsx",
       },
       schema: [optionSchema],
       messages: {
-        missingSiblings:
-          "Component '{{name}}' is missing required siblings: {{missing}}",
+        wrongLocation:
+          "Component '{{name}}' is in the wrong place. Put it in src/views/<Feature>/components/{{name}}.tsx (a feature component), src/components/ui/ (a shared primitive), or make it the view root src/views/<Feature>/index.tsx — do NOT scatter components under {{dir}}.",
       },
     },
-    defaultOptions: [
-      {
-        requiredSiblings: DEFAULT_SIBLINGS,
-        ignorePaths: DEFAULT_IGNORE_PATHS,
-      },
-    ],
+    defaultOptions: [{ ignorePaths: DEFAULT_IGNORE_PATHS }],
     create(context, [options]) {
       const filename = context.filename;
 
@@ -80,42 +65,32 @@ export const componentFolderStructureRule = createRule<RuleOptions, MessageIds>(
         return {};
       }
 
-      if (isInShadcnUi(filename)) {
+      // Allowed homes: shared primitives, generated route shells, feature
+      // components. Anything else is a scattered/mis-placed component.
+      if (
+        isInShadcnUi(filename) ||
+        isRouteFile(filename) ||
+        FEATURE_COMPONENT.test(filename)
+      ) {
         return {};
       }
 
       const componentName = getComponentName(filename);
 
-      if (!componentName) {
+      if (componentName === null) {
         return {};
       }
 
+      const slash = filename.lastIndexOf("/");
+      const dir = slash === -1 ? "." : filename.slice(0, slash);
+
       return {
         "Program:exit"(node) {
-          const dir = dirname(filename);
-          const requiredSiblings = options.requiredSiblings ?? DEFAULT_SIBLINGS;
-
-          const missing: string[] = [];
-
-          for (const sibling of requiredSiblings) {
-            const siblingPath = sibling.replace("<Name>", componentName);
-            const fullPath = join(dir, siblingPath);
-
-            if (!existsSync(fullPath)) {
-              missing.push(siblingPath);
-            }
-          }
-
-          if (missing.length > 0) {
-            context.report({
-              node,
-              messageId: "missingSiblings",
-              data: {
-                name: componentName,
-                missing: missing.join(", "),
-              },
-            });
-          }
+          context.report({
+            node,
+            messageId: "wrongLocation",
+            data: { name: componentName, dir },
+          });
         },
       };
     },

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

@@ -82,6 +82,68 @@ export function isInShadcnUi(filename: string): boolean {
   return filename.includes("/components/ui/");
 }
 
+/**
+ * Detect if a path is a TanStack route file (generated/hand-wired shells under
+ * src/routes/). These legitimately hold a non-component `const Route =
+ * createFileRoute(...)` and are exempt from the component-purity/location rules.
+ */
+export function isRouteFile(filename: string): boolean {
+  return /(^|\/)src\/routes\//.test(filename);
+}
+
+/** A name is a component name when it is PascalCase (starts with an uppercase). */
+export function isComponentName(name: string): boolean {
+  return /^[A-Z]/.test(name);
+}
+
+/** True when a node is a function expression/arrow (a component's init shape). */
+function isFunctionInit(node: TSESTree.Expression | null | undefined): boolean {
+  return (
+    node?.type === AST_NODE_TYPES.ArrowFunctionExpression ||
+    node?.type === AST_NODE_TYPES.FunctionExpression
+  );
+}
+
+/**
+ * Given a top-level statement (already unwrapped from any `export`), report
+ * whether it DECLARES a React component — a PascalCase `function`, or a
+ * `const PascalCase = (…) => …` whose init is a function. A `const Route =
+ * createFileRoute(...)(...)` is NOT a component (its init is a call), so route
+ * files don't trip this.
+ */
+export function isComponentDeclaration(node: TSESTree.Node): boolean {
+  if (node.type === AST_NODE_TYPES.FunctionDeclaration && node.id !== null) {
+    return isComponentName(node.id.name);
+  }
+
+  if (node.type === AST_NODE_TYPES.VariableDeclaration) {
+    return node.declarations.some(
+      (d) =>
+        d.id.type === AST_NODE_TYPES.Identifier &&
+        isComponentName(d.id.name) &&
+        isFunctionInit(d.init)
+    );
+  }
+
+  return false;
+}
+
+/** Unwrap a top-level statement from its `export`/`export default` wrapper, so
+ *  callers classify the underlying declaration uniformly. */
+export function unwrapExport(
+  statement: TSESTree.ProgramStatement
+): TSESTree.Node {
+  if (
+    (statement.type === AST_NODE_TYPES.ExportNamedDeclaration ||
+      statement.type === AST_NODE_TYPES.ExportDefaultDeclaration) &&
+    statement.declaration !== null
+  ) {
+    return statement.declaration;
+  }
+
+  return statement;
+}
+
 /**
  * Extract component name from filename (e.g., Button.tsx → Button)
  */

package/src/rule-packs/rule-metadata.ts

@@ -18,6 +18,7 @@ const RULE_ENTRIES: Readonly<Record<string, IRuleCatalogEntry>> = {
     falsePositiveRisk: "medium",
   },
   "component-folder-structure": { tier: "architecture", tags: ["react"] },
+  "component-file-purity": { tier: "architecture", tags: ["react"] },
   "no-state-in-component-body": { tier: "architecture", tags: ["react"] },
   "no-inline-jsx-functions": { tier: "architecture", tags: ["react"] },
   "no-anonymous-useEffect": {

package/src/web-components.ts

@@ -365,64 +365,66 @@ export function Separator({
 `,
   table: `import { cn } from "@/lib/utils";
 
-export function Table({
+// A column-driven table: pass your typed rows + a column spec and it renders.
+// This is the table — there is NO per-feature wrapper (no DealsTable/UsersTable).
+// Define columns as a feature constant (e.g. dashboard.constants.ts) and render
+// <Table columns={dealColumns} data={deals} rowKey={(d) => d.id} />.
+export interface IColumn<T> {
+  readonly header: string;
+  readonly cell: (row: T) => React.ReactNode;
+  readonly className?: string;
+}
+
+export function Table<T>({
+  columns,
+  data,
+  rowKey,
   className,
-  ...props
-}: React.TableHTMLAttributes<HTMLTableElement>): React.JSX.Element {
+}: {
+  readonly columns: readonly IColumn<T>[];
+  readonly data: readonly T[];
+  readonly rowKey: (row: T) => string;
+  readonly className?: string;
+}): React.JSX.Element {
   return (
     <div className="relative w-full overflow-auto $DELTA">
-      <table className={cn("w-full caption-bottom text-sm", className)} {...props} />
+      <table className={cn("w-full caption-bottom text-sm", className)}>
+        <thead className="[&_tr]:border-b">
+          <tr className="border-b transition-colors hover:bg-muted/50">
+            {columns.map((col) => (
+              <th
+                key={col.header}
+                className={cn(
+                  "h-10 px-2 text-left align-middle font-medium text-muted-foreground",
+                  col.className
+                )}
+              >
+                {col.header}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody className="[&_tr:last-child]:border-0">
+          {data.map((row) => (
+            <tr
+              key={rowKey(row)}
+              className="border-b transition-colors hover:bg-muted/50"
+            >
+              {columns.map((col) => (
+                <td
+                  key={col.header}
+                  className={cn("p-2 align-middle", col.className)}
+                >
+                  {col.cell(row)}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
     </div>
   );
 }
-
-export function TableHeader({
-  className,
-  ...props
-}: React.HTMLAttributes<HTMLTableSectionElement>): React.JSX.Element {
-  return <thead className={cn("[&_tr]:border-b", className)} {...props} />;
-}
-
-export function TableBody({
-  className,
-  ...props
-}: React.HTMLAttributes<HTMLTableSectionElement>): React.JSX.Element {
-  return <tbody className={cn("[&_tr:last-child]:border-0", className)} {...props} />;
-}
-
-export function TableRow({
-  className,
-  ...props
-}: React.HTMLAttributes<HTMLTableRowElement>): React.JSX.Element {
-  return (
-    <tr
-      className={cn("border-b transition-colors hover:bg-muted/50", className)}
-      {...props}
-    />
-  );
-}
-
-export function TableHead({
-  className,
-  ...props
-}: React.ThHTMLAttributes<HTMLTableCellElement>): React.JSX.Element {
-  return (
-    <th
-      className={cn(
-        "h-10 px-2 text-left align-middle font-medium text-muted-foreground",
-        className
-      )}
-      {...props}
-    />
-  );
-}
-
-export function TableCell({
-  className,
-  ...props
-}: React.TdHTMLAttributes<HTMLTableCellElement>): React.JSX.Element {
-  return <td className={cn("p-2 align-middle", className)} {...props} />;
-}
 `,
   // ─── composition blocks (molecules) ────────────────────────────────────────
   "app-shell": `import { Link, Outlet, useLocation } from "@tanstack/react-router";

package/src/web-templates.ts

@@ -437,20 +437,29 @@ const REACT_GUIDANCE = [
   "TanStack (Router + Query) — ALREADY scaffolded and its dependencies INSTALLED.",
   "Build the app by adding/editing files under src/. Do NOT touch vite.config.ts,",
   "index.html, tsconfig.json, components.json, or the build setup.",
-  "FILE LAYOUT — boringstack, ONE thing per file (judged on this, not just",
-  "compiling). NEVER put more than one component in a file, and NEVER inline types",
-  "or constants in a component file:",
-  "  • Organize by DOMAIN: each feature/area of the app is its own folder under",
-  "    src/, named for the domain it holds. Inside a domain folder <d>/ put:",
-  "      – <d>.types.ts — that domain's interfaces/types (I-prefixed)",
-  "      – <d>.constants.ts — its `as const` registries/config",
-  "      – one component per .tsx file (PascalCase, named for the component)",
-  "      – (NO <d>.hooks.ts query wrapper — the SDK's useCollection IS the data hook;",
-  "        add a hook file ONLY for genuine derived/computed state, never to fetch)",
-  "      – index.ts — a barrel re-exporting the folder's public surface",
-  "  • Types ALWAYS live in a `.types.ts`, constants in a `.constants.ts` — never",
-  "    inline, and never one mega src/types.ts for the whole app. Types shared",
-  "    across domains → src/shared/shared.types.ts.",
+  "FILE LAYOUT — VIEWS. ONE thing per file, and the GATE ENFORCES IT (lint errors,",
+  "not style): a component .tsx holds ONLY imports + the component — NO inline types,",
+  "constants, or helper functions. Every screen/feature is a VIEW:",
+  "  • src/views/<Feature>/ — one folder per feature (PascalCase, e.g. Dashboard). Put:",
+  "      – index.tsx — THE VIEW: the composition root. It imports its pieces from",
+  "        ./components and the shared primitives in @/components/ui and assembles the",
+  "        screen. This is the only component allowed at the feature root.",
+  "      – components/<X>.tsx — the feature's own components, ONE component per file",
+  "        (PascalCase). Create one ONLY when a piece needs local state, is reused in",
+  "        the view, or is big enough to stand alone — otherwise compose primitives",
+  "        directly in index.tsx. Do NOT wrap a single primitive in a feature name",
+  "        (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",
+  "        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",
+  "    → <feature>.types.ts (shared across features → src/shared/shared.types.ts). A pure",
+  "    helper (formatCurrency, timeAgo) → src/lib/<name>.ts. Putting any of these atop a",
+  "    component is a GATE ERROR (component-file-purity / component-folder-structure).",
+  "  • Shared, reusable UI primitives live in @/components/ui (scaffold_ui) — they are",
+  "    feature-agnostic. Anything feature-specific is a view component, never a primitive.",
   "  • NO RUNTIME VALIDATION / PARSING — there is NO backend, network, or uploaded",
   "    data here; EVERY value originates from your own typed code + seed, so TypeScript",
   "    has already proven its shape. The TYPE SYSTEM is the only validation. NEVER create",
@@ -467,8 +476,9 @@ const REACT_GUIDANCE = [
   "    create/edit pages (e.g. /deals/create). It writes every src/routes/*.tsx stub AND",
   "    the real home at src/routes/index.tsx and regenerates the route tree, so the whole",
   "    app navigates and every <Link to>/navigate target type-checks from that point on.",
-  "    NEVER hand-write or hand-edit route files or createFileRoute paths. THEN fill each",
-  "    route's placeholder component with the real UI, ONE feature at a time.",
+  "    NEVER hand-write or hand-edit route files or createFileRoute paths. A route file is",
+  "    a THIN SHELL: it renders its view (e.g. `import { Dashboard } from",
+  "    '@/views/Dashboard'`), no UI logic of its own. Build the views ONE feature at a time.",
   "      – shadcn/ui primitives stay in @/components/ui (Button exists; add more there",
   "        following cva + cn() + tokens).",
   "  • src/routeTree.gen.ts is AUTO-GENERATED by the Vite build from your route",
@@ -510,15 +520,19 @@ const REACT_GUIDANCE = [
   "    (label+control+error), form-actions, toolbar, empty-state. COMPOSE these:",
   "    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 domain wiring.",
+  "    chrome — it wastes time and breaks theme coherence. Write only feature wiring.",
+  "    `table` is COLUMN-DRIVEN: `<Table columns={dealColumns} data={deals} rowKey={(d)",
+  "    => 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 domain's whole",
-  "        service: typed async CRUD + Result + latency. <d>.service.ts is ONE line:",
-  "        `export const items = createCollection('items', SEED_ITEMS)`.",
+  "      – 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 <d>.hooks.ts query wrapper.",
+  "        optimistic updates + rollback. Do NOT write a <feature>.hooks.ts query wrapper.",
   "      – 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",
@@ -554,8 +568,9 @@ const REACT_GUIDANCE = [
   "        `KIND_LABEL[activity.kind]` needs NO cast. NEVER write the map as a bare",
   "        `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 domain is mostly: <d>.types.ts + a `satisfies`-typed SEED const + one-line",
-  "    createCollection + components that call useCollection/useForm. Far fewer lines,",
+  "    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.",
   "  • Style with Tailwind classes via className using theme tokens",
@@ -563,7 +578,7 @@ const REACT_GUIDANCE = [
   "  • Need charts? `recharts` is installed — import from 'recharts'. Need drag-and-",
   "    drop? `@dnd-kit/core` + `@dnd-kit/sortable` are installed. Do NOT add other",
   "    deps (only these + the scaffold's are installed; the build can't fetch more).",
-  "Imports use the @/ alias (e.g. @/<domain>/<domain>.types, @/components/ui/button).",
+  "Imports use the @/ alias (e.g. @/views/<Feature>/<feature>.types, @/components/ui/button).",
   "Do NOT write a checks.json or any browser interaction test. The gate already",
   "builds the app with Vite and renders it in a real browser, FAILING on any",
   "runtime/console error — that IS the acceptance. Spend your effort on a working,",

package/strict.web.eslint.config.mjs

@@ -145,6 +145,7 @@ export default tseslint.config(
       "boringstack/one-component-per-file": "error",
       "react/jsx-key": "error",
       "react/no-array-index-key": "error",
+      "react/button-has-type": "error",
       "react-hooks/rules-of-hooks": "error",
       "react-hooks/exhaustive-deps": "warn",
       "prefer-const": "error",
@@ -207,7 +208,6 @@ export default tseslint.config(
             "jsx-a11y/click-events-have-key-events": "warn",
             "jsx-a11y/no-static-element-interactions": "warn",
             "jsx-a11y/label-has-associated-control": "error",
-            "jsx-a11y/button-has-type": "error",
             "jsx-a11y/no-noninteractive-tabindex": "error",
           },
         },