@starci/hfs 4.9.6 → 4.9.9

package/templates/be/skeleton/src/modules/platform/http-security/rate-limit.guard.spec.ts

@@ -3,29 +3,34 @@ import type { ExecutionContext, Type } from "@nestjs/common"
 import type { Request } from "express"
 import { Reflector } from "@nestjs/core"
 import { Test } from "@nestjs/testing"
-import { FakeClock, mock } from "@starci/jest-preset"
+import { FakeClock, mock, mockEntityManager } from "@starci/jest-preset"
+import type { MockEntityManager } from "@starci/jest-preset"
 import { CLOCK } from "@modules/platform/clock"
+import { PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
 import { HttpSecurityErrorCode } from "./errors/http-security.error"
 import { HTTP_SECURITY_OPTIONS } from "./http-security.decorators"
 import type { HttpSecurityOptions } from "./http-security.options"
+import { HIT_RATE_WINDOW, PRUNE_RATE_WINDOWS } from "./persistence/rate-limit.sql"
 import { RateLimit, RateLimitGuard, RateTier } from "./rate-limit.guard"
 
 const AT = "2026-02-03T04:05:06.000Z"
+const RESET_AT = "2026-02-03T04:06:06.000Z"
 const options: HttpSecurityOptions = {
     allowedOrigins: [],
     rateLimit: { windowMs: 60_000, defaultLimit: 2, strictLimit: 1 },
     webhooks: {},
 }
 
-const build = async (clock: FakeClock, tier?: RateTier) => {
+const build = async (entityManager: MockEntityManager, tier?: RateTier) => {
     const reflector = mock<Reflector>()
     reflector.getAllAndOverride.mockReturnValue(tier)
     const moduleRef = await Test.createTestingModule({
         providers: [
             RateLimitGuard,
             { provide: Reflector, useValue: reflector },
-            { provide: CLOCK, useValue: clock },
+            { provide: CLOCK, useValue: new FakeClock(AT) },
             { provide: HTTP_SECURITY_OPTIONS, useValue: options },
+            { provide: PRIMARY_ENTITY_MANAGER, useValue: entityManager },
         ],
     }).compile()
     return { guard: moduleRef.get(RateLimitGuard), reflector }
@@ -33,79 +38,100 @@ const build = async (clock: FakeClock, tier?: RateTier) => {
 
 /** An execution context of one POST from `ip` on the door; the handler and the class carry the tier metadata. */
 const contextOf = (ip: string | undefined, handler = () => undefined, door: Type<unknown> = class Door {}) => {
-    let address = ip
     const http = mock<ReturnType<ExecutionContext["switchToHttp"]>>()
-    http.getRequest.mockImplementation(() => mock<Request>({ headers: {}, method: "POST", ip: address }))
+    http.getRequest.mockImplementation(() => mock<Request>({ headers: {}, method: "POST", ip }))
     const context = mock<ExecutionContext>()
     context.switchToHttp.mockReturnValue(http)
     context.getHandler.mockReturnValue(handler)
     context.getClass.mockReturnValue(door)
-    return { context, setIp: (value: string | undefined) => (address = value) }
+    return context
 }
 
 describe("RateLimit", () => {
     it("marks a door with the tier it declares, and the guard counts it under that tier's limit", async () => {
         class Door {}
         RateLimit(RateTier.Strict)(Door)
-        const { guard, reflector } = await build(new FakeClock(AT), RateTier.Strict)
+        const entityManager = mockEntityManager({ query: [HIT_RATE_WINDOW, [{ hits: 2 }]] })
+        const { guard, reflector } = await build(entityManager, RateTier.Strict)
         const handler = () => undefined
-        const { context } = contextOf("127.0.0.1", handler, Door)
 
         expect(Reflect.getMetadata("platform.http-security.rate-tier", Door)).toBe(RateTier.Strict)
-        expect(guard.canActivate(context)).toBe(true)
-        expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.RateLimited)
+        await expect(guard.canActivate(contextOf("127.0.0.1", handler, Door))).rejects.toMatchObject({
+            code: HttpSecurityErrorCode.RateLimited,
+        })
         expect(reflector.getAllAndOverride).toHaveBeenCalledWith("platform.http-security.rate-tier", [handler, Door])
+        expect(entityManager.query).toHaveBeenCalledWith(HIT_RATE_WINDOW, [
+            "strict:127.0.0.1",
+            new Date(AT),
+            new Date(RESET_AT),
+        ])
     })
 })
 
 describe("RateLimitGuard", () => {
-    it("counts an unmarked door under the default limit", async () => {
-        const { guard } = await build(new FakeClock(AT))
-        const { context } = contextOf("127.0.0.1")
-
-        expect(guard.canActivate(context)).toBe(true)
-        expect(guard.canActivate(context)).toBe(true)
-        expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.RateLimited)
+    it("admits a caller under the default limit of an unmarked door, counting in the shared window", async () => {
+        const entityManager = mockEntityManager({ query: [HIT_RATE_WINDOW, [{ hits: 2 }]] })
+        const { guard } = await build(entityManager)
+
+        await expect(guard.canActivate(contextOf("127.0.0.1"))).resolves.toBe(true)
+        expect(entityManager.query).toHaveBeenCalledWith(HIT_RATE_WINDOW, [
+            "default:127.0.0.1",
+            new Date(AT),
+            new Date(RESET_AT),
+        ])
     })
 
-    it("opens a fresh window for a caller whose bucket expired", async () => {
-        const clock = new FakeClock(AT)
-        const { guard } = await build(clock)
-        const { context } = contextOf("127.0.0.1")
-
-        guard.canActivate(context)
-        guard.canActivate(context)
-        expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.RateLimited)
+    it("refuses a caller whose shared window is over the default limit", async () => {
+        const { guard } = await build(mockEntityManager({ query: [HIT_RATE_WINDOW, [{ hits: 3 }]] }))
 
-        clock.advance(60_001)
+        await expect(guard.canActivate(contextOf("127.0.0.1"))).rejects.toMatchObject({
+            code: HttpSecurityErrorCode.RateLimited,
+        })
+    })
 
-        expect(guard.canActivate(context)).toBe(true)
+    it("prunes the expired windows when a hit opens a fresh one", async () => {
+        const entityManager = mockEntityManager({
+            query: [
+                [HIT_RATE_WINDOW, [{ hits: 1 }]],
+                [PRUNE_RATE_WINDOWS, []],
+            ],
+        })
+        const { guard } = await build(entityManager)
+
+        await expect(guard.canActivate(contextOf("127.0.0.1"))).resolves.toBe(true)
+        expect(entityManager.query).toHaveBeenCalledWith(PRUNE_RATE_WINDOWS, [new Date(AT)])
     })
 
-    it("counts a request without an address under the unknown bucket", async () => {
-        const { guard } = await build(new FakeClock(AT))
-        const { context } = contextOf(undefined)
+    it("counts a request without an address under the unknown key", async () => {
+        const entityManager = mockEntityManager({ query: [HIT_RATE_WINDOW, [{ hits: 2 }]] })
+        const { guard } = await build(entityManager)
 
-        guard.canActivate(context)
-        guard.canActivate(context)
-        expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.RateLimited)
+        await expect(guard.canActivate(contextOf(undefined))).resolves.toBe(true)
+        expect(entityManager.query).toHaveBeenCalledWith(HIT_RATE_WINDOW, [
+            "default:unknown",
+            new Date(AT),
+            new Date(RESET_AT),
+        ])
     })
 
-    it("prunes the expired buckets when the map outgrows the bucket cap", async () => {
-        const clock = new FakeClock(AT)
-        const { guard } = await build(clock)
-        const { context, setIp } = contextOf("0.0.0.0")
+    it("bounds the window key to the length the table stores", async () => {
+        const entityManager = mockEntityManager({ query: [HIT_RATE_WINDOW, [{ hits: 2 }]] })
+        const { guard } = await build(entityManager)
 
-        for (let index = 0; index <= 10_000; index += 1) {
-            setIp(`10.${(index >> 16) % 256}.${(index >> 8) % 256}.${index % 256}`)
-            guard.canActivate(context)
-        }
+        await guard.canActivate(contextOf("f".repeat(300)))
+
+        expect(entityManager.query).toHaveBeenCalledWith(HIT_RATE_WINDOW, [
+            `default:${"f".repeat(120)}`,
+            new Date(AT),
+            new Date(RESET_AT),
+        ])
+    })
 
-        clock.advance(60_001)
-        setIp("127.0.0.1")
+    it("refuses the request when the store answers no window", async () => {
+        const { guard } = await build(mockEntityManager({ query: [HIT_RATE_WINDOW, []] }))
 
-        expect(guard.canActivate(context)).toBe(true)
-        expect(guard.canActivate(context)).toBe(true)
-        expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.RateLimited)
+        await expect(guard.canActivate(contextOf("127.0.0.1"))).rejects.toMatchObject({
+            code: HttpSecurityErrorCode.RateLimited,
+        })
     })
 })

package/templates/be/skeleton/src/modules/platform/http-security/rate-limit.guard.ts

@@ -1,13 +1,17 @@
 import { Injectable, SetMetadata } from "@nestjs/common"
 import type { CanActivate, ExecutionContext } from "@nestjs/common"
 import type { Reflector } from "@nestjs/core"
+import type { EntityManager } from "typeorm"
 import { InjectClock } from "@modules/platform/clock"
 import type { Clock } from "@modules/platform/clock"
 import { InjectReflector } from "@modules/platform/composition"
+import { InjectPrimaryEntityManager } from "@modules/platform/database"
 import { HttpSecurityError, HttpSecurityErrorCode } from "./errors/http-security.error"
 import { requestOf } from "./execution-request.mapper"
 import { InjectHttpSecurityOptions } from "./http-security.decorators"
 import type { HttpSecurityOptions } from "./http-security.options"
+import type { RateWindowRow } from "./persistence/rate-limit.rows"
+import { HIT_RATE_WINDOW, PRUNE_RATE_WINDOWS } from "./persistence/rate-limit.sql"
 
 /** The rate limit tiers of a door. */
 export enum RateTier {
@@ -18,29 +22,28 @@ export enum RateTier {
 }
 
 const RATE_TIER_KEY = "platform.http-security.rate-tier"
-const BUCKETS_MAX = 10_000
-
-interface Bucket {
-    count: number
-    resetAt: number
-}
+/** The longest window key the table stores: the tier, a colon and the caller address. */
+const KEY_MAX = 128
 
 /** Marks a door with a rate limit tier other than the default. */
 export const RateLimit = (tier: RateTier): ReturnType<typeof SetMetadata> => SetMetadata(RATE_TIER_KEY, tier)
 
 @Injectable()
-/** The first app guard: a fixed-window counter per caller address and tier, kept in process memory and stamped by the Clock. */
+/**
+ * The first app guard: a fixed-window counter per caller address and tier, stamped by the Clock and kept in the primary
+ * database, so every replica counts against the same window. A hit that opens a fresh window also prunes a bounded batch of
+ * expired windows.
+ */
 export class RateLimitGuard implements CanActivate {
-    private readonly buckets = new Map<string, Bucket>()
-
     constructor(
         @InjectReflector() private readonly reflector: Reflector,
         @InjectClock() private readonly clock: Clock,
         @InjectHttpSecurityOptions() private readonly options: HttpSecurityOptions,
+        @InjectPrimaryEntityManager() private readonly entityManager: EntityManager,
     ) {}
 
     /** Counts the request and refuses it when the caller is over the limit of the door tier. */
-    canActivate(context: ExecutionContext): boolean {
+    async canActivate(context: ExecutionContext): Promise<boolean> {
         const tier =
             this.reflector.getAllAndOverride<RateTier | undefined>(RATE_TIER_KEY, [
                 context.getHandler(),
@@ -48,21 +51,13 @@ export class RateLimitGuard implements CanActivate {
             ]) ?? RateTier.Default
         const limit =
             tier === RateTier.Strict ? this.options.rateLimit.strictLimit : this.options.rateLimit.defaultLimit
-        const now = this.clock.now().getTime()
-        const key = `${tier}:${requestOf(context).ip ?? "unknown"}`
-        const current = this.buckets.get(key)
-        const bucket =
-            current && current.resetAt > now ? current : { count: 0, resetAt: now + this.options.rateLimit.windowMs }
-        bucket.count += 1
-        this.buckets.set(key, bucket)
-        if (this.buckets.size > BUCKETS_MAX) this.prune(now)
-        if (bucket.count > limit) throw new HttpSecurityError({ code: HttpSecurityErrorCode.RateLimited })
+        const now = this.clock.now()
+        const key = `${tier}:${requestOf(context).ip ?? "unknown"}`.slice(0, KEY_MAX)
+        const resetAt = new Date(now.getTime() + this.options.rateLimit.windowMs)
+        const rows: Array<RateWindowRow> = await this.entityManager.query(HIT_RATE_WINDOW, [key, now, resetAt])
+        const hits = rows[0]?.hits ?? Number.POSITIVE_INFINITY
+        if (hits === 1) await this.entityManager.query(PRUNE_RATE_WINDOWS, [now])
+        if (hits > limit) throw new HttpSecurityError({ code: HttpSecurityErrorCode.RateLimited })
         return true
     }
-
-    private prune(now: number): void {
-        for (const [key, bucket] of this.buckets) {
-            if (bucket.resetAt <= now) this.buckets.delete(key)
-        }
-    }
 }

package/templates/be/skeleton-lite/src/modules/platform/database/errors/database.error.ts

@@ -5,11 +5,14 @@ import type { ErrorKind } from "@modules/platform/errors"
 export enum DatabaseErrorCode {
     /** A configured connection has no declared EntityManager injection token. */
     ConnectionUndeclared = "DATABASE_CONNECTION_UNDECLARED",
+    /** A dynamic SQL identifier was not on the names its caller allows. */
+    IdentifierRejected = "DATABASE_IDENTIFIER_REJECTED",
 }
 
 /** How each database code travels. */
 export const DATABASE_ERROR_KINDS: Record<DatabaseErrorCode, ErrorKind> = {
     [DatabaseErrorCode.ConnectionUndeclared]: "internal",
+    [DatabaseErrorCode.IdentifierRejected]: "internal",
 }
 
 /** The one error class of the database capability. */

package/templates/be/skeleton-lite/src/modules/platform/database/index.ts

@@ -1,7 +1,8 @@
 export { DatabaseModule } from "./database.module"
-export { DATABASE_PROBE, InjectDatabaseProbe } from "./primary.decorators"
+export { DATABASE_PROBE, InjectDatabaseProbe, InjectPrimaryEntityManager, PRIMARY_ENTITY_MANAGER } from "./primary.decorators"
 export { DatabaseProbeService } from "./database-probe.service"
 export type { DatabaseConnectionOptions } from "./database.options"
 export { PRIMARY_DATA_SOURCE } from "./database.port"
+export { sql } from "./database.sql"
 export { DATABASE_ERROR_KINDS } from "./errors/database.error"
 export { parsePrimaryDatabaseConfig } from "./primary.config"

package/templates/fe/skeleton/apps/app/src/features/pages/AppHomePage/component.tsx

@@ -1,4 +1,4 @@
-import { Heading } from "@starci/grammar/common"
+import { Page } from "@starci/grammar/common"
 import { SignInForm } from "@/components/blocks/SignInForm"
 import { SignOutButton } from "@/components/blocks/SignOutButton"
 
@@ -8,11 +8,13 @@ export type AppHomePageBaseProps = {
     readonly props: { readonly title: string }
 }
 
-/** Draw the front door of the product app: the sign-in form for a signed-out reader, the reader and sign-out once signed in. */
+/**
+ * Draw the front door of the product app as one Grammar Page (R325): the title heads the page band, and the body holds
+ * the sign-in form for a signed-out reader, the reader and sign-out once signed in.
+ */
 export const AppHomePageBase = (props: AppHomePageBaseProps) => (
-    <>
-        <Heading level={1}>{props.props.title}</Heading>
+    <Page header={{ title: props.props.title }}>
         <SignInForm />
         <SignOutButton />
-    </>
+    </Page>
 )

package/templates/fe/skeleton/apps/landing/src/features/pages/LandingPage/component.tsx

@@ -1,4 +1,4 @@
-import { Button, Heading, Text } from "@starci/grammar/common"
+import { Button, Page } from "@starci/grammar/common"
 
 /** Props for {@link LandingPageBase}. */
 export type LandingPageBaseProps = {
@@ -12,13 +12,14 @@ export type LandingPageBaseProps = {
     }
 }
 
-/** Draw the public front door: the welcome, one sentence about the product and the way into the product app. */
+/**
+ * Draw the public front door as one Grammar Page (R325): the welcome heads the band with one sentence about the product
+ * under it, and the body holds the way into the product app.
+ */
 export const LandingPageBase = (props: LandingPageBaseProps) => (
-    <>
-        <Heading level={1}>{props.props.title}</Heading>
-        <Text tone="muted">{props.props.lede}</Text>
+    <Page header={{ title: props.props.title, description: props.props.lede }}>
         <Button href={props.props.appHref} intent="commit">
             {props.props.openApp}
         </Button>
-    </>
+    </Page>
 )

package/templates/fe/skeleton-lite/apps/web/src/features/pages/AppHomePage/component.tsx

@@ -1,4 +1,4 @@
-import { Heading } from "@starci/grammar/common"
+import { Page } from "@starci/grammar/common"
 import { SignInForm } from "@/components/blocks/SignInForm"
 import { SignOutButton } from "@/components/blocks/SignOutButton"
 
@@ -7,11 +7,10 @@ export type AppHomePageBaseProps = {
     readonly props: { readonly title: string }
 }
 
-/** Draws the front door: the sign-in form for a signed-out reader, the reader and sign-out once signed in. */
+/** Draws the front door as one Grammar Page (R325): the title heads the band, the body the sign-in form or the reader and sign-out. */
 export const AppHomePageBase = (props: AppHomePageBaseProps) => (
-    <>
-        <Heading level={1}>{props.props.title}</Heading>
+    <Page header={{ title: props.props.title }}>
         <SignInForm />
         <SignOutButton />
-    </>
+    </Page>
 )

package/templates/fe/units/block/component.tsx.tpl

@@ -0,0 +1,35 @@
+import { SurfaceCard, Text } from "@starci/grammar/common"
+import { SlotView } from "{{slotViewFrom}}"
+import type { DataSlot, SlotLabels } from "@/modules/types"
+{{shapeDeclarations}}
+/** One read value as {{Name}} draws it. */
+export interface {{Name}}Item {
+    readonly id: string
+{{itemShapeMember}}}
+
+/** Copy, the one read and the retry the connected {{Name}} supplies; atoms only. */
+export interface {{Name}}BaseProps {
+{{shapeMember}}    readonly props: {
+        readonly title: string
+{{shapeLabelsMember}}        readonly item: DataSlot<{{Name}}Item>
+        readonly slotLabels: SlotLabels
+    }
+    readonly on: { readonly retry: () => void }
+}
+
+/** A value of the same shape as the read: the skeleton draws the ready tree from it{{placeholderShapeDoc}}. */
+export const {{NAME_UPPER}}_PLACEHOLDER: {{Name}}Item = { id: ""{{placeholderShape}} }
+{{shapeBody}}
+/** Draws {{Name}} from atoms: its read renders every status through SlotView, inside the unchanged surface. */
+export const {{Name}}Base = (props: {{Name}}BaseProps) => (
+    <SurfaceCard label={props.props.title}>
+        <SlotView
+            slot={props.props.item}
+            placeholder={{{NAME_UPPER}}_PLACEHOLDER}
+            labels={props.props.slotLabels}
+            onRetry={props.on.retry}
+        >
+            {(item, isSkeleton) => {{readyTree}}}
+        </SlotView>
+    </SurfaceCard>
+)

package/templates/fe/units/block/index.tsx.tpl

@@ -0,0 +1,29 @@
+"use client"
+
+import { useTranslations } from "next-intl"
+import { mapSlot, slotOfSwr, useSlotLabels } from "@/hooks/slot"
+import { useQuery{{Read}}Swr } from "@/hooks/swr"
+import { {{componentImports}} } from "./component"
+{{componentTypeImport}}
+/** Input of {{Name}}: the id of the value it reads. */
+type {{Name}}Props = {
+    readonly id: string
+}
+{{shapeOfHelper}}
+/** The connected {{Name}}: folds its one read into a slot, {{connectedDoc}}resolves every label and the retry, and renders its pure half. */
+export const {{Name}} = (props: {{Name}}Props) => {
+    const t = useTranslations("{{nameCamel}}")
+    const slotLabels = useSlotLabels()
+    const read = useQuery{{Read}}Swr(props.id)
+    const item = mapSlot(slotOfSwr(read), (value) => ({ id: value.id{{itemShapeMapped}} }))
+    return (
+        <{{Name}}Base
+{{shapeAttribute}}            props={{
+                title: t("title"),
+{{shapeLabelsResolved}}                item,
+                slotLabels: slotLabels(t("empty")),
+            }}
+            on={{ retry: () => void read.mutate() }}
+        />
+    )
+}

package/templates/fe/units/block/stories.tsx.tpl

@@ -0,0 +1,29 @@
+import type { Meta, StoryObj } from "@storybook/react-vite"
+import { {{Name}}Base } from "../../src/components/blocks/{{Name}}/component"
+import type { {{Name}}BaseProps } from "../../src/components/blocks/{{Name}}/component"
+import { loadingSlot } from "../../src/hooks/slot/slot.shared"
+
+/** The ready read every story draws: one value, settled. */
+const READY: {{Name}}BaseProps["props"] = {
+    title: "{{title}}",
+{{shapeLabelsFixture}}    item: { items: { id: "{{nameKebab}}-1"{{fixtureShape}} } },
+    slotLabels: { empty: "Nothing yet", forbidden: "Not allowed", error: "Could not load", retry: "Try again" },
+}
+
+/** The pure half of {{Name}} drawn from fixtures: {{storiesDoc}} and the loading twin of the first. */
+const meta = {
+    title: "{{Name}}",
+    component: {{Name}}Base,
+    args: { {{shapeArg}}props: READY, on: { retry: () => undefined } },
+} satisfies Meta<typeof {{Name}}Base>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+{{readyStories}}
+
+/** The loading twin of {{firstStory}}: the same tree drawn from the placeholder with every leaf resting. */
+export const {{firstStory}}Skeleton: Story = {
+    args: { {{shapeArg}}props: { ...READY, item: loadingSlot() } },
+    parameters: { dna: { pair: "{{firstStory}}", phase: "loading" } },
+}

package/templates/fe/units/branch/index.tsx.tpl

@@ -0,0 +1,23 @@
+import { useState } from "react"
+import type { ReactNode } from "react"
+import { Button } from "@starci/grammar/common"
+
+/** The resolved labels of the toggle and the content it shows; the branch owns only whether it is open. */
+type {{Name}}Props = {
+    readonly showLabel: string
+    readonly hideLabel: string
+    readonly children: ReactNode
+}
+
+/** Holds its intrinsic state alone (open or closed); it reads no data, resolves no copy and renders below a client block. */
+export const {{Name}} = (props: {{Name}}Props) => {
+    const [isOpen, setIsOpen] = useState(false)
+    return (
+        <>
+            <Button intent="neutral" onPress={() => setIsOpen((current) => !current)}>
+                {isOpen ? props.hideLabel : props.showLabel}
+            </Button>
+            {isOpen ? props.children : null}
+        </>
+    )
+}

package/templates/fe/units/composite/index.tsx.tpl

@@ -0,0 +1,18 @@
+import { Text } from "@starci/grammar/common"
+
+/** The resolved fields {{Name}} draws; its block resolves the copy and passes the waiting flag down. */
+type {{Name}}Props = {
+    readonly term: string
+    readonly value: string
+    readonly isSkeleton: boolean
+}
+
+/** A closed arrangement of Grammar parts: a term and its value, each resting as itself while its block waits. */
+export const {{Name}} = (props: {{Name}}Props) => (
+    <>
+        <Text tone="muted" isSkeleton={props.isSkeleton}>
+            {props.term}
+        </Text>
+        <Text isSkeleton={props.isSkeleton}>{props.value}</Text>
+    </>
+)

package/templates/fe/units/layout/index.tsx.tpl

@@ -0,0 +1,11 @@
+import type { ReactNode } from "react"
+import { PrimaryRailLayout } from "@starci/grammar/common"
+{{blockImports}}
+/** Framework-layout boundary input: the routed page of the {{segment}} segment and nothing else. */
+type {{Name}}Props = { readonly content: ReactNode }
+
+/**
+ * The {{segment}} segment's frame: Grammar's PrimaryRailLayout places the routed page and {{railDoc}}. A frame only places
+ * regions and never insets a page; the Page inside owns its inset and rhythm.
+ */
+export const {{Name}} = (props: {{Name}}Props) => {{frame}}

package/templates/fe/units/layout/route-layout.tsx.tpl

@@ -0,0 +1,9 @@
+import type { ReactNode } from "react"
+import { {{Name}} } from "@/features/layouts/{{Name}}"
+
+type LayoutProps = { readonly children: ReactNode }
+
+/** The {{segment}} segment's layout slot: it mounts {{Name}} around the routed page and nothing else. */
+const Layout = (props: LayoutProps) => <{{Name}} content={props.children} />
+
+export default Layout

package/templates/fe/units/leaf/index.tsx.tpl

@@ -0,0 +1,10 @@
+import { Badge } from "@starci/grammar/common"
+
+/** One resolved label and the waiting flag of the block that draws it. */
+type {{Name}}Props = {
+    readonly label: string
+    readonly isSkeleton: boolean
+}
+
+/** A fixed semantic unit over one Grammar leaf; it rests as itself by passing `isSkeleton` on. */
+export const {{Name}} = (props: {{Name}}Props) => <Badge isSkeleton={props.isSkeleton}>{props.label}</Badge>

package/templates/fe/units/overlay/component.tsx.tpl

@@ -0,0 +1,27 @@
+import { {{grammarImports}} } from "@starci/grammar/common"
+
+/** The copy, the open state and the actions the connected {{Name}} supplies; atoms only. */
+export interface {{Name}}BaseProps {
+    readonly props: {
+        readonly isOpen: boolean
+        readonly triggerLabel: string
+        readonly title: string
+{{labelMembers}}        readonly cancelLabel: string
+        readonly submitLabel: string
+    }
+    readonly on: {
+        readonly openChange: (isOpen: boolean) => void
+{{submitMember}}    }
+}
+
+/** {{doc}} */
+export const {{Name}}Base = (props: {{Name}}BaseProps) => (
+    <{{shell}}
+        isOpen={props.props.isOpen}
+        onOpenChange={props.on.openChange}
+        title={props.props.title}
+{{shellAttributes}}        trigger={<Button intent="neutral">{props.props.triggerLabel}</Button>}
+{{footer}}    >
+{{body}}
+    </{{shell}}>
+)

package/templates/fe/units/overlay/index.tsx.tpl

@@ -0,0 +1,23 @@
+"use client"
+
+import { useState } from "react"
+import { useTranslations } from "next-intl"
+import { {{Name}}Base } from "./component"
+
+/** The connected {{Name}}: owns whether it is open, resolves every label and renders its pure half. */
+export const {{Name}} = () => {
+    const t = useTranslations("{{nameCamel}}")
+    const [isOpen, setIsOpen] = useState(false)
+    return (
+        <{{Name}}Base
+            props={{
+                isOpen,
+                triggerLabel: t("open"),
+                title: t("title"),
+{{labelsResolved}}                cancelLabel: t("cancel"),
+                submitLabel: t("submit"),
+            }}
+            on={{ openChange: setIsOpen, {{submitHandler}} }}
+        />
+    )
+}

package/templates/fe/units/overlay/stories.tsx.tpl

@@ -0,0 +1,29 @@
+import type { Meta, StoryObj } from "@storybook/react-vite"
+import { {{Name}}Base } from "../../src/features/overlays/{{Name}}/component"
+import type { {{Name}}BaseProps } from "../../src/features/overlays/{{Name}}/component"
+
+/** The copy of the overlay. */
+const COPY: {{Name}}BaseProps["props"] = {
+    isOpen: false,
+    triggerLabel: "Open",
+    title: "{{title}}",
+{{labelsFixture}}    cancelLabel: "Cancel",
+    submitLabel: "Save",
+}
+
+/** The pure half of {{Name}}: closed behind its trigger, and open. */
+const meta = {
+    title: "{{Name}}",
+    component: {{Name}}Base,
+    args: { props: COPY, on: { openChange: () => undefined, {{submitFixture}} } },
+} satisfies Meta<typeof {{Name}}Base>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/** Closed: only its trigger shows. */
+export const Closed: Story = {}
+
+/** Open above the page. */
+export const Open: Story = { args: { props: { ...COPY, isOpen: true } } }