@_tc/template-core 0.2.12 → 0.3.0

package/.skills/tc-component-usage-skills/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: tc-component-usage-skills
-description: Use when building or modifying React UI in TemplateCore projects. Covers how to choose, compose, and correctly use components from `@tc/ui-react` / `@_tc/template-core/fe/rc`, plus TemplateCore frontend helpers from `@_tc/template-core/fe` such as `AsyncSelect`, `LanguageSwitch`, and `ThemeSwitch`. Includes patterns for forms, tables, modals, drawers, menus, Dashboard toolbar UI, and TC visual style.
+description: Use when building or modifying React UI in TemplateCore projects. Covers how to choose, compose, and correctly use components from the published `@_tc/template-core/fe/rc` UI entry, plus TemplateCore frontend helpers from `@_tc/template-core/fe` such as `AsyncSelect`, `LanguageSwitch`, and `ThemeSwitch`. Includes patterns for forms, tables, modals, drawers, menus, Dashboard toolbar UI, and TC visual style.
 ---
 
 # TC Component Usage
 
-Use this skill when writing React components that consume `@tc/ui-react`, `@_tc/template-core/fe/rc`, or TemplateCore frontend helpers from `@_tc/template-core/fe`.
+Use this skill when writing React components that consume the published TemplateCore UI entry `@_tc/template-core/fe/rc` or frontend helpers from `@_tc/template-core/fe`.
 
 ## Quick Decision Flow
 
@@ -51,7 +51,7 @@ const [form] = useForm<T>();
 ```
 
 UI-library built-in `type` values: `input`, `inputNumber`, `select`, `textarea`, `switch`, `date`, `checkbox`.
-TemplateCore adds framework type `asyncSelect` via `@tc/scalability/SchemaForm/frameData`; custom app types are registered via `@tc/scalability/SchemaForm/data`.
+TemplateCore adds framework type `asyncSelect`; custom app types are registered in the consumer app at `frontend/extended/SchemaForm/data.ts`.
 
 ### Modal (Declarative + Imperative)
 
@@ -114,24 +114,22 @@ pnpm type-check
 ## Component Import Convention
 
 ```tsx
-import { Button, Form, FormItem, Input, DataTable, Modal, modal, useForm } from '@tc/ui-react'
+import { Button, Form, FormItem, Input, DataTable, Modal, modal, useForm } from '@_tc/template-core/fe/rc'
 import { AsyncSelect, LanguageSwitch, ThemeSwitch } from '@_tc/template-core/fe'
 ```
 
-When consuming the published TemplateCore package, `@_tc/template-core/fe/rc` re-exports the UI component library:
+When editing the TemplateCore package source repository, `@tc/ui-react` is the raw UI workspace package. Published consumer projects should use `@_tc/template-core/fe/rc`, which re-exports the UI component library:
 
 ```tsx
 import { Button, DataTable, TableSearch } from '@_tc/template-core/fe/rc'
 ```
 
-Inside this source repository, use `@tc/ui-react` for the raw UI workspace package. The `@_tc/template-core/fe/rc` path is a published TemplateCore package export generated into `dist/package.json`.
-
 Style entry:
 
 ```tsx
-import '@tc/ui-react/index.css'
-// or, in published TemplateCore frontend entries:
 import '@_tc/template-core/fe/tailwind_ui.css'
+// source repository raw UI work can use:
+// import '@tc/ui-react/index.css'
 ```
 
 ## Visual Style

package/.skills/tc-component-usage-skills/reference/component-api.md

@@ -1,6 +1,6 @@
 # Component API Reference
 
-Complete props for every `@tc/ui-react` component.
+Complete props for the UI components re-exported by `@_tc/template-core/fe/rc`.
 
 ---
 
@@ -317,7 +317,7 @@ interface SchemaFormProps<T> {
 }
 ```
 
-**Important:** In `horizontal` layout, `footerButtons` are NOT auto-rendered. UI-library built-in types: `input`, `inputNumber`, `select`, `textarea`, `switch`, `date`, `checkbox`. TemplateCore also registers framework type `asyncSelect`. App types are extensible via `@tc/scalability/SchemaForm/data`.
+**Important:** In `horizontal` layout, `footerButtons` are NOT auto-rendered. UI-library built-in types: `input`, `inputNumber`, `select`, `textarea`, `switch`, `date`, `checkbox`. TemplateCore also registers framework type `asyncSelect`. App types are registered in `frontend/extended/SchemaForm/data.ts` and resolved by the TemplateCore build alias.
 
 ---
 

package/.skills/tc-component-usage-skills/reference/examples.md

@@ -8,8 +8,8 @@ Copy-paste starting points for common TC UI scenarios.
 
 ```tsx
 import { useState, useEffect, useCallback } from 'react'
-import { DataTable, TableSearch, Button, Modal, SchemaForm, ConfirmDialog, message, useForm } from '@tc/ui-react'
-import type { TableColumnDef, TableSearchSchema } from '@tc/ui-react'
+import { DataTable, TableSearch, Button, Modal, SchemaForm, ConfirmDialog, message, useForm } from '@_tc/template-core/fe/rc'
+import type { TableColumnDef, TableSearchSchema } from '@_tc/template-core/fe/rc'
 
 interface Product {
   id: number
@@ -164,7 +164,7 @@ export function ProductList() {
 ## Example 2: Detail Drawer
 
 ```tsx
-import { Drawer, Button, Loading, Skeleton } from '@tc/ui-react'
+import { Drawer, Button, Loading, Skeleton } from '@_tc/template-core/fe/rc'
 
 export function UserDetailDrawer({ userId, open, onClose }: {
   userId: number | null
@@ -207,7 +207,7 @@ export function UserDetailDrawer({ userId, open, onClose }: {
 ## Example 3: App Shell with Sidebar Menu
 
 ```tsx
-import { Layout, Menu, Breadcrumb } from '@tc/ui-react'
+import { Layout, Menu, Breadcrumb } from '@_tc/template-core/fe/rc'
 import { useNavigate, useLocation } from 'react-router-dom'
 
 export function AppShell({ children }: { children: ReactNode }) {
@@ -253,7 +253,7 @@ export function AppShell({ children }: { children: ReactNode }) {
 ## Example 4: Image Upload Form
 
 ```tsx
-import { SchemaForm, ImageUpload, message, useForm } from '@tc/ui-react'
+import { SchemaForm, ImageUpload, message, useForm } from '@_tc/template-core/fe/rc'
 
 interface BannerForm {
   title: string
@@ -295,7 +295,7 @@ function BannerEditor() {
 ## Example 5: TreeSelect for Permissions
 
 ```tsx
-import { TreeSelect } from '@tc/ui-react'
+import { TreeSelect } from '@_tc/template-core/fe/rc'
 
 function PermissionEditor() {
   const [checked, setChecked] = useState<(string | number)[]>([])
@@ -326,7 +326,7 @@ function PermissionEditor() {
 ## Example 6: DataTable with Row Selection (Batch Actions)
 
 ```tsx
-import { DataTable, Button, message } from '@tc/ui-react'
+import { DataTable, Button, message } from '@_tc/template-core/fe/rc'
 
 function BatchUserList() {
   const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([])
@@ -368,7 +368,7 @@ function BatchUserList() {
 ## Example 7: DatePicker Usage
 
 ```tsx
-import { DatePicker } from '@tc/ui-react'
+import { DatePicker } from '@_tc/template-core/fe/rc'
 
 // Single date
 <DatePicker
@@ -398,7 +398,7 @@ import { DatePicker } from '@tc/ui-react'
 ## Example 8: Tooltip & Popup
 
 ```tsx
-import { Tooltip, Popup, Dropdown, Button } from '@tc/ui-react'
+import { Tooltip, Popup, Dropdown, Button } from '@_tc/template-core/fe/rc'
 import { useRef, useState } from 'react'
 
 // Simple tooltip

package/.skills/tc-component-usage-skills/reference/patterns.md

@@ -1,6 +1,6 @@
 # Component Patterns
 
-Recurring patterns and best practices for `@tc/ui-react`.
+Recurring patterns and best practices for TemplateCore UI components from `@_tc/template-core/fe/rc`.
 
 ---
 
@@ -69,7 +69,7 @@ TemplateCore already registers framework field type `asyncSelect`:
 The options endpoint should return the normal TemplateCore response wrapper, usually via `this.success(ctx, options)`.
 
 ```tsx
-// In the app-side module aliased as @tc/scalability/SchemaForm/data:
+// frontend/extended/SchemaForm/data.ts
 const consumerComponentsMap = {
   richText: RichTextEditor,
   userSelector: UserSelect,
@@ -311,7 +311,7 @@ In `mode='top'`, SubMenus always use popup dropdowns.
 ### Toast Messages
 
 ```tsx
-import { message } from '@tc/ui-react'
+import { message } from '@_tc/template-core/fe/rc'
 
 message.success('User created successfully')
 message.error('Failed to save')
@@ -322,7 +322,7 @@ message.info('New update available')
 ### Notifications (Corner)
 
 ```tsx
-import { Notification } from '@tc/ui-react'
+import { Notification } from '@_tc/template-core/fe/rc'
 
 // As component
 <Notification type="error" title="Upload Failed" message="Network error. Retry?" />
@@ -385,7 +385,7 @@ This means both patterns work identically:
 
 ## CSS Conventions
 
-- Import styles before using components: `@tc/ui-react/index.css` for raw UI usage, or `@_tc/template-core/fe/tailwind_ui.css` for published TemplateCore frontend entries.
+- Import styles before using components: `@_tc/template-core/fe/tailwind_ui.css` for published TemplateCore frontend entries; raw UI source work can use `@tc/ui-react/index.css`.
 - All CSS classes are prefixed `tc-ui-<component-name>`
 - Tailwind CSS used for styling
 - Theme via CSS custom properties: `hsl(var(--theme-primary))`, `hsl(var(--theme-background))`, etc.

package/.skills/tc-component-usage-skills/reference/template-core-frontend.md

@@ -11,7 +11,7 @@ import type { BaseResponse, RequestConfig, ResponseConfig } from '@_tc/template-
 import { Button, DataTable, TableSearch } from '@_tc/template-core/fe/rc'
 ```
 
-Inside this repository, use `@tc/ui-react` for the raw UI workspace package. In published business projects, prefer `@_tc/template-core/fe/rc` for UI components, `@_tc/template-core/fe` for frontend runtime helpers, and `@_tc/template-core/fe/common/request` when only the request layer is needed.
+Inside the TemplateCore package source repository, use `@tc/ui-react` for the raw UI workspace package. In published business projects, prefer `@_tc/template-core/fe/rc` for UI components, `@_tc/template-core/fe` for frontend runtime helpers, and `@_tc/template-core/fe/common/request` when only the request layer is needed.
 
 ## LanguageSwitch
 

package/.skills/tc-generator/SKILL.md

@@ -1,21 +1,24 @@
 ---
 name: tc-generator
-description: Generate TemplateCore business projects, modules, model configurations, Schema CRUD pages, controllers, routers, and project overrides that follow this repository's Koa + React + model-driven conventions. Use when the user asks to create or modify TC/TemplateCore projects, admin modules, model/mode.js files, schemaConfig CRUD pages, menu structures, or app/controller and app/router files.
+description: Generate consumer business projects, modules, model configurations, Schema CRUD pages, controllers, routers, and project overrides that use the TemplateCore npm package's Koa + React + model-driven conventions. Use when the user asks to create or modify TC/TemplateCore consumer apps, admin modules, models/mode.js files, schemaConfig CRUD pages, menu structures, or app/controller and app/router files.
 ---
 
 # TC Generator
 
-Use this skill to generate or update TemplateCore business code.
+Use this skill to generate or update consumer business code that runs on TemplateCore.
+
+This workspace is the TemplateCore npm package repository (`@_tc/template-core`). Treat generated business code as consumer-app code that imports the package. Do not treat the package repository root as the business `baseDir` unless the user explicitly asks to edit this repository's demo, reference templates, or framework/package source.
 
 ## Quick Workflow
 
-1. Identify the target business root. In this repository, a generated project usually uses:
+1. Identify the target consumer business root. A generated consumer app usually uses:
    - `index.js`
    - `config/config.default.js`
    - `app/controller/*.js`
    - `app/router/*.js`
-   - `model/{modelKey}/mode.js`
-   - optional `model/{modelKey}/project/{projectKey}.js`
+   - `models/{modelKey}/mode.js`
+   - optional `models/{modelKey}/project/{projectKey}.js`
+   - optional `ssr/apps/{page}/{page}.entry.jsx|tsx` only when the user explicitly asks for SSR pages.
 2. Read only the reference needed:
    - Model/menu/schema rules: `reference/model-schema.md`
    - Runtime extensions (db, Dashboard slots/routes, frontend helpers): `reference/runtime-extensions.md`
@@ -23,15 +26,17 @@ Use this skill to generate or update TemplateCore business code.
    - Complete product CRUD example: `reference/example.md`
 3. Generate the smallest working slice first: config, entry, controller, router, model.
 4. Keep keys stable. Array merge and project overrides depend on `key`.
-5. Prefer CommonJS `.js` for generated business examples unless the existing business project already uses TypeScript.
+5. Prefer CommonJS `.js` for generated consumer examples unless the existing consumer app already uses TypeScript.
 
 ## TemplateCore Conventions
 
-- Start the app with `serverStart({ name, baseDir })` from `@_tc/template-core`.
-- Start the built-in frontend with `await buildFE("dev")` from `@_tc/template-core/bundler` when the user needs the admin UI. The current API returns `Promise<void>`; in dev mode it performs the initial build, then watches the business `frontend/` directory. Use `buildFE("prod", { output: "run", minifyHtml: true })` when the generated project should emit its own `app/public/dist` templates and compact final `.tpl` output.
+- Start the consumer app with `serverStart({ name, baseDir })` from `@_tc/template-core`.
+- Start the built-in frontend with `await buildFE("dev")` from `@_tc/template-core/bundler` when the user needs the admin UI. The current API returns `Promise<void>`; in dev mode it performs the initial build, then watches the consumer app's `frontend/` directory. Use `buildFE("prod", { output: "run", minifyHtml: true })` when the generated consumer app should emit its own `app/public/dist` templates and compact final `.tpl` output.
 - `buildFE()` writes `FEBuildKey` into the output directory; the server uses it to invalidate local HTML ETag cache after frontend rebuilds.
-- If `buildFE("dev")` is used in a standalone project, include the TemplateCore peer dependencies or use the package manager's peer dependency auto-install behavior.
-- Business code lives under the user's `baseDir`, not inside TemplateCore framework folders.
+- Generate SSR pages only when requested. SSR entries live under `ssr/apps/{page}/{page}.entry.tsx`, import `createSSREntry` from `@_tc/template-core/ssr/createSSREntry`, and are built with `buildSSR({ baseDir, output: "run" })` from `@_tc/template-core/bundler`. Use `watchSSRFiles({ baseDir, output: "run" })` for development watches. SSR entries may export static strings or `SSRPageMetaResolver` functions as `pageTitle` / `pageDescription`; resolver functions run after `getServerProps()` and receive `{ params, query, path, app, ctx, props }`.
+- SSR entry files are built for both server and browser. Do not put top-level Node-only or browser-only side effects in them; load server-only code inside `getServerProps()` with dynamic import and guard browser APIs with `typeof window !== "undefined"` or React effects. Do not call frontend API helpers that depend on `window` or `localStorage` from `getServerProps()`; put Node-safe request/data code in `*.server.ts` and import it dynamically from `getServerProps()`.
+- If `buildFE("dev")` is used in a standalone consumer app, include the TemplateCore peer dependencies or use the package manager's peer dependency auto-install behavior.
+- Consumer business code lives under the consumer app's `baseDir`, not inside this TemplateCore npm package's framework folders.
 - The framework provides `app.extends.db` as a default SQLite-backed KV/SQL helper. Use it for small framework/business settings; override `app/extends/db.js` only when the project needs a custom storage implementation.
 - Backend loaders map filenames to camelCase fields:
   - `app/controller/product.js` -> `app.controller.product`
@@ -47,25 +52,36 @@ Use this skill to generate or update TemplateCore business code.
 
 ## Output Rules
 
-- Make generated code directly runnable when package dependencies are installed.
+- Make generated consumer code directly runnable when its package dependencies are installed.
 - Include realistic in-memory data only for demos or scaffolds.
 - Use `$i18n::...` only when also adding or pointing to language resources; otherwise write plain labels.
 - For Schema CRUD, include `tableOption`, `createFormOption`, `editFormOption`, and `detailPanelOption` only where the field should appear.
 - For edit/detail components, set `fetchKey` to the primary key field.
 - For remove buttons, use `$schema::{field}` to pull values from the current row.
-- Generate frontend extensions only when needed:
+- When generating or updating a model, validate every requested form `comType` and table `renderComponent` before writing the model:
+  - Do not hard-code the available `comType` or `renderComponent` names in this skill. They are extensible by the framework consumer and can vary by project/version.
+  - Determine availability from the target consumer app's existing registrations and the TemplateCore package source/docs available in this repository. Consumer app registrations include `frontend/extended/SchemaForm/data.ts` for form types and `frontend/extended/SchemaPage/SchemaTable/data.ts` for table render components.
+  - If a requested type/component cannot be verified as available, do not invent a substitute, do not auto-create frontend extensions, and do not force the model to use an unknown type. Return the unverified/missing type list to the user and ask them to choose whether to reuse an existing type, add/register a custom component, or adjust the field design.
+- Generate frontend extensions only when explicitly requested or after the user confirms a missing custom type/component:
   - Dashboard header UI: `frontend/extended/dash/components.tsx` with `HeaderView.userArea`
   - Dashboard custom routes: `frontend/extended/dash/customRoutes.tsx`
   - SchemaForm field types: `frontend/extended/SchemaForm/data.ts`
+  - SchemaTable render components: `frontend/extended/SchemaPage/SchemaTable/data.ts`
   - SchemaPage custom call components: `frontend/extended/SchemaPage/CallCom/data.ts`
 
 ## Validation
 
-When editing an existing project, verify with the closest available command:
+When editing this TemplateCore npm package repository, verify with the closest relevant package command:
+
+```bash
+npm run type-check
+```
+
+When editing or generating a consumer business project, verify with the closest command available in that project:
 
 ```bash
 pnpm type-check
 pnpm dev
 ```
 
-For generated standalone CommonJS examples, at minimum inspect paths and imports against the current package name.
+For generated standalone CommonJS examples, at minimum inspect paths and imports against the TemplateCore package name.

package/.skills/tc-generator/reference/example.md

@@ -1,6 +1,6 @@
 # Complete Product CRUD Example
 
-This example creates a minimal TemplateCore business project with a product Schema CRUD page.
+This example creates a minimal consumer business project that imports the `@_tc/template-core` npm package and exposes a product Schema CRUD page. It is not the layout of the TemplateCore package repository itself.
 
 ## Structure
 
@@ -13,7 +13,7 @@ my-admin/
 │       └── product.js
 ├── config/
 │   └── config.default.js
-├── model/
+├── models/
 │   └── product/
 │       ├── mode.js
 │       └── project/
@@ -155,7 +155,7 @@ module.exports = (app, router) => {
 };
 ```
 
-## model/product/mode.js
+## models/product/mode.js
 
 ```js
 module.exports = {
@@ -339,7 +339,7 @@ module.exports = {
 };
 ```
 
-## model/product/project/default.js
+## models/product/project/default.js
 
 ```js
 module.exports = {

package/.skills/tc-generator/reference/model-schema.md

@@ -1,15 +1,17 @@
 # TemplateCore Model Schema Reference
 
+This reference describes model files in a consumer business app that uses the `@_tc/template-core` npm package. Paths are relative to that app's `baseDir`, not to the TemplateCore package repository root, unless the user explicitly asks to edit this repository's demo or reference files.
+
 ## File Layout
 
-The model loader reads the business root:
+The model loader reads the consumer business root:
 
 ```text
-model/{modelKey}/mode.js
-model/{modelKey}/project/{projectKey}.js
+models/{modelKey}/mode.js
+models/{modelKey}/project/{projectKey}.js
 ```
 
-`model/index.js` and `model/index.ts` are ignored.
+`models/index.js` and `models/index.ts` are ignored.
 
 Loader output shape:
 
@@ -228,7 +230,7 @@ cover: {
 
 Built-in `PreviewImage` accepts the current field value as a string or string array. Project-specific table render components are registered in `frontend/extended/SchemaPage/SchemaTable/data.ts` and referenced by `tableOption.renderComponent`.
 
-Common form `comType` values:
+Example form `comType` values often seen in TemplateCore configs. This is not an authoritative or exhaustive list; verify available types from the target consumer app and this package repository before generating a model.
 
 ```text
 input
@@ -240,6 +242,8 @@ date
 checkbox
 ```
 
+Model generation guard: before writing generated model config, verify that every `comType` and `tableOption.renderComponent` can be found in the target consumer app registrations or the TemplateCore package source/docs available in this repository. Because both extension points are consumer-extensible, this reference should not be treated as an authoritative list of all valid names. If a needed type cannot be verified, return the unverified `comType` / `renderComponent` names to the user for confirmation instead of auto-creating a custom component or forcing an unknown type into the model.
+
 Useful option fields:
 
 ```js

package/.skills/tc-generator/reference/runtime-extensions.md

@@ -1,6 +1,8 @@
 # TemplateCore Runtime Extensions
 
-Use this reference when generating business code that needs persistence, Dashboard customization, or frontend helper components.
+Use this reference when generating consumer business code that needs persistence, Dashboard customization, or frontend helper components.
+
+This repository is the `@_tc/template-core` npm package source. Paths such as `app/extends/*` and `frontend/extended/*` are consumer-app paths under that app's `baseDir`, not package-source paths, unless the task is explicitly about this repository's demo, docs, or framework implementation.
 
 ## Default DB
 
@@ -10,7 +12,7 @@ Use this reference when generating business code that needs persistence, Dashboa
 .template-core/template-core.sqlite
 ```
 
-The default path is relative to the business project `baseDir`. Configure it in `config/config.default.js`:
+The default path is relative to the consumer app `baseDir`. Configure it in `config/config.default.js`:
 
 ```js
 module.exports = {
@@ -179,7 +181,7 @@ Keep header content compact; the default header already owns brand, title, and m
 
 ## Server Router Guard
 
-Use `app/router-guard.js` or `app/router-guard.ts` in the generated business project when unmatched server paths need custom fallback behavior. The file lives directly under the business `app/` directory.
+Use `app/router-guard.js` or `app/router-guard.ts` in the generated consumer app when unmatched server paths need custom fallback behavior. The file lives directly under the consumer app's `app/` directory.
 
 ```js
 module.exports = (app) => (ctx) => {
@@ -222,14 +224,14 @@ Use `frontend/extended/dash/routeGuard.ts` when the built-in Dashboard needs a o
 ```ts
 import type { DashRouteGuard } from '@_tc/template-core/fe'
 
-const dashRouteGuard: DashRouteGuard = ({ isLoggedIn }) => {
-  if (!isLoggedIn) return '/login'
+const dashRouteGuard: DashRouteGuard = ({ isLoggedIn, isSSR }) => {
+  if (!isLoggedIn) return isSSR ? '/login?from=ssr' : '/login'
 }
 
 export default dashRouteGuard
 ```
 
-Return a login URL string when the framework should jump with `window.location.href`; the login page does not need to be inside Dash routes. `DashRouteGuardResult` is `string | undefined`, and `undefined` also interrupts the built-in Dashboard redirect, including the implicit return from a logged-in branch.
+Return a login URL string when the framework should jump with `window.location.href`; the login page does not need to be inside Dash routes. `DashRouteGuardContext` includes `renderMode: 'csr' | 'ssr'` and `isSSR` for render-mode-specific redirects. `DashRouteGuardResult` is `string | undefined`, and `undefined` also interrupts the built-in Dashboard redirect, including the implicit return from a logged-in branch.
 
 ## Frontend Helpers
 
@@ -313,7 +315,7 @@ cover: {
 }
 ```
 
-For project-specific renderers, create `frontend/extended/SchemaPage/SchemaTable/data.ts` and default-export a component map typed as `SchemaTableRenderComponentsMap` from `@_tc/template-core/fe`. Extend `SchemaTableNamespace.RenderComponentPropsMap` from `@_tc/template-core/model` when TypeScript model config should know the renderer props.
+For project-specific renderers, create `frontend/extended/SchemaPage/SchemaTable/data.ts` and default-export a component map typed as `SchemaTableRenderComponentsMap` from `@_tc/template-core/fe`. Extend `SchemaTableNamespace.RenderComponentPropsMap` from `@_tc/template-core/models` when TypeScript model config should know the renderer props.
 
 ## SchemaPage CallCom Extensions