pasika 0.1.1 → 0.1.6

package/docs/code-organization-guide/references/application-architecture-reference.md

@@ -0,0 +1,149 @@
+# Application Architecture Reference
+
+Use this reference to look up the canonical shape of the repository's `src/` tree and its Layer Model.
+
+## Layer Model
+
+This section describes the repository's five layers and their dependency direction. Use it to decide where a component or support file belongs and which layers it can import from.
+
+| Layer          | Path                      | Permitted contents                                                                                                                                                                     | Imports from                         |
+| -------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `app`          | `src/app/`                | [Next.js App Router routing files](https://nextjs.org/docs/app/getting-started/project-structure#routing-files), [metadata assets](https://nextjs.org/docs/app/getting-started/project-structure#metadata-file-conventions), and [styles required by routing files](https://nextjs.org/docs/app/getting-started/css) | compositions, features, shared, root |
+| `compositions` | `src/compositions/`       | Components and support files (`hooks/`, `types/`, `schemas/`, `constants/`, `utils/`)                                                                                                  | compositions, features, shared, root |
+| `features`     | `src/features/<feature>/` | Components and support files (`hooks/`, `types/`, `schemas/`, `constants/`, `utils/`). `src/features/` itself holds feature folders only — never components or support folders         | same feature, shared, root           |
+| `shared`       | `src/shared/`             | Components and support files (`hooks/`, `types/`, `schemas/`, `constants/`, `utils/`)                                                                                                  | shared, root                         |
+| `root`         | `src/`                    | App-wide support folders: `hooks/`, `types/`, `schemas/`, `constants/`, `utils/`, `config/`, and `locales/`                                                                          | root |
+
+## Closest Common Folder (CCF)
+
+The CCF determines the placement of components, hooks, types, schemas, constants, and utilities. It is the closest folder shared by the files under `src/` that use the item.
+
+```text
+src/features/payments/payment-card.tsx
+src/features/payments/payment-history.tsx
+└─ both import StatusBadge
+
+CCF: src/features/payments/
+Location: src/features/payments/status-badge.tsx
+```
+
+For components, imports from `src/app/` and configuration modules do not affect the CCF. A component used by `src/app/` and a feature therefore stays with the feature.
+
+```text
+src/app/products/page.tsx                ─┐
+src/features/products/product-card.tsx   ─┴─ imports ProductPrice
+
+CCF and location: src/features/products/product-price.tsx
+```
+
+A component with no consumers outside `src/app/` or configuration modules stays in the feature it represents or supports. When no existing feature applies, it creates a feature folder.
+
+```text
+src/app/search/page.tsx  → SearchForm  → src/features/search/search-form.tsx
+
+src/app/account/page.tsx ─┐
+src/app/orders/page.tsx  ─┴→ AccountNav → src/features/account/account-nav.tsx
+```
+
+When a component has consumers both inside and outside `src/compositions/`, only the consumers outside `src/compositions/` count. When all consumers are in `src/compositions/`, that folder counts.
+
+```text
+src/compositions/checkout.tsx             ─┐
+src/features/payments/payment-summary.tsx ─┴→ Total → src/features/payments/total.tsx
+
+src/compositions/checkout.tsx ─┐
+src/compositions/receipt.tsx  ─┴→ Total → src/compositions/total.tsx
+```
+
+A component stays at a nested component folder, feature folder, `src/compositions/`, or `src/shared/`. A CCF of `src/features/` places it in `src/shared/`.
+
+```text
+src/features/payments/payment-card.tsx ─┐
+src/features/orders/order-card.tsx     ─┴→ StatusBadge → src/shared/status-badge.tsx
+```
+
+For a support file imported by a file under `src/app/`, use the matching root support folder, such as `src/hooks/` or `src/utils/`. Otherwise, the CCF passes through a support folder to its parent folder, and the file lives in the matching support folder directly below that parent.
+
+```text
+src/app/products/page.tsx                    → useSearch    → src/hooks/use-search.ts
+src/features/payments/hooks/use-payment.ts   → formatAmount → src/features/payments/utils/format-amount.ts
+src/features/payments/payment-card.tsx       ─┐
+src/features/orders/order-card.tsx           ─┴→ formatDate → src/utils/format-date.ts
+```
+
+## Application Structure
+
+This tree shows the canonical directory layout and naming conventions for files and folders inside `src/`. It is included so readers can verify their structure matches the project standard at a glance.
+
+```
+src/
+├── app/                                   # Next.js framework-convention files, assets, and route styles
+├── compositions/                          # Components stay flat siblings by default
+│   ├── <ComponentA>.tsx                   # Smart component (PascalCase-named)
+│   ├── <component-b>.tsx                  # Dumb component (kebab-case-named)
+│   ├── <component-part>.tsx               # Dumb component — shared by A and B, so it stays flat too
+│   ├── <NestedComponent>/                 # Smart (PascalCase-named) — or kebab-case-named for dumb; nested only once it gains exclusive children
+│   │   ├── index.ts                       # Named-re-exports only the nested parent
+│   │   ├── <NestedComponent>.tsx          # Smart (PascalCase-named) — or kebab-case-named for dumb
+│   │   ├── <nested-part>.tsx              # Exclusive child — not in index.ts
+│   │   ├── hooks/                         # Nested-scoped support folders
+│   │   ├── types/
+│   │   ├── schemas/
+│   │   ├── constants/
+│   │   └── utils/
+│   ├── hooks/                             # Composition-scoped custom hooks
+│   ├── types/                             # Composition-scoped TypeScript types
+│   ├── schemas/                           # Composition-scoped validation schemas
+│   ├── constants/                         # Composition-scoped constants
+│   └── utils/                             # Composition-scoped pure functions
+├── features/                              # Feature folders only — no components, no support folders here
+│   └── <feature>/                         # One folder per feature — a feature can hold several components
+│       ├── <ComponentA>.tsx               # Smart component (PascalCase-named)
+│       ├── <component-b>.tsx              # Dumb component (kebab-case-named)
+│       ├── <component-part>.tsx           # Dumb component — shared by A and B, so it stays flat too
+│       ├── <NestedComponent>/             # Smart (PascalCase-named) — or kebab-case-named for dumb; nested only once it gains exclusive children
+│       │   ├── index.ts                   # Named-re-exports only the nested parent
+│       │   ├── <NestedComponent>.tsx      # Smart (PascalCase-named) — or kebab-case-named for dumb
+│       │   ├── <nested-part>.tsx          # Exclusive child — not in index.ts
+│       │   ├── hooks/                     # Nested-scoped support folders
+│       │   ├── types/
+│       │   ├── schemas/
+│       │   ├── constants/
+│       │   └── utils/
+│       ├── hooks/                         # Feature-scoped custom hooks
+│       ├── types/                         # Feature-scoped TypeScript types
+│       ├── schemas/                       # Feature-scoped validation schemas
+│       ├── constants/                     # Feature-scoped constants
+│       └── utils/                         # Feature-scoped pure functions
+├── shared/                                # Components stay flat siblings by default
+│   ├── <ComponentA>.tsx                   # Smart component (PascalCase-named)
+│   ├── <component-b>.tsx                  # Dumb component (kebab-case-named)
+│   ├── <component-part>.tsx               # Dumb component — shared by A and B, so it stays flat too
+│   ├── <NestedComponent>/                 # Smart (PascalCase-named) — or kebab-case-named for dumb; nested only once it gains exclusive children
+│   │   ├── index.ts                       # Named-re-exports only the nested parent
+│   │   ├── <NestedComponent>.tsx          # Smart (PascalCase-named) — or kebab-case-named for dumb
+│   │   ├── <nested-part>.tsx              # Exclusive child — not in index.ts
+│   │   ├── hooks/                         # Nested-scoped support folders
+│   │   ├── types/
+│   │   ├── schemas/
+│   │   ├── constants/
+│   │   └── utils/
+│   ├── hooks/                             # Shared-scoped custom hooks
+│   ├── types/                             # Shared-scoped TypeScript types
+│   ├── schemas/                           # Shared-scoped validation schemas
+│   ├── constants/                         # Shared-scoped constants
+│   └── utils/                             # Shared-scoped pure functions
+├── hooks/                                 # App-wide custom hooks
+├── types/                                 # App-wide TypeScript types
+├── schemas/                               # App-wide validation schemas
+├── constants/                             # App-wide constants
+├── utils/                                 # App-wide pure functions
+├── config/                                # Configuration modules that centralize application behavior
+│   └── <config-name>/                     # One folder per configuration module
+│       ├── index.ts                       # Configuration-module entry point
+│       ├── types/                         # Config-only TypeScript types
+│       ├── schemas/                       # Config-only validation schemas
+│       └── utils/                         # Config-only pure functions
+└── locales/                               # App-wide locale strings
+    └── index.ts                           # Single locale-registration file
+```

package/docs/code-organization-guide/rules/component-placement-rule.md

@@ -0,0 +1,119 @@
+# Component Placement Rule
+
+Without clear placement, it is hard to tell where a component belongs and reuse can create tangled dependencies. This rule gives each component a specific place in the application structure.
+
+- A component that imports from two or more feature folders MUST live in `src/compositions/` and is, by definition, a composition.
+- A component with no consumers outside `src/app/` or configuration modules, and that does not import from two or more feature folders, MUST live in the feature folder it represents or supports. If no existing feature applies, it MUST introduce a new feature folder.
+- A component with at least one consumer outside `src/app/` and configuration modules MUST live in its CCF, calculated without imports from `src/app/` or configuration modules.
+- When calculating a component's CCF, consumers under `src/compositions/` MUST count only when no consumer is outside `src/compositions/`.
+- A component whose CCF is `src/features/` MUST live in `src/shared/`.
+- `src/app/` MUST contain [Next.js App Router framework-convention files and assets](https://nextjs.org/docs/app/getting-started/project-structure#routing-files), plus styles required by routing files, but MUST NOT contain ordinary components or support folders.
+## Incorrect — Cross-Feature Component Duplicated
+
+```text
+src/features/
+├── donation/
+│   ├── DonationCard.tsx
+│   └── status-badge.tsx
+└── stream/
+    ├── StreamCard.tsx
+    └── status-badge.tsx
+```
+
+Why: two feature folders contain duplicate copies because neither feature may import from the other.
+
+## Correct — Cross-Feature Component in `src/shared/`
+
+```text
+src/
+├── features/
+│   ├── donation/
+│   │   └── DonationCard.tsx
+│   └── stream/
+│       └── StreamCard.tsx
+└── shared/
+    └── status-badge.tsx
+```
+
+Why: the component's CCF is `src/features/`, so it lives in `src/shared/`.
+
+## Incorrect — Multi-Feature Composition Inside One Feature
+
+```tsx
+// src/features/billing/billing-aggregate-view.tsx
+import { BillingPanel } from "./BillingPanel";
+import { HomeBanner } from "@/features/home/HomeBanner";
+```
+
+Why: the component imports from two feature folders, so it cannot live in either feature folder.
+
+## Correct — Multi-Feature Component in `src/compositions/`
+
+```tsx
+// src/compositions/billing-aggregate-view.tsx
+import { BillingPanel } from "@/features/billing/BillingPanel";
+import { HomeBanner } from "@/features/home/HomeBanner";
+```
+
+Why: the component imports from two feature folders, so it lives in `src/compositions/`.
+
+## Incorrect — Ordinary Component Under `src/app/`
+
+```text
+src/app/contact/
+├── _components/
+│   └── contact-page-content.tsx
+└── page.tsx
+```
+
+Why: the route folder contains ordinary component structure even though `src/app/` is reserved for framework-convention files, assets, and styles.
+
+## Correct — `src/app/` Imports a Page Composition
+
+```text
+src/
+├── app/contact/
+│   └── page.tsx
+├── compositions/
+│   └── contact-page-content.tsx
+└── features/
+    ├── contact/
+    │   └── contact-information.tsx
+    └── location/
+        └── office-location.tsx
+```
+
+```tsx
+// src/compositions/contact-page-content.tsx
+import { ContactInformation } from "@/features/contact/contact-information";
+import { OfficeLocation } from "@/features/location/office-location";
+import { locales } from "@/locales";
+
+export function ContactPageContent(): React.JSX.Element {
+  return (
+    <main>
+      <header>
+        <h1>{locales.contactPageTitle}</h1>
+        <p>{locales.contactPageDescription}</p>
+      </header>
+      <section>
+        <h2>{locales.contactInformationHeading}</h2>
+        <ContactInformation />
+      </section>
+      <section>
+        <h2>{locales.officeLocationHeading}</h2>
+        <OfficeLocation />
+      </section>
+    </main>
+  );
+}
+
+// src/app/contact/page.tsx
+import { ContactPageContent } from "@/compositions/contact-page-content";
+
+export default function Page(): React.JSX.Element {
+  return <ContactPageContent />;
+}
+```
+
+Why: `src/app/` contains the routing file while the composition provides the contact page layout and combines components from two feature folders.

package/docs/code-organization-guide/rules/configuration-rule.md

@@ -0,0 +1,42 @@
+# Configuration Rule
+
+Configuration modules centralize values that control application behavior. This rule keeps each module and the files that only support it together in `src/config/`.
+
+- A configuration module is an app-wide module that selects or parameterizes application behavior.
+- All configuration modules MUST live in `src/config/`.
+- A configuration module MUST be one `src/config/<config-name>/` folder with `index.ts` as its entry point.
+- A type, schema, or utility used only to implement one configuration module MUST be extracted even with one consumer.
+- An extracted configuration type, schema, or utility MUST live in its matching dedicated folder under `src/config/<config-name>/`.
+- An extracted configuration type, schema, or utility MUST move to its matching root support folder when a consumer outside its configuration module imports it.
+
+## Incorrect — Supporting Schema Outside Its Config Folder
+
+```text
+src/config/
+├── home-feed/
+│   └── index.ts
+└── home-feed-schema.ts
+```
+
+Why: the schema sits outside the `home-feed/` configuration folder.
+
+## Correct — Configuration Module with Its Supporting Schema
+
+```text
+src/config/
+└── home-feed/
+    ├── index.ts
+    └── schemas/
+        └── index.ts
+```
+
+```ts
+// src/config/home-feed/index.ts
+import { homeFeedConfigSchema } from "./schemas";
+
+export const homeFeedConfig = homeFeedConfigSchema.parse({
+  freshVideoMaxAgeDays: 7,
+});
+```
+
+Why: the configuration module and its supporting schema are grouped in the same configuration folder.

package/docs/code-organization-guide/rules/constants-rule.md

@@ -0,0 +1,74 @@
+# Constants Rule
+
+Duplicated constants are hard to keep in sync, while extracting every single-use value creates unnecessary files. This rule keeps reused constants in one file and leaves single-use values close to their consumer.
+
+- A value MUST remain in its declaring component or file until another file imports it independently; it MUST then be extracted as a constant.
+- Extracted constants MUST live in a `constants/` folder at the closest common folder (CCF) of their consumers.
+- Consumers MUST import an extracted constant through the `index.ts` in that constant's `constants/` folder.
+- A `constants/` folder MUST either define its constants directly in `index.ts` or group related constants in kebab-case files that `index.ts` named-re-exports.
+- When a constant's CCF is `src/features/`, it MUST move to `src/constants/`.
+- A constant MAY live in `src/config/<module>/` instead of a `constants/` folder when a developer determines that it configures application behavior and is best understood alongside the configuration that parameterizes it, even when consumers exist outside the config module.
+
+## Incorrect — Constant Imported Without `constants/index.ts`
+
+```ts
+// src/features/billing/constants/max-retries.ts
+export const maxRetries = 3;
+```
+
+```ts
+// src/features/billing/hooks/use-retry-payment.ts
+import { maxRetries } from "../constants/max-retries";
+```
+
+Why: the consumer bypasses the feature's `constants/index.ts`.
+
+## Correct — Grouped Constants Re-Exported from `constants/index.ts`
+
+```ts
+// src/features/billing/constants/retry.ts
+export const maxRetries = 3;
+export const retryDelayMs = 1_000;
+
+// src/features/billing/constants/index.ts
+export { maxRetries, retryDelayMs } from "./retry";
+```
+
+```ts
+// src/features/billing/hooks/use-retry-payment.ts
+import { maxRetries } from "../constants";
+```
+
+Why: the constants are available through the feature's `constants/index.ts`.
+
+## Incorrect — Feature and Composition Constant Kept in a Feature
+
+```ts
+// src/features/billing/constants/index.ts
+export const paymentRetryDelayMs = 1_000;
+
+// src/features/billing/hooks/use-retry-payment.ts
+import { paymentRetryDelayMs } from "../constants";
+
+// src/compositions/BillingDashboard.tsx
+import { paymentRetryDelayMs } from "@/features/billing/constants";
+```
+
+Why: the feature and composition have `src/` as their CCF, but the constant remains in the billing feature.
+
+## Correct — Feature and Composition Constant in `src/constants/`
+
+```ts
+// src/constants/index.ts
+export const paymentRetryDelayMs = 1_000;
+```
+
+```tsx
+// src/features/billing/hooks/use-retry-payment.ts
+import { paymentRetryDelayMs } from "@/constants";
+
+// src/compositions/BillingDashboard.tsx
+import { paymentRetryDelayMs } from "@/constants";
+```
+
+Why: the feature and composition have `src/` as their CCF, so the constant lives in `src/constants/`.

package/docs/code-organization-guide/rules/exports-and-imports-rule.md

@@ -0,0 +1,84 @@
+# Exports and Imports Rule
+
+Without consistent exports, import paths, and layer boundaries, it is harder to tell what a file contains and which files may depend on it. This rule gives each file a predictable export style and keeps imports consistent with the application structure.
+
+- A file that exports values MUST use named exports unless a framework or third-party package requires a different export style for that file.
+- Imports MUST use relative paths for the same folder, a direct subfolder, or one folder up.
+- Imports MUST use the `@/*` alias for anything beyond one folder up.
+- A file under `src/compositions/` MUST NOT import from `src/app/`.
+- A file in a feature folder MUST NOT import from another feature folder, `src/compositions/`, or `src/app/`.
+- A file under `src/shared/` MUST NOT import from `src/app/`, `src/compositions/`, or a feature folder.
+- A file in the `root` layer MUST NOT import from `src/app/`, `src/compositions/`, a feature folder, or `src/shared/`.
+- A configuration module MUST import only from root support folders and its own files.
+## Incorrect — Single-Export Utility Uses a Default Export
+
+```ts
+// src/utils/format-duration.ts
+export default function formatDuration(seconds: number): string {
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return `${minutes}:${String(remainder).padStart(2, "0")}`;
+}
+```
+
+Why: files use named exports even when they expose one item.
+
+## Correct — Single-Export Utility Uses a Named Export
+
+```ts
+// src/utils/format-duration.ts
+export function formatDuration(seconds: number): string {
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return `${minutes}:${String(remainder).padStart(2, "0")}`;
+}
+```
+
+Why: the utility uses the same named-export form as every other file that does not have a package-required export contract.
+
+## Incorrect — Deep Relative Path
+
+```ts
+// src/features/stream/StreamBoard/schedule.ts
+import { debounce } from "../../../utils/debounce";
+```
+
+Why: reaching more than one folder up hides the cross-scope dependency in relative path traversal.
+
+## Correct — Alias Across Scopes and Relative Paths Nearby
+
+```ts
+// src/features/stream/StreamBoard/schedule.ts
+import { debounce } from "@/utils/debounce";
+import { formatSlot } from "./utils/format-slot";
+import { type StreamSlot } from "./types";
+import { buildSchedule } from "../schedule-builder";
+```
+
+Why: the alias identifies the distant dependency while nearby files keep short relative paths.
+
+## Incorrect — Next.js Page Uses a Named Export
+
+```tsx
+// src/app/contact/page.tsx
+import { locales } from "@/locales";
+
+export function Page(): React.JSX.Element {
+  return <main>{locales.contactUs}</main>;
+}
+```
+
+Why: Next.js requires a `page.tsx` file to default-export its page component.
+
+## Correct — Next.js Page Uses a Default Export
+
+```tsx
+// src/app/contact/page.tsx
+import { locales } from "@/locales";
+
+export default function Page(): React.JSX.Element {
+  return <main>{locales.contactUs}</main>;
+}
+```
+
+Why: the page follows the export contract Next.js requires.

package/docs/code-organization-guide/rules/folder-nesting-rule.md

@@ -0,0 +1,82 @@
+# Folder Nesting Rule
+
+Without nesting, exclusive children can look reusable and their relationship to the parent is easy to miss in review. This rule groups them with their parent and keeps them out of the folder's public API.
+
+- An exclusive child component is imported only by its parent component. A component MUST stay flat until it has one or more exclusive child components, then MUST be nested in a folder with the same name.
+- A component MUST NOT be nested only because it has support files.
+- A nested component's support files MUST live in its folder.
+- The nested folder's `index.ts` MUST named-re-export the nested component and MUST NOT re-export its exclusive children.
+
+## Incorrect — Exclusive Children Kept Flat
+
+```text
+src/features/blog/
+  BlogPage.tsx                # owns exclusive children
+  blog-header.tsx             # exclusive child — no sibling needs it
+  blog-footer.tsx             # exclusive child — no sibling needs it
+  hooks/
+    use-blog-filter.ts        # used only by BlogPage
+```
+
+Why: `BlogPage` owns children that no sibling uses, but all three files sit as flat siblings. Nothing in the tree shows that `blog-header.tsx` and `blog-footer.tsx` belong to `BlogPage` rather than to any other component in the folder.
+
+## Correct — Exclusive Children Nested
+
+```text
+src/features/blog/
+  BlogPage/
+    index.ts                  # re-exports only BlogPage.tsx
+    BlogPage.tsx
+    blog-header.tsx           # not re-exported from index.ts
+    blog-footer.tsx           # not re-exported from index.ts
+    hooks/
+      use-blog-filter.ts
+```
+
+Why: nesting `BlogPage` into `BlogPage/` makes the parent–child relationship visible in the filesystem, lets the children stay scoped to their concrete consumer, and gives the folder a barrel that re-exports only the nested component.
+
+## Incorrect — Support Files Cause Unnecessary Nesting
+
+```text
+src/features/blog/
+  BlogPage/
+    index.ts
+    BlogPage.tsx
+    hooks/
+      use-blog-filter.ts
+```
+
+Why: support files alone do not make `BlogPage` a nested component.
+
+## Correct — Support Files Keep a Component Flat
+
+```text
+src/features/blog/
+  BlogPage.tsx
+  hooks/
+    use-blog-filter.ts
+```
+
+Why: without exclusive children, `BlogPage` stays flat and its support files remain at the feature scope.
+
+## Incorrect — Exclusive Child Re-Exported
+
+```ts
+// src/features/blog/BlogPage/index.ts
+export { BlogPage } from "./BlogPage";
+export { BlogHeader } from "./blog-header";
+```
+
+Why: the barrel re-exports the child as well as the nested component, so outside consumers can import `blog-header.tsx` through `index.ts` and the child stops being exclusive to `BlogPage`.
+
+## Correct — Only the Nested Component Re-Exported
+
+```tsx
+// src/features/blog/BlogPage/index.ts
+export { BlogPage } from "./BlogPage";
+
+// src/features/blog/BlogPage/BlogPage.tsx
+import { BlogHeader } from "./blog-header";
+```
+
+Why: the barrel exposes only the nested component, so it does not expose the child.