@metaobjectsdev/codegen-ts-tanstack 0.24.3 → 0.24.5

package/README.md

@@ -57,6 +57,15 @@ the entity module from wherever `entityFile()` is routed (relative when same tar
 the entity-module target's `importBase` when not); the grid-hook imports its sibling
 `<Entity>.columns` from within its own target.
 
+### The generator is yours
+
+Each of `tanstackQuery()`, `tanstackGrid()` and `tanstackGridHook()` has a reference template:
+`meta eject hooks` / `grid` / `grid-hook` copies one into `codegen/generators/` for you to own. Each
+renderer (`renderHooksFile`, `renderColumnsFile`, `renderGridHookFile`) is exported, so retargeting
+is usually a wrapper, not a rewrite — compose it and change the one step your framework needs.
+Inside the ejected file's existing `if (!ctx.renderContext) throw …` guard, change only the
+`content:` line, e.g. `content: '"use client";\n' + renderHooksFile(entity, ctx.renderContext)`.
+
 ## Pairs with
 
 - Runtime: [`@metaobjectsdev/tanstack`](../../../../client/web/packages/tanstack) — generated hooks and columns import from here.

package/dist/index.d.ts

@@ -1,4 +1,10 @@
 export { tanstackQuery, type TanstackQueryOpts } from "./tanstack-query.js";
 export { tanstackGrid, type TanstackGridOpts } from "./tanstack-grid.js";
 export { tanstackGridHook, type TanstackGridHookOpts } from "./tanstack-grid-hook.js";
+export { renderHooksFile } from "./templates/hooks-file.js";
+export { renderColumnsFile } from "./templates/columns-file.js";
+export { renderGridHookFile } from "./templates/grid-hook-file.js";
+export { hasDataGridLayout, warnMissingDataGridLayout } from "./data-grid-gate.js";
+export { resolveReferenceRoot, readReferenceTemplate, REFERENCE_GENERATOR_NAMES } from "./reference-templates.js";
+export type { ReferenceGeneratorName } from "./reference-templates.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAItF,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAMnE,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAInF,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAGlH,YAAY,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -2,4 +2,17 @@
 export { tanstackQuery } from "./tanstack-query.js";
 export { tanstackGrid } from "./tanstack-grid.js";
 export { tanstackGridHook } from "./tanstack-grid-hook.js";
+// FR-040 §4.2(b) — public so an owned generator composes the engine rather than
+// forking it. Signatures are stable API: (entity, ctx) => string.
+export { renderHooksFile } from "./templates/hooks-file.js";
+export { renderColumnsFile } from "./templates/columns-file.js";
+export { renderGridHookFile } from "./templates/grid-hook-file.js";
+// FR-040 §4.2(b) — the grid/grid-hook data-grid opt-in gate is a STEP in the pipeline
+// those two owned templates compose, not an internal detail either may fork. Public so
+// `grid.ts` and `grid-hook.ts` import one shared implementation instead of each
+// carrying its own copy.
+export { hasDataGridLayout, warnMissingDataGridLayout } from "./data-grid-gate.js";
+// FR-040 §4.1 — the copyable reference generators this package ships in
+// `src/reference/`, and the reader `meta init`/`meta eject` use to read them.
+export { resolveReferenceRoot, readReferenceTemplate, REFERENCE_GENERATOR_NAMES } from "./reference-templates.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,OAAO,EAAE,aAAa,EAA0B,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAyB,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAA6B,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,OAAO,EAAE,aAAa,EAA0B,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAyB,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAA6B,MAAM,yBAAyB,CAAC;AAEtF,gFAAgF;AAChF,kEAAkE;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAEnE,sFAAsF;AACtF,uFAAuF;AACvF,gFAAgF;AAChF,yBAAyB;AACzB,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAEnF,wEAAwE;AACxE,8EAA8E;AAC9E,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/reference-templates.d.ts

@@ -0,0 +1,5 @@
+export declare const REFERENCE_GENERATOR_NAMES: readonly ["hooks", "grid", "grid-hook"];
+export type ReferenceGeneratorName = (typeof REFERENCE_GENERATOR_NAMES)[number];
+export declare function resolveReferenceRoot(): string;
+export declare function readReferenceTemplate(name: ReferenceGeneratorName): string;
+//# sourceMappingURL=reference-templates.d.ts.map

package/dist/reference-templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-templates.d.ts","sourceRoot":"","sources":["../src/reference-templates.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,yBAAyB,yCAA0C,CAAC;AACjF,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAIhF,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAE1E"}

package/dist/reference-templates.js

@@ -0,0 +1,12 @@
+// FR-040 §4.1 — this package hosts its own copyable reference generators in
+// `src/reference/`, read through the shared factory so the resolver is not duplicated.
+import { makeReferenceReader } from "@metaobjectsdev/codegen-ts";
+export const REFERENCE_GENERATOR_NAMES = ["hooks", "grid", "grid-hook"];
+const reader = makeReferenceReader(import.meta.url, REFERENCE_GENERATOR_NAMES);
+export function resolveReferenceRoot() {
+    return reader.resolveReferenceRoot();
+}
+export function readReferenceTemplate(name) {
+    return reader.readReferenceTemplate(name);
+}
+//# sourceMappingURL=reference-templates.js.map

package/dist/reference-templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-templates.js","sourceRoot":"","sources":["../src/reference-templates.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,uFAAuF;AACvF,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAU,CAAC;AAGjF,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,yBAAyB,CAAC,CAAC;AAE/E,MAAM,UAAU,oBAAoB;IAClC,OAAO,MAAM,CAAC,oBAAoB,EAAE,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,IAA4B;IAChE,OAAO,MAAM,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC"}

package/dist/tanstack-grid-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tanstack-grid-hook.d.ts","sourceRoot":"","sources":["../src/tanstack-grid-hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAA6B,KAAK,gBAAgB,EAAyJ,MAAM,4BAA4B,CAAC;AAIrP,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAuDxB,gBAAgB,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC"}
+{"version":3,"file":"tanstack-grid-hook.d.ts","sourceRoot":"","sources":["../src/tanstack-grid-hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAA6B,KAAK,gBAAgB,EAExD,MAAM,4BAA4B,CAAC;AAIpC,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EA0DxB,gBAAgB,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC"}

package/dist/tanstack-grid-hook.js

@@ -1,4 +1,4 @@
-import { perEntity, formatTs, entityOutputPath, entityMetaFileName, renderEntityMetaFile, servesReadApi, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID } from "@metaobjectsdev/codegen-ts";
+import { perEntity, formatTs, entityOutputPath, entityMetaFileName, renderEntityMetaFile, servesReadApi, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID, withClientDirective, } from "@metaobjectsdev/codegen-ts";
 import { hasDataGridLayout, warnMissingDataGridLayout } from "./data-grid-gate.js";
 import { renderGridHookFile } from "./templates/grid-hook-file.js";
 /**
@@ -42,7 +42,7 @@ export const tanstackGridHook = function tanstackGridHook(opts) {
                 content: await formatTs(renderEntityMetaFile(entity, ctx.renderContext.apiPrefix)),
             }, {
                 path: entityOutputPath(ctx.renderContext.outputLayout, entity.package, `${entity.name}.grid.ts`),
-                content: await formatTs(renderGridHookFile(entity, ctx.renderContext)),
+                content: withClientDirective(await formatTs(renderGridHookFile(entity, ctx.renderContext)), ctx.renderContext.clientDirective),
             }];
     });
     const generator = {

package/dist/tanstack-grid-hook.js.map

@@ -1 +1 @@
-{"version":3,"file":"tanstack-grid-hook.js","sourceRoot":"","sources":["../src/tanstack-grid-hook.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAyC,QAAQ,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,aAAa,EAAE,YAAY,EAAE,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACrP,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAOnE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,gBAAgB,CAAC,IAA2B;IACnF,MAAM,UAAU,GAAG,IAAI,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAChD,gFAAgF;IAChF,iFAAiF;IACjF,gFAAgF;IAChF,0BAA0B;IAC1B,EAAE;IACF,sFAAsF;IACtF,wFAAwF;IACxF,yFAAyF;IACzF,uFAAuF;IACvF,oFAAoF;IACpF,mFAAmF;IACnF,sFAAsF;IACtF,yDAAyD;IACzD,MAAM,gBAAgB,GAAG,CAAC,CAAa,EAAW,EAAE,CAClD,aAAa,CAAC,CAAC,CAAC;QAChB,2FAA2F;WACxF,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,KAAK,KAAK;WAC5C,UAAU,CAAC,CAAC,CAAC;WACb,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,KAAK,IAAI,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,EAAE,MAAkB,EAAE,GAAG,EAAE,EAAE;QACvD,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;QACxF,CAAC;QACD,0EAA0E;QAC1E,8EAA8E;QAC9E,+EAA+E;QAC/E,+EAA+E;QAC/E,2BAA2B;QAC3B,OAAO,CAAC;gBACN,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,aAAa,CAAC,YAAY,EAAE,MAAM,CAAC,OAAO,EACnE,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAClC,OAAO,EAAE,MAAM,QAAQ,CAAC,oBAAoB,CAAC,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;aACnF,EAAE;gBACD,IAAI,EAAE,gBAAgB,CACpB,GAAG,CAAC,aAAa,CAAC,YAAY,EAC9B,MAAM,CAAC,OAAO,EACd,GAAG,MAAM,CAAC,IAAI,UAAU,CACzB;gBACD,OAAO,EAAE,MAAM,QAAQ,CAAC,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC;aACvE,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,MAAM,SAAS,GAAc;QAC3B,IAAI,EAAE,oBAAoB;QAC1B,MAAM,EAAE,CAAC,CAAa,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC;QACtE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACtB,yBAAyB,CAAC,GAAG,EAAE,gBAAgB,EAAE,kBAAkB,CAAC,CAAC;YACrE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;KACF,CAAC;IACF,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACjC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAkD,CAAC"}
+{"version":3,"file":"tanstack-grid-hook.js","sourceRoot":"","sources":["../src/tanstack-grid-hook.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAyC,QAAQ,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,aAAa,EAAE,YAAY,EAAE,0BAA0B,EAAE,sBAAsB,EAC9M,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAOnE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,gBAAgB,CAAC,IAA2B;IACnF,MAAM,UAAU,GAAG,IAAI,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAChD,gFAAgF;IAChF,iFAAiF;IACjF,gFAAgF;IAChF,0BAA0B;IAC1B,EAAE;IACF,sFAAsF;IACtF,wFAAwF;IACxF,yFAAyF;IACzF,uFAAuF;IACvF,oFAAoF;IACpF,mFAAmF;IACnF,sFAAsF;IACtF,yDAAyD;IACzD,MAAM,gBAAgB,GAAG,CAAC,CAAa,EAAW,EAAE,CAClD,aAAa,CAAC,CAAC,CAAC;QAChB,2FAA2F;WACxF,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,KAAK,KAAK;WAC5C,UAAU,CAAC,CAAC,CAAC;WACb,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,KAAK,IAAI,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,EAAE,MAAkB,EAAE,GAAG,EAAE,EAAE;QACvD,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;QACxF,CAAC;QACD,0EAA0E;QAC1E,8EAA8E;QAC9E,+EAA+E;QAC/E,+EAA+E;QAC/E,2BAA2B;QAC3B,OAAO,CAAC;gBACN,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,aAAa,CAAC,YAAY,EAAE,MAAM,CAAC,OAAO,EACnE,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAClC,OAAO,EAAE,MAAM,QAAQ,CAAC,oBAAoB,CAAC,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;aACnF,EAAE;gBACD,IAAI,EAAE,gBAAgB,CACpB,GAAG,CAAC,aAAa,CAAC,YAAY,EAC9B,MAAM,CAAC,OAAO,EACd,GAAG,MAAM,CAAC,IAAI,UAAU,CACzB;gBACD,OAAO,EAAE,mBAAmB,CAC1B,MAAM,QAAQ,CAAC,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC,EAC7D,GAAG,CAAC,aAAa,CAAC,eAAe,CAClC;aACF,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,MAAM,SAAS,GAAc;QAC3B,IAAI,EAAE,oBAAoB;QAC1B,MAAM,EAAE,CAAC,CAAa,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC;QACtE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACtB,yBAAyB,CAAC,GAAG,EAAE,gBAAgB,EAAE,kBAAkB,CAAC,CAAC;YACrE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;KACF,CAAC;IACF,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACjC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAkD,CAAC"}

package/dist/tanstack-grid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tanstack-grid.d.ts","sourceRoot":"","sources":["../src/tanstack-grid.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAA6B,KAAK,gBAAgB,EAA+G,MAAM,4BAA4B,CAAC;AAI3M,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAqCpB,gBAAgB,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC"}
+{"version":3,"file":"tanstack-grid.d.ts","sourceRoot":"","sources":["../src/tanstack-grid.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAA6B,KAAK,gBAAgB,EAExD,MAAM,4BAA4B,CAAC;AAIpC,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAwCpB,gBAAgB,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC"}

package/dist/tanstack-grid.js

@@ -1,4 +1,4 @@
-import { perEntity, formatTs, entityOutputPath, servesReadApi, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID } from "@metaobjectsdev/codegen-ts";
+import { perEntity, formatTs, entityOutputPath, servesReadApi, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID, withClientDirective, } from "@metaobjectsdev/codegen-ts";
 import { hasDataGridLayout, warnMissingDataGridLayout } from "./data-grid-gate.js";
 import { renderColumnsFile } from "./templates/columns-file.js";
 /**
@@ -27,7 +27,7 @@ export const tanstackGrid = function tanstackGrid(opts) {
         }
         return {
             path: entityOutputPath(ctx.renderContext.outputLayout, entity.package, `${entity.name}.columns.tsx`),
-            content: await formatTs(renderColumnsFile(entity, ctx.renderContext)),
+            content: withClientDirective(await formatTs(renderColumnsFile(entity, ctx.renderContext)), ctx.renderContext.clientDirective),
         };
     });
     const generator = {

package/dist/tanstack-grid.js.map

@@ -1 +1 @@
-{"version":3,"file":"tanstack-grid.js","sourceRoot":"","sources":["../src/tanstack-grid.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAyC,QAAQ,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAC3M,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAOhE;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,SAAS,YAAY,CAAC,IAAuB;IACvE,MAAM,UAAU,GAAG,IAAI,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAChD,gFAAgF;IAChF,2EAA2E;IAC3E,0EAA0E;IAC1E,iFAAiF;IACjF,kFAAkF;IAClF,0BAA0B;IAC1B,iFAAiF;IACjF,iFAAiF;IACjF,MAAM,gBAAgB,GAAG,CAAC,CAAa,EAAW,EAAE,CAClD,aAAa,CAAC,CAAC,CAAC;QAChB,2FAA2F;WACxF,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,KAAK,KAAK;WAC5C,UAAU,CAAC,CAAC,CAAC;WACb,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,KAAK,IAAI,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,EAAE,MAAkB,EAAE,GAAG,EAAE,EAAE;QACvD,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;QACnF,CAAC;QACD,OAAO;YACL,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,aAAa,CAAC,YAAY,EAAE,MAAM,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,IAAI,cAAc,CAAC;YACpG,OAAO,EAAE,MAAM,QAAQ,CAAC,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC;SACtE,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,MAAM,SAAS,GAAc;QAC3B,IAAI,EAAE,eAAe;QACrB,MAAM,EAAE,CAAC,CAAa,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC;QACtE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACtB,yBAAyB,CAAC,GAAG,EAAE,gBAAgB,EAAE,sBAAsB,CAAC,CAAC;YACzE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;KACF,CAAC;IACF,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACjC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAA8C,CAAC"}
+{"version":3,"file":"tanstack-grid.js","sourceRoot":"","sources":["../src/tanstack-grid.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAyC,QAAQ,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,0BAA0B,EAAE,sBAAsB,EACpK,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAOhE;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,SAAS,YAAY,CAAC,IAAuB;IACvE,MAAM,UAAU,GAAG,IAAI,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAChD,gFAAgF;IAChF,2EAA2E;IAC3E,0EAA0E;IAC1E,iFAAiF;IACjF,kFAAkF;IAClF,0BAA0B;IAC1B,iFAAiF;IACjF,iFAAiF;IACjF,MAAM,gBAAgB,GAAG,CAAC,CAAa,EAAW,EAAE,CAClD,aAAa,CAAC,CAAC,CAAC;QAChB,2FAA2F;WACxF,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,KAAK,KAAK;WAC5C,UAAU,CAAC,CAAC,CAAC;WACb,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,KAAK,IAAI,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,EAAE,MAAkB,EAAE,GAAG,EAAE,EAAE;QACvD,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;QACnF,CAAC;QACD,OAAO;YACL,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,aAAa,CAAC,YAAY,EAAE,MAAM,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,IAAI,cAAc,CAAC;YACpG,OAAO,EAAE,mBAAmB,CAC1B,MAAM,QAAQ,CAAC,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC,EAC5D,GAAG,CAAC,aAAa,CAAC,eAAe,CAClC;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,MAAM,SAAS,GAAc;QAC3B,IAAI,EAAE,eAAe;QACrB,MAAM,EAAE,CAAC,CAAa,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC;QACtE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACtB,yBAAyB,CAAC,GAAG,EAAE,gBAAgB,EAAE,sBAAsB,CAAC,CAAC;YACzE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;KACF,CAAC;IACF,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACjC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAA8C,CAAC"}

package/dist/tanstack-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tanstack-query.d.ts","sourceRoot":"","sources":["../src/tanstack-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAA6B,KAAK,gBAAgB,EAAiI,MAAM,4BAA4B,CAAC;AAG7N,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAqCrB,gBAAgB,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC"}
+{"version":3,"file":"tanstack-query.d.ts","sourceRoot":"","sources":["../src/tanstack-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAA6B,KAAK,gBAAgB,EAExD,MAAM,4BAA4B,CAAC;AAGpC,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EA0CrB,gBAAgB,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC"}

package/dist/tanstack-query.js

@@ -1,4 +1,4 @@
-import { perEntity, formatTs, entityOutputPath, entityMetaFileName, renderEntityMetaFile, servesReadApi, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK } from "@metaobjectsdev/codegen-ts";
+import { perEntity, formatTs, entityOutputPath, entityMetaFileName, renderEntityMetaFile, servesReadApi, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, withClientDirective, } from "@metaobjectsdev/codegen-ts";
 import { renderHooksFile } from "./templates/hooks-file.js";
 /**
  * Per-entity generator that emits <Entity>.hooks.ts — a query-key factory
@@ -33,7 +33,9 @@ export const tanstackQuery = function tanstackQuery(opts) {
             };
             return [metaFile, {
                     path: entityOutputPath(ctx.renderContext.outputLayout, entity.package, `${entity.name}.hooks.ts`),
-                    content: await formatTs(renderHooksFile(entity, ctx.renderContext)),
+                    // Outside formatTs deliberately: the directive must stay the module's first
+                    // token, and a formatter is entitled to move a leading string expression.
+                    content: withClientDirective(await formatTs(renderHooksFile(entity, ctx.renderContext)), ctx.renderContext.clientDirective),
                 }];
         }),
     };

package/dist/tanstack-query.js.map

@@ -1 +1 @@
-{"version":3,"file":"tanstack-query.js","sourceRoot":"","sources":["../src/tanstack-query.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAyC,QAAQ,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,aAAa,EAAE,YAAY,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAC7N,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAO5D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,aAAa,CAAC,IAAwB;IAC1E,MAAM,UAAU,GAAG,IAAI,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,SAAS,GAAc;QAC3B,IAAI,EAAE,gBAAgB;QACtB,6EAA6E;QAC7E,6EAA6E;QAC7E,6EAA6E;QAC7E,0EAA0E;QAC1E,+EAA+E;QAC/E,iFAAiF;QACjF,iFAAiF;QACjF,MAAM,EAAE,CAAC,CAAa,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,KAAK,KAAK,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC;QAChI,QAAQ,EAAE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE;YACxC,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;gBACvB,MAAM,IAAI,KAAK,CACb,gEAAgE,CACjE,CAAC;YACJ,CAAC,CAAM,0EAA0E;YACjF,yEAAyE;YACzE,+EAA+E;YAC/E,gFAAgF;YAChF,qCAAqC;YACrC,MAAM,QAAQ,GAAG;gBACf,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,aAAa,CAAC,YAAY,EAAE,MAAM,CAAC,OAAO,EACnE,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAClC,OAAO,EAAE,MAAM,QAAQ,CAAC,oBAAoB,CAAC,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;aACnF,CAAC;YACF,OAAO,CAAC,QAAQ,EAAE;oBAChB,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,aAAa,CAAC,YAAY,EAAE,MAAM,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,IAAI,WAAW,CAAC;oBACjG,OAAO,EAAE,MAAM,QAAQ,CAAC,eAAe,CAAC,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC;iBACpE,CAAC,CAAC;QACL,CAAC,CAAC;KACH,CAAC;IACF,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACjC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAA+C,CAAC"}
+{"version":3,"file":"tanstack-query.js","sourceRoot":"","sources":["../src/tanstack-query.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAyC,QAAQ,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,aAAa,EAAE,YAAY,EAAE,0BAA0B,EACtL,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAO5D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,aAAa,CAAC,IAAwB;IAC1E,MAAM,UAAU,GAAG,IAAI,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,SAAS,GAAc;QAC3B,IAAI,EAAE,gBAAgB;QACtB,6EAA6E;QAC7E,6EAA6E;QAC7E,6EAA6E;QAC7E,0EAA0E;QAC1E,+EAA+E;QAC/E,iFAAiF;QACjF,iFAAiF;QACjF,MAAM,EAAE,CAAC,CAAa,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,KAAK,KAAK,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC;QAChI,QAAQ,EAAE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE;YACxC,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;gBACvB,MAAM,IAAI,KAAK,CACb,gEAAgE,CACjE,CAAC;YACJ,CAAC,CAAM,0EAA0E;YACjF,yEAAyE;YACzE,+EAA+E;YAC/E,gFAAgF;YAChF,qCAAqC;YACrC,MAAM,QAAQ,GAAG;gBACf,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,aAAa,CAAC,YAAY,EAAE,MAAM,CAAC,OAAO,EACnE,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAClC,OAAO,EAAE,MAAM,QAAQ,CAAC,oBAAoB,CAAC,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;aACnF,CAAC;YACF,OAAO,CAAC,QAAQ,EAAE;oBAChB,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,aAAa,CAAC,YAAY,EAAE,MAAM,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,IAAI,WAAW,CAAC;oBACjG,4EAA4E;oBAC5E,0EAA0E;oBAC1E,OAAO,EAAE,mBAAmB,CAC1B,MAAM,QAAQ,CAAC,eAAe,CAAC,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC,EAC1D,GAAG,CAAC,aAAa,CAAC,eAAe,CAClC;iBACF,CAAC,CAAC;QACL,CAAC,CAAC;KACH,CAAC;IACF,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACjC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAA+C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/codegen-ts-tanstack",
-  "version": "0.24.3",
+  "version": "0.24.5",
   "description": "TanStack codegen for metaobjects — TanStack Query hooks for every entity, plus TanStack Table column definitions and grid-state hooks for entities declaring a layout.dataGrid.",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,8 +44,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@metaobjectsdev/metadata": "0.24.3",
-    "@metaobjectsdev/codegen-ts": "0.24.3",
+    "@metaobjectsdev/metadata": "0.24.5",
+    "@metaobjectsdev/codegen-ts": "0.24.5",
     "ts-poet": "^6.10.0"
   },
   "peerDependencies": {

package/src/index.ts

@@ -2,3 +2,22 @@
 export { tanstackQuery, type TanstackQueryOpts } from "./tanstack-query.js";
 export { tanstackGrid, type TanstackGridOpts } from "./tanstack-grid.js";
 export { tanstackGridHook, type TanstackGridHookOpts } from "./tanstack-grid-hook.js";
+
+// FR-040 §4.2(b) — public so an owned generator composes the engine rather than
+// forking it. Signatures are stable API: (entity, ctx) => string.
+export { renderHooksFile } from "./templates/hooks-file.js";
+export { renderColumnsFile } from "./templates/columns-file.js";
+export { renderGridHookFile } from "./templates/grid-hook-file.js";
+
+// FR-040 §4.2(b) — the grid/grid-hook data-grid opt-in gate is a STEP in the pipeline
+// those two owned templates compose, not an internal detail either may fork. Public so
+// `grid.ts` and `grid-hook.ts` import one shared implementation instead of each
+// carrying its own copy.
+export { hasDataGridLayout, warnMissingDataGridLayout } from "./data-grid-gate.js";
+
+// FR-040 §4.1 — the copyable reference generators this package ships in
+// `src/reference/`, and the reader `meta init`/`meta eject` use to read them.
+export { resolveReferenceRoot, readReferenceTemplate, REFERENCE_GENERATOR_NAMES } from "./reference-templates.js";
+// The name union travels with the names array — codegen-ts exports both, and a
+// consumer keying anything by ejectable name needs the type as much as the values.
+export type { ReferenceGeneratorName } from "./reference-templates.js";

package/src/reference/grid-hook.ts

@@ -0,0 +1,114 @@
+// REFERENCE TEMPLATE — copy this into your repo (e.g. codegen/generators/grid-hook.ts) and own it.
+// Then import it LOCALLY in metaobjects.config.ts:
+//   import { tanstackGridHook } from "./codegen/generators/grid-hook.js";
+//
+// RUNTIME: this file executes under whatever runs `meta gen` — NODE, even in a Bun
+// project. Do not reach for `Bun.*` globals here.
+// targets:       TanStack Query. The emitted hook calls `useEntityFetcher()` from
+//                `@metaobjectsdev/tanstack`, so the module is a CLIENT component.
+//                If your framework compiles server and client from one tree and resolves
+//                each half under different conditions, the emitted file may need a marker
+//                directive — prepend it to `renderGridHookFile`'s result below. That is a
+//                one-line change in THIS file and is the intended way to do it.
+// use-when:      you want a use<Entity><Grid>Grid() state hook — sort/filter/pagination
+//                wired to TanStack Query — for each `layout.dataGrid` an entity declares.
+// emits:         <target>/<Entity>.grid.ts, plus the DB-free <Entity>.meta.ts descriptor
+//                the hook module imports from. Emissions byte-identical to another UI
+//                generator's copy of the same descriptor collapse to one file (#266).
+// customize:     this generator is YOURS. `renderGridHookFile` (exported from
+//                @metaobjectsdev/codegen-ts-tanstack) produces the hook body — wrap it,
+//                prepend to it, or replace the call entirely with your own renderer.
+// composes-with: grid.ts (the column definitions this hook's grid state pairs with).
+
+import { type MetaObject } from "@metaobjectsdev/metadata";
+import {
+  perEntity,
+  type Generator,
+  type GeneratorFactory,
+  formatTs,
+  entityOutputPath,
+  entityMetaFileName,
+  renderEntityMetaFile,
+  servesReadApi,
+  isTphSubtype,
+  CODEGEN_ATTR_EMIT_TANSTACK,
+  CODEGEN_ATTR_EMIT_GRID,
+  withClientDirective,
+} from "@metaobjectsdev/codegen-ts";
+import {
+  renderGridHookFile,
+  hasDataGridLayout,
+  warnMissingDataGridLayout,
+} from "@metaobjectsdev/codegen-ts-tanstack";
+
+export interface TanstackGridHookOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+/**
+ * Per-entity generator that emits <Entity>.grid.ts — one
+ * use<Entity><Grid>Grid() hook per layout[dataGrid] declared on the entity.
+ *
+ * Per-entity opt-out via @emitTanstack: false. Per-entity opt-IN: presence of
+ * at least one dataGrid layout on the object (mirrors tanstackGrid).
+ */
+export const tanstackGridHook = function tanstackGridHook(opts?: TanstackGridHookOpts): Generator {
+  const userFilter = opts?.filter ?? (() => true);
+  // Every gate EXCEPT the dataGrid-layout opt-in: the framework instance-artifact
+  // guard (skips abstract types), the metadata opt-out, and the user filter. Split
+  // out so the discoverability note can name exactly the entities the LAYOUT gate
+  // alone held back (#287).
+  //
+  // The TPH clause must MATCH tanstackGrid's exactly. A TPH subtype inherits its base's
+  // dataGrid layout via extends, so `hasDataGridLayout` is true for it — but tanstackGrid
+  // deliberately emits no per-subtype columns without an own `@emitGrid: true` (the base's
+  // polymorphic grid is the single source of truth). Without the same clause here, a TPH
+  // subtype got a `<Sub>.grid.ts` whose sibling `<Sub>.columns.tsx` is never emitted:
+  // a dangling `use<Sub>DefaultGrid()` with nothing to pair it with, and an outright
+  // TS2307 when the inherited layout carries an `@filter` preset (the hook then imports
+  // `<sub>DefaultFilter` from the missing columns module).
+  const passesOtherGates = (e: MetaObject): boolean =>
+    servesReadApi(e)
+    // ADR-0039: resolving — a concrete entity may inherit its @emit* opt-out flag via extends.
+    && e.attr(CODEGEN_ATTR_EMIT_TANSTACK) !== false
+    && userFilter(e)
+    && (!isTphSubtype(e) || e.attr(CODEGEN_ATTR_EMIT_GRID) === true);
+  const emit = perEntity(async (entity: MetaObject, ctx) => {
+    if (!ctx.renderContext) {
+      throw new Error("tanstack-grid-hook: renderContext is required (provided by runGen)");
+    }
+    // Also emit the DB-free descriptor module this file imports from. Each UI
+    // generator emits it rather than relying on the consumer wiring an extra one:
+    // the entity generator is scaffold-and-own (ADR-0034), so it cannot be changed
+    // from the package. Emissions are byte-identical between generators, which the
+    // runner collapses (#266).
+    return [{
+      path: entityOutputPath(ctx.renderContext.outputLayout, entity.package,
+        entityMetaFileName(entity.name)),
+      content: await formatTs(renderEntityMetaFile(entity, ctx.renderContext.apiPrefix)),
+    }, {
+      path: entityOutputPath(
+        ctx.renderContext.outputLayout,
+        entity.package,
+        `${entity.name}.grid.ts`,
+      ),
+      content: withClientDirective(
+        await formatTs(renderGridHookFile(entity, ctx.renderContext)),
+        ctx.renderContext.clientDirective,
+      ),
+    }];
+  });
+  const generator: Generator = {
+    name: "tanstack-grid-hook",
+    filter: (e: MetaObject) => passesOtherGates(e) && hasDataGridLayout(e),
+    generate: async (ctx) => {
+      warnMissingDataGridLayout(ctx, passesOtherGates, "<Entity>.grid.ts");
+      return emit(ctx);
+    },
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<TanstackGridHookOpts | void>;

package/src/reference/grid.ts

@@ -0,0 +1,93 @@
+// REFERENCE TEMPLATE — copy this into your repo (e.g. codegen/generators/grid.ts) and own it.
+// Then import it LOCALLY in metaobjects.config.ts:
+//   import { tanstackGrid } from "./codegen/generators/grid.js";
+//
+// RUNTIME: this file executes under whatever runs `meta gen` — NODE, even in a Bun
+// project. Do not reach for `Bun.*` globals here.
+// targets:       TanStack Table. The emitted module's `ColumnDef` comes from
+//                `@tanstack/react-table`, so it is a CLIENT component.
+//                If your framework compiles server and client from one tree and resolves
+//                each half under different conditions, the emitted file may need a marker
+//                directive — prepend it to `renderColumnsFile`'s result below. That is a
+//                one-line change in THIS file and is the intended way to do it.
+// use-when:      you want generated grid column definitions for any entity declaring a
+//                `layout.dataGrid` child.
+// emits:         <target>/<Entity>.columns.tsx — one column set per declared dataGrid
+//                layout; a TPH discriminator base's grid folds in its subtypes' fields.
+// customize:     this generator is YOURS. `renderColumnsFile` (exported from
+//                @metaobjectsdev/codegen-ts-tanstack) produces the column definitions —
+//                wrap it, prepend to it, or replace the call entirely with your own
+//                renderer.
+// composes-with: entity.ts (imports the Row type the columns are typed against),
+//                hooks.ts (the query hook a grid usually pairs with).
+
+import { type MetaObject } from "@metaobjectsdev/metadata";
+import {
+  perEntity,
+  type Generator,
+  type GeneratorFactory,
+  formatTs,
+  entityOutputPath,
+  servesReadApi,
+  isTphSubtype,
+  CODEGEN_ATTR_EMIT_TANSTACK,
+  CODEGEN_ATTR_EMIT_GRID,
+  withClientDirective,
+} from "@metaobjectsdev/codegen-ts";
+import {
+  renderColumnsFile,
+  hasDataGridLayout,
+  warnMissingDataGridLayout,
+} from "@metaobjectsdev/codegen-ts-tanstack";
+
+export interface TanstackGridOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+/**
+ * Per-entity opt-out via `@emitTanstack: false`. Per-entity opt-IN: presence of
+ * at least one `dataGrid` layout on the object. If both pass and the user-supplied
+ * filter passes, the generator emits.
+ */
+export const tanstackGrid = function tanstackGrid(opts?: TanstackGridOpts): Generator {
+  const userFilter = opts?.filter ?? (() => true);
+  // Every gate EXCEPT the dataGrid-layout opt-in: the framework instance-artifact
+  // guard (skips abstract types), the metadata opt-out, and the user filter.
+  // FR-017 Tier 3: a TPH discriminator base emits ONE polymorphic grid. Its
+  // subtypes inherit the base's dataGrid layout via extends, but per-subtype grids
+  // are opt-IN only (own `@emitGrid: true`) — otherwise the polymorphic grid is the
+  // single source of truth.
+  // Split out so the discoverability note can name exactly the entities the LAYOUT
+  // gate alone held back (#287) — an opted-out or abstract type is not a surprise.
+  const passesOtherGates = (e: MetaObject): boolean =>
+    servesReadApi(e)
+    // ADR-0039: resolving — a concrete entity may inherit its @emit* opt-out flag via extends.
+    && e.attr(CODEGEN_ATTR_EMIT_TANSTACK) !== false
+    && userFilter(e)
+    && (!isTphSubtype(e) || e.attr(CODEGEN_ATTR_EMIT_GRID) === true);
+  const emit = perEntity(async (entity: MetaObject, ctx) => {
+    if (!ctx.renderContext) {
+      throw new Error("tanstack-grid: renderContext is required (provided by runGen)");
+    }
+    return {
+      path: entityOutputPath(ctx.renderContext.outputLayout, entity.package, `${entity.name}.columns.tsx`),
+      content: withClientDirective(
+        await formatTs(renderColumnsFile(entity, ctx.renderContext)),
+        ctx.renderContext.clientDirective,
+      ),
+    };
+  });
+  const generator: Generator = {
+    name: "tanstack-grid",
+    filter: (e: MetaObject) => passesOtherGates(e) && hasDataGridLayout(e),
+    generate: async (ctx) => {
+      warnMissingDataGridLayout(ctx, passesOtherGates, "<Entity>.columns.tsx");
+      return emit(ctx);
+    },
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<TanstackGridOpts | void>;

package/src/reference/hooks.ts

@@ -0,0 +1,93 @@
+// REFERENCE TEMPLATE — copy this into your repo (e.g. codegen/generators/hooks.ts) and own it.
+// Then import it LOCALLY in metaobjects.config.ts:
+//   import { tanstackQuery } from "./codegen/generators/hooks.js";
+//
+// RUNTIME: this file executes under whatever runs `meta gen` — NODE, even in a Bun
+// project. Do not reach for `Bun.*` globals here.
+// targets:       TanStack Query. The emitted hooks call `useEntityFetcher()` from
+//                `@metaobjectsdev/tanstack`, so the module is a CLIENT component.
+//                If your framework compiles server and client from one tree and resolves
+//                each half under different conditions, the emitted file may need a marker
+//                directive — prepend it to `renderHooksFile`'s result below. That is a
+//                one-line change in THIS file and is the intended way to do it.
+// use-when:      you want a query-key factory plus 2 query hooks and 3 mutation hooks,
+//                backed by TanStack Query, per entity.
+// emits:         <target>/<Entity>.hooks.ts, plus the DB-free <Entity>.meta.ts descriptor
+//                the hooks module imports from. Emissions byte-identical to another UI
+//                generator's copy of the same descriptor collapse to one file (#266).
+// customize:     this generator is YOURS. `renderHooksFile` (exported from
+//                @metaobjectsdev/codegen-ts-tanstack) produces the hooks body — wrap it,
+//                prepend to it, or replace the call entirely with your own renderer.
+// composes-with: entity.ts (imports the table/schemas these hooks fetch/validate against).
+
+import { type MetaObject } from "@metaobjectsdev/metadata";
+import {
+  perEntity,
+  type Generator,
+  type GeneratorFactory,
+  formatTs,
+  entityOutputPath,
+  entityMetaFileName,
+  renderEntityMetaFile,
+  servesReadApi,
+  isTphSubtype,
+  CODEGEN_ATTR_EMIT_TANSTACK,
+  withClientDirective,
+} from "@metaobjectsdev/codegen-ts";
+import { renderHooksFile } from "@metaobjectsdev/codegen-ts-tanstack";
+
+export interface TanstackQueryOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+/**
+ * Per-entity generator that emits <Entity>.hooks.ts — a query-key factory
+ * plus 2 query hooks and 3 mutation hooks backed by useEntityFetcher().
+ *
+ * Per-entity opt-out via `@emitTanstack: false` is honored. If the user
+ * supplies their own filter, both must pass (AND).
+ */
+export const tanstackQuery = function tanstackQuery(opts?: TanstackQueryOpts): Generator {
+  const userFilter = opts?.filter ?? (() => true);
+  const generator: Generator = {
+    name: "tanstack-query",
+    // AND-composes the framework instance-artifact guard (skips abstract types —
+    // they contribute shape via inheritance only and have no instance to query),
+    // the metadata opt-out, and the optional user filter. Projections still pass
+    // here and get read-only hooks via renderHooksFile's isProjection branch.
+    // FR-017 Tier 3: TPH subtypes get no standalone hooks file — their per-subtype
+    // hooks live in the discriminator base's hooks file (polymorphic + per-subtype).
+    // ADR-0039: resolving — a concrete entity may inherit @emitTanstack via extends.
+    filter: (e: MetaObject) => servesReadApi(e) && e.attr(CODEGEN_ATTR_EMIT_TANSTACK) !== false && !isTphSubtype(e) && userFilter(e),
+    generate: perEntity(async (entity, ctx) => {
+      if (!ctx.renderContext) {
+        throw new Error(
+          "tanstack-query: renderContext is required (provided by runGen)",
+        );
+      }      // Also emit the DB-free descriptor module this file imports from. Each UI
+      // generator emits it rather than relying on the consumer wiring an extra
+      // generator: the entity generator is scaffold-and-own (ADR-0034), so it cannot
+      // be changed from the package. Emissions are byte-identical between generators,
+      // which the runner collapses (#266).
+      const metaFile = {
+        path: entityOutputPath(ctx.renderContext.outputLayout, entity.package,
+          entityMetaFileName(entity.name)),
+        content: await formatTs(renderEntityMetaFile(entity, ctx.renderContext.apiPrefix)),
+      };
+      return [metaFile, {
+        path: entityOutputPath(ctx.renderContext.outputLayout, entity.package, `${entity.name}.hooks.ts`),
+        // Outside formatTs deliberately: the directive must stay the module's first
+        // token, and a formatter is entitled to move a leading string expression.
+        content: withClientDirective(
+          await formatTs(renderHooksFile(entity, ctx.renderContext)),
+          ctx.renderContext.clientDirective,
+        ),
+      }];
+    }),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<TanstackQueryOpts | void>;

package/src/reference-templates.ts

@@ -0,0 +1,16 @@
+// FR-040 §4.1 — this package hosts its own copyable reference generators in
+// `src/reference/`, read through the shared factory so the resolver is not duplicated.
+import { makeReferenceReader } from "@metaobjectsdev/codegen-ts";
+
+export const REFERENCE_GENERATOR_NAMES = ["hooks", "grid", "grid-hook"] as const;
+export type ReferenceGeneratorName = (typeof REFERENCE_GENERATOR_NAMES)[number];
+
+const reader = makeReferenceReader(import.meta.url, REFERENCE_GENERATOR_NAMES);
+
+export function resolveReferenceRoot(): string {
+  return reader.resolveReferenceRoot();
+}
+
+export function readReferenceTemplate(name: ReferenceGeneratorName): string {
+  return reader.readReferenceTemplate(name);
+}

package/src/tanstack-grid-hook.ts

@@ -1,5 +1,7 @@
 import type { MetaObject } from "@metaobjectsdev/metadata";
-import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, entityMetaFileName, renderEntityMetaFile, servesReadApi, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID } from "@metaobjectsdev/codegen-ts";
+import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, entityMetaFileName, renderEntityMetaFile, servesReadApi, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID,
+  withClientDirective,
+} from "@metaobjectsdev/codegen-ts";
 import { hasDataGridLayout, warnMissingDataGridLayout } from "./data-grid-gate.js";
 import { renderGridHookFile } from "./templates/grid-hook-file.js";
 
@@ -55,7 +57,10 @@ export const tanstackGridHook = function tanstackGridHook(opts?: TanstackGridHoo
         entity.package,
         `${entity.name}.grid.ts`,
       ),
-      content: await formatTs(renderGridHookFile(entity, ctx.renderContext)),
+      content: withClientDirective(
+        await formatTs(renderGridHookFile(entity, ctx.renderContext)),
+        ctx.renderContext.clientDirective,
+      ),
     }];
   });
   const generator: Generator = {

package/src/tanstack-grid.ts

@@ -1,5 +1,7 @@
 import type { MetaObject } from "@metaobjectsdev/metadata";
-import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, servesReadApi, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID } from "@metaobjectsdev/codegen-ts";
+import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, servesReadApi, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID,
+  withClientDirective,
+} from "@metaobjectsdev/codegen-ts";
 import { hasDataGridLayout, warnMissingDataGridLayout } from "./data-grid-gate.js";
 import { renderColumnsFile } from "./templates/columns-file.js";
 
@@ -35,7 +37,10 @@ export const tanstackGrid = function tanstackGrid(opts?: TanstackGridOpts): Gene
     }
     return {
       path: entityOutputPath(ctx.renderContext.outputLayout, entity.package, `${entity.name}.columns.tsx`),
-      content: await formatTs(renderColumnsFile(entity, ctx.renderContext)),
+      content: withClientDirective(
+        await formatTs(renderColumnsFile(entity, ctx.renderContext)),
+        ctx.renderContext.clientDirective,
+      ),
     };
   });
   const generator: Generator = {

package/src/tanstack-query.ts

@@ -1,5 +1,7 @@
 import type { MetaObject } from "@metaobjectsdev/metadata";
-import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, entityMetaFileName, renderEntityMetaFile, servesReadApi, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK } from "@metaobjectsdev/codegen-ts";
+import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, entityMetaFileName, renderEntityMetaFile, servesReadApi, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK,
+  withClientDirective,
+} from "@metaobjectsdev/codegen-ts";
 import { renderHooksFile } from "./templates/hooks-file.js";
 
 export interface TanstackQueryOpts {
@@ -43,7 +45,12 @@ export const tanstackQuery = function tanstackQuery(opts?: TanstackQueryOpts): G
       };
       return [metaFile, {
         path: entityOutputPath(ctx.renderContext.outputLayout, entity.package, `${entity.name}.hooks.ts`),
-        content: await formatTs(renderHooksFile(entity, ctx.renderContext)),
+        // Outside formatTs deliberately: the directive must stay the module's first
+        // token, and a formatter is entitled to move a leading string expression.
+        content: withClientDirective(
+          await formatTs(renderHooksFile(entity, ctx.renderContext)),
+          ctx.renderContext.clientDirective,
+        ),
       }];
     }),
   };