Compare commits

...

8 Commits

Author SHA1 Message Date
Amiram_se dcf99e6fa5 chore(skill): fixed-name fonts and an icon sprite versioned in its link
Fonts and symbol-defs.svg keep fixed names that no build step hashes,
served immutable from each app's public/. Fonts have no version; the
sprite is linked as symbol-defs.svg?v=<N>, and every sprite change
raises ICON_SPRITE_VERSION in the same commit. Documents
font-copy-plugin, fonts.css with root paths, CRITICAL_FONT_URL, and the
matching review and Definition of Done checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 19:01:39 +04:00
Amiram_se 1136e55ebf chore(skill): forbid hard-coded env values
No project hard-codes a value that changes between environments: no
literal address, key, ID or flag, no fallback, and no schema default.
Every env value comes from the .env of the app that serves it, and only
apps have .env files. Adds the rule to the env lib spec, the env flow,
the refactoring smells, and the Definition of Done.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 19:01:39 +04:00
Amiram_se 60b62d98db docs(decisions): fixed-name fonts and sprite versioned in its link
- 0009 and 0010 versioned the file names; both are now superseded.
- 0011: fonts keep fixed names with no version; a changed font ships
  under a new name.
- 0012: the sprite stays symbol-defs.svg, linked with ?v=<N>, written by
  icon-sprite-plugin and font-copy-plugin.
- 0007 and 0008 are marked superseded, and the index lists 0011 and 0012.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 19:00:46 +04:00
Amiram_se 86944adb97 feat(island,apps): serve fonts and icon sprite under fixed names
Replace the hashing asset plugin with two build-time plugins that never
rename their files, so an unchanged font or sprite stays in every
visitor's cache across deploys (0011, 0012):

- icon-sprite-plugin builds icons/*.svg with svgo into
  public/icons/symbol-defs.svg. The Icon atom links it as
  symbol-defs.svg?v=<ICON_SPRITE_VERSION>; the file's first line stamps
  its version, so dev warns when the sprite changes without a bump.
- font-copy-plugin copies island fonts/ byte for byte into public/fonts/
  and warns when a font changes under its old name.
- island fonts.css declares both Yekan Bakh faces with root paths and a
  fallback face; theme.css points font-sans and font-latin at them.
- Root layouts preload CRITICAL_FONT_URL. next/font is gone.
- Both apps serve /fonts and /icons as immutable.
- island env, the apps' island-env bootstrap, NEXT_PUBLIC_ISLAND_* and
  NEXT_PUBLIC_CDN_ORIGIN are removed; paths live in island constants.ts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 19:00:46 +04:00
Amiram_se dc229a3949 refactor(market,apps): share PageError from market screens
Both apps had their own copy of the page error boundary. It now lives
once in platforms/market/src/app/screens/organisms/page-error, and every
route group's error.tsx re-exports it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 19:00:28 +04:00
Amiram_se 0bee35290d refactor(island): move dialog to atoms, modal and sheet to molecules
Imports and the root index follow the new paths.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 19:00:28 +04:00
Amiram_se 605feabb40 chore: update skill 2026-10-05 13:27:31 +04:00
Amiram_se 79304d1009 chore: update skill 2026-10-05 12:48:39 +04:00
92 changed files with 623 additions and 539 deletions

View File

@ -19,11 +19,11 @@ How you work:
- Who uses it: the public, 1–20 million visitors a day (Amazon, eBay, Digikala). - Who uses it: the public, 1–20 million visitors a day (Amazon, eBay, Digikala).
- App: Next.js App Router, routes in `apps/<app>/src/app/`. - App: Next.js App Router, routes in `apps/<app>/src/app/`.
- Business logic: `platforms/<app>/`; the app stays thin. - Business logic: `platforms/<platform>/`, one per product and shared by its apps; each app stays thin.
- Server entry: every project except apps has `src/server.ts`. - Server entry: every project except apps has `src/server.ts`.
- Critical: a fresh server render per request with no server cache, web vitals, bundle and chunk size, and hydration and navigation speed. - Critical: a fresh server render per request with no server cache, web vitals, bundle and chunk size, and hydration and navigation speed.
Read the playbook before designing or writing code: [references/b2c-b2b.md](references/b2c-b2b.md). When the work changes what the user sees or what search engines read (a page, template, organism, form, copy, upload, image, font, or metadata), also read [references/ui-rules.md](references/ui-rules.md): UX, SEO, images, and fonts. Read the playbook before designing or writing code: [references/b2c-b2b.md](references/b2c-b2b.md). When the work changes what the user sees or what search engines read (a page, template, organism, form, copy, upload, image, font, icon, or metadata), also read [references/ui-rules.md](references/ui-rules.md): UX, SEO, images, fonts, and the icon sprite.
## 2. Stack ## 2. Stack
@ -39,10 +39,10 @@ Read the playbook before designing or writing code: [references/b2c-b2b.md](refe
| Server state | TanStack Query | Configured in `configs/react-query.ts`; query keys live in the repository's `constants.ts`; queries don't retry on their own, because the HTTP lib does, and a failed first load throws to its error boundary, where the user retries | | Server state | TanStack Query | Configured in `configs/react-query.ts`; query keys live in the repository's `constants.ts`; queries don't retry on their own, because the HTTP lib does, and a failed first load throws to its error boundary, where the user retries |
| Toasts | sonner | After every completed or failed action; never for reads | | Toasts | sonner | After every completed or failed action; never for reads |
| i18n | i18next + react-i18next | No hard-coded UI text | | i18n | i18next + react-i18next | No hard-coded UI text |
| Env | @t3-oss/env-core + valibot | The app validates its variables with `createClientEnv` and `createServerEnv` from `packages/libs/env`; other projects read only their own `env/` | | Env | @t3-oss/env-core + valibot | The app validates its variables with `createClientEnv` and `createServerEnv` from `packages/libs/env`; other projects read only their own `env/`. No hard-coded env values |
| Lint and format | oxlint, prettier | ESLint runs module-boundary rules only | | Lint and format | oxlint, prettier | ESLint runs module-boundary rules only |
| TS scripts and configs | jiti | Runs `tools/` scripts and TypeScript config files without a build step | | TS scripts and configs | jiti | Runs `tools/` scripts and TypeScript config files without a build step |
| Icons | svgo | Through island's `icon-sprite-plugin` | | Icons | svgo | Through island's `icon-sprite-plugin`, into `symbol-defs.svg`, which no step hashes; linked with `?v=<N>` |
TanStack Query is implied by `configs/react-query.ts`; confirm the repo uses it before adding it. Don't add any dependency outside this stack without stating why and getting approval. TanStack Query is implied by `configs/react-query.ts`; confirm the repo uses it before adding it. Don't add any dependency outside this stack without stating why and getting approval.
@ -51,6 +51,7 @@ TanStack Query is implied by `configs/react-query.ts`; confirm the repo uses it
The rules below are enough for work inside existing projects and features. Read the rest only when its trigger applies: The rules below are enough for work inside existing projects and features. Read the rest only when its trigger applies:
- Project structure (full trees, Nx tags, the env flow, export mechanics), only when you add an Nx project, a feature, or a top-level folder, or change tags or exports: [references/project-structure.md](references/project-structure.md) - Project structure (full trees, Nx tags, the env flow, export mechanics), only when you add an Nx project, a feature, or a top-level folder, or change tags or exports: [references/project-structure.md](references/project-structure.md)
- Component placement (its atomic level and the project and folder it belongs in), before you add or move a component: only the "Choosing where a component goes" section of [references/project-structure.md](references/project-structure.md#choosing-where-a-component-goes)
- Code patterns, one section at a time: read only the section for the layer you write (island component, tokens, repository, action, form and model, mutation, store, persisted store, env), as its Contents line lists. Copy an existing file of the same kind when the repo has one: [references/code-patterns.md](references/code-patterns.md) - Code patterns, one section at a time: read only the section for the layer you write (island component, tokens, repository, action, form and model, mutation, store, persisted store, env), as its Contents line lists. Copy an existing file of the same kind when the repo has one: [references/code-patterns.md](references/code-patterns.md)
Shared libs have full specs. Read the matching one only when you build or change the lib itself, or when a feature needs lib behavior that "Env, HTTP, cookies, and storage" below doesn't describe. To use a lib from a feature, that section and code-patterns.md are enough: Shared libs have full specs. Read the matching one only when you build or change the lib itself, or when a feature needs lib behavior that "Env, HTTP, cookies, and storage" below doesn't describe. To use a lib from a feature, that section and code-patterns.md are enough:
@ -83,7 +84,7 @@ Error handling, patterns, and refactoring have their own references. Read each o
**Dependency direction** **Dependency direction**
- apps → platforms → packages. Nothing imports upward, and one product's app or platform never imports another's. ESLint enforces this through Nx tags. - apps → platforms → packages. Nothing imports upward, apps never import each other, and one product's app or platform never imports another's. ESLint enforces this through Nx tags.
- island follows atomic design: atoms → molecules → organisms → templates, and a level never imports a level above it. `primitives/` are non-visual structural pieces (for example a portal) outside that ladder. The `components/` and `hooks/` inside an organism are private to it, except a compound component's named parts, which its `index.ts` re-exports. - island follows atomic design: atoms → molecules → organisms → templates, and a level never imports a level above it. `primitives/` are non-visual structural pieces (for example a portal) outside that ladder. The `components/` and `hooks/` inside an organism are private to it, except a compound component's named parts, which its `index.ts` re-exports.
**Features are DDD** (`features/<feature>/`) **Features are DDD** (`features/<feature>/`)
@ -112,6 +113,7 @@ Error handling, patterns, and refactoring have their own references. Read each o
**Env, HTTP, cookies, and storage** **Env, HTTP, cookies, and storage**
- Env (`packages/libs/src/env`): only the app's `env/` files read `process.env`, through `createClientEnv` (public) and `createServerEnv` (server only). Other projects read their own values with `getEnv`, filled by the app's bootstrap. Libs never read env; the bootstrap passes their settings through `configure`. - Env (`packages/libs/src/env`): only the app's `env/` files read `process.env`, through `createClientEnv` (public) and `createServerEnv` (server only). Other projects read their own values with `getEnv`, filled by the app's bootstrap. Libs never read env; the bootstrap passes their settings through `configure`.
- No project hard-codes an env value: a value that changes between environments, such as a service or CDN address, a key, a third-party ID, or a feature flag. Not as a literal, a fallback (`?? 'http://localhost:3000'`), or a schema default. Every env value comes from the `.env` of the app that serves it, and only apps have `.env` files. Values that are the same in every environment stay in `constants/`.
- HTTP (`packages/libs/http`): one root `http` client, configured in the app's bootstrap, and one client per feature made with `http.extend(...)`, so every feature shares one token refresh, the interceptors, and error normalization. - HTTP (`packages/libs/http`): one root `http` client, configured in the app's bootstrap, and one client per feature made with `http.extend(...)`, so every feature shares one token refresh, the interceptors, and error normalization.
- Auth is cookie-based. On a 401, one refresh runs for the whole app, the waiting requests replay once, and a failed refresh triggers logout. The server side never refreshes and never sends the auth cookies. - Auth is cookie-based. On a 401, one refresh runs for the whole app, the waiting requests replay once, and a failed refresh triggers logout. The server side never refreshes and never sends the auth cookies.
- Retry covers only idempotent requests, with backoff. Every request is abortable, and aborted requests are silent. Uploads report progress. - Retry covers only idempotent requests, with backoff. Every request is abortable, and aborted requests are silent. Uploads report progress.
@ -123,8 +125,10 @@ Error handling, patterns, and refactoring have their own references. Read each o
**Design system (island)** **Design system (island)**
- Build UI from island. Never fork or restyle an island component inside a feature; add a variant to island and use it. - Build UI from island. Never fork or restyle an island component inside a feature; add a variant to island and use it.
- Place every new component in three steps: reuse or add a variant first, then pick its level by what it renders and imports (never by its size), then its owner by whether it knows a domain. A domain-free organism that one route uses stays in that route's `organisms/` until a second route needs it, then moves to island. An organism or template that knows a domain and serves several routes, or the same route in several apps, goes to the platform's `screens/`, at the nearest route level they share. Details: [references/project-structure.md](references/project-structure.md#choosing-where-a-component-goes).
- Components use semantic tokens (`--color-surface-card`, `--color-text-muted`, `--color-action-primary`) layered over primitive tokens in `theme.css`. That layering is what makes theming and dark mode possible without a rewrite. - Components use semantic tokens (`--color-surface-card`, `--color-text-muted`, `--color-action-primary`) layered over primitive tokens in `theme.css`. That layering is what makes theming and dark mode possible without a rewrite.
- Every component defines its variants, sizes, and states (default, hover, focus-visible, active, disabled, loading, error, selected) and its accessibility behavior. Enabled interactive elements show `cursor: pointer` and disabled ones `cursor: not-allowed`, built into the component so no page can forget them. - Every component defines its variants, sizes, and states (default, hover, focus-visible, active, disabled, loading, error, selected) and its accessibility behavior. Enabled interactive elements show `cursor: pointer` and disabled ones `cursor: not-allowed`, built into the component so no page can forget them.
- Fonts and the icon sprite keep their fixed file names, such as `yekan-bakh-vf.woff2` and `symbol-defs.svg`, served from each app's `public/` as immutable. No build step hashes or renames them (not `next/font`, the bundler, or the CSS pipeline), so an unchanged file stays in every visitor's cache across deploys. Fonts have no version. The sprite is linked as `symbol-defs.svg?v=<N>`, and every change to it raises `ICON_SPRITE_VERSION` in the same commit. Details: [references/ui-rules.md](references/ui-rules.md#fonts-and-the-icon-sprite).
- Complex organisms are compound components (`<DataTable>`, `<DataTable.Toolbar>`, `<DataTable.Pagination>`) that share state through context, with slots or render props for the parts that vary per entity, such as cells, empty states, and toolbars. - Complex organisms are compound components (`<DataTable>`, `<DataTable.Toolbar>`, `<DataTable.Pagination>`) that share state through context, with slots or render props for the parts that vary per entity, such as cells, empty states, and toolbars.
**Cross-cutting** **Cross-cutting**
@ -139,12 +143,12 @@ Error handling, patterns, and refactoring have their own references. Read each o
## 4. Workflow ## 4. Workflow
Follow these steps for any design or implementation task. Write a short plan in the PR description: affected projects and paths, data types, each route's streamed, deferred, and auth-dependent parts, each rendering override the developer asked for, and each new non-obvious pattern. Follow these steps for any design or implementation task. Write a short plan in the PR description: affected projects and paths, each new component's path, level, and reason, data types, each route's streamed, deferred, and auth-dependent parts, each rendering override the developer asked for, and each new non-obvious pattern.
1. **Clarify the job.** Who uses it, how often, and what they finish with it. State assumptions. 1. **Clarify the job.** Who uses it, how often, and what they finish with it. State assumptions.
2. **Read the playbook** ([b2c-b2b.md](references/b2c-b2b.md)), plus [ui-rules.md](references/ui-rules.md) for UI work. 2. **Read the playbook** ([b2c-b2b.md](references/b2c-b2b.md)), plus [ui-rules.md](references/ui-rules.md) for UI work.
3. **Map the data.** Entities, repository types (`*Args`, `*Dto`, `*ResponseDto`, `*Payload`), caches and how each client part gets its server data, page and part models, actions and their events, query keys, and how the query cache is updated after each mutation. 3. **Map the data.** Entities, repository types (`*Args`, `*Dto`, `*ResponseDto`, `*Payload`), caches and how each client part gets its server data, page and part models, actions and their events, query keys, and how the query cache is updated after each mutation.
4. **Place the code.** List the Nx projects and folders that change. Reuse what exists before creating anything. For each part you add or move, decide whether it depends on the viewer, where it renders, and when its code loads ([rendering-patterns.md](references/rendering-patterns.md)), and add a pattern only for a signal you can name ([design-patterns.md](references/design-patterns.md)). When existing code resists the change, refactor it first, in its own commit ([refactoring.md](references/refactoring.md)). 4. **Place the code.** List the Nx projects and folders that change. Reuse what exists before creating anything. Give each component you add or move its level and owner with "Choosing where a component goes" ([project-structure.md](references/project-structure.md#choosing-where-a-component-goes)). For each part you add or move, decide whether it depends on the viewer, where it renders, and when its code loads ([rendering-patterns.md](references/rendering-patterns.md)), and add a pattern only for a signal you can name ([design-patterns.md](references/design-patterns.md)). When existing code resists the change, refactor it first, in its own commit ([refactoring.md](references/refactoring.md)).
5. **Design every state first:** loading, empty (no data, no results, not found, no access), error, in progress, then populated. 5. **Design every state first:** loading, empty (no data, no results, not found, no access), error, in progress, then populated.
6. **Build in layer order,** with island components, adding variants to island when needed: 6. **Build in layer order,** with island components, adding variants to island when needed:
1. Setup: Nx projects, tags, subpath exports, and new env variables. 1. Setup: Nx projects, tags, subpath exports, and new env variables.
@ -179,16 +183,19 @@ Copy this into the PR description, add the list from the playbook, and tick ever
``` ```
Structure Structure
[ ] Code is in the right project and folder, under src/, named per the naming rules [ ] Code is in the right project and folder, under src/, named per the naming rules
[ ] Each new or moved component went through "Choosing where a component goes"; its path, level, and reason are in the PR
[ ] Public API is exported by name from index.ts (and server.ts); no export * [ ] Public API is exported by name from index.ts (and server.ts); no export *
[ ] ESLint boundaries pass; no upward or cross-product imports [ ] ESLint boundaries pass; no upward or cross-product imports
[ ] Repositories have no client-side dependencies; UI and stores use *Payload types only [ ] Repositories have no client-side dependencies; UI and stores use *Payload types only
[ ] Repositories send requests only through their feature's http.ts client; no fetch outside the HTTP lib [ ] Repositories send requests only through their feature's http.ts client; no fetch outside the HTTP lib
[ ] Env is read only in the app's env/ files and through each project's getEnv(); no process.env elsewhere [ ] Env is read only in the app's env/ files and through each project's getEnv(); no process.env elsewhere
[ ] No hard-coded env value, fallback, or schema default; every env value comes from the app's .env, and only apps have .env files
[ ] Every action emits its event when it succeeds, unless called with { emit: false } [ ] Every action emits its event when it succeeds, unless called with { emit: false }
[ ] No tokens or personal data in cookies or local storage; neither is read during render [ ] No tokens or personal data in cookies or local storage; neither is read during render
[ ] Every new pattern answers a named signal and sits where design-patterns.md puts it; none is on its "Not used here" list [ ] Every new pattern answers a named signal and sits where design-patterns.md puts it; none is on its "Not used here" list
[ ] Each new or moved part went through rendering-patterns.md's "Choosing where a part loads"; every deferred part and its trigger is written in the PR [ ] Each new or moved part went through rendering-patterns.md's "Choosing where a part loads"; every deferred part and its trigger is written in the PR
[ ] The server render is the same for every visitor; every auth-dependent page or part renders in the browser behind a same-size skeleton, unless the developer asked otherwise and the PR says so [ ] The server render is the same for every visitor; every auth-dependent page or part renders in the browser behind a same-size skeleton, unless the developer asked otherwise and the PR says so
[ ] Fonts and the icon sprite keep fixed names that no step hashes; every sprite change raised ICON_SPRITE_VERSION in the same commit
[ ] Refactors are in their own commits, and the PR states how unchanged behavior was checked; smells noticed but not fixed are listed as debt [ ] Refactors are in their own commits, and the PR states how unchanged behavior was checked; smells noticed but not fixed are listed as debt
[ ] Code follows every accepted decision in docs/decisions; lasting decisions made in this work are recorded [ ] Code follows every accepted decision in docs/decisions; lasting decisions made in this work are recorded
@ -214,4 +221,4 @@ Every review comment names the rule, shows the problem, and proposes the fix. Fo
Name a code smell and its technique, with the target layer or file, as [references/refactoring.md](references/refactoring.md#review-comments) does. A smell is a suggestion; when it also breaks a rule on the list below, lead with that rule, mark it blocking, and name the smell in the body. In a feature PR, raise smells only in the code the PR touches. Flag a pattern from the "Not used here" list in [references/design-patterns.md](references/design-patterns.md#not-used-here) with its alternative. Never flag the smells that refactoring.md marks as intended. Name a code smell and its technique, with the target layer or file, as [references/refactoring.md](references/refactoring.md#review-comments) does. A smell is a suggestion; when it also breaks a rule on the list below, lead with that rule, mark it blocking, and name the smell in the body. In a feature PR, raise smells only in the code the PR touches. Flag a pattern from the "Not used here" list in [references/design-patterns.md](references/design-patterns.md#not-used-here) with its alternative. Never flag the smells that refactoring.md marks as intended.
Block a merge only for: code that breaks an accepted project decision; a boundary or layer violation; a client-side dependency in a repository; server-only code reachable from a client bundle; tokens or personal data readable by JavaScript (a non-HttpOnly cookie or local storage); stale cache after a mutation; missing error handling; missing loading or empty states; inaccessible contrast; UI that flickers on update; a server-side cache; a server render that depends on auth without the developer's explicit request; a page not rendered per request, or a web-vitals or bundle-budget regression. Everything else is a suggestion with a rationale. Block a merge only for: code that breaks an accepted project decision; a boundary or layer violation; a client-side dependency in a repository; server-only code reachable from a client bundle; tokens or personal data readable by JavaScript (a non-HttpOnly cookie or local storage); stale cache after a mutation; a sprite change without a version bump, a font changed under its old name, or a font or sprite name that a build step hashes; missing error handling; missing loading or empty states; inaccessible contrast; UI that flickers on update; a server-side cache; a server render that depends on auth without the developer's explicit request; a page not rendered per request, or a web-vitals or bundle-budget regression. Everything else is a suggestion with a rationale.

View File

@ -1,6 +1,6 @@
# Code patterns # Code patterns
Reference implementations for each layer. Paths are relative to the project that owns the code: `platforms/<app>/src/` for an app's logic and `packages/<name>/src/` for shared packages. `@project` is the workspace scope. The `@project/libs/*` APIs shown follow the lib specs: `http` and `isHttpError` in [lib-http.md](lib-http.md), the error handler's functions in [lib-error-handler.md](lib-error-handler.md), `storage` in [lib-local-storage.md](lib-local-storage.md), `cookie` in [lib-cookie.md](lib-cookie.md). `eventEmitter` stands for the repo's own lib; match its real signature. Reference implementations for each layer. Paths are relative to the project that owns the code: `platforms/<platform>/src/` for a product's logic and `packages/<name>/src/` for shared packages. `@project` is the workspace scope. The `@project/libs/*` APIs shown follow the lib specs: `http` and `isHttpError` in [lib-http.md](lib-http.md), the error handler's functions in [lib-error-handler.md](lib-error-handler.md), `storage` in [lib-local-storage.md](lib-local-storage.md), `cookie` in [lib-cookie.md](lib-cookie.md). `eventEmitter` stands for the repo's own lib; match its real signature.
Caches, the page entrypoint, and server-to-client data live in [b2c-b2b.md](b2c-b2b.md). Caches, the page entrypoint, and server-to-client data live in [b2c-b2b.md](b2c-b2b.md).
@ -157,12 +157,32 @@ This is an excerpt. The real file defines every semantic token the components us
@source '../'; @source '../';
``` ```
`styles/fonts.css`. Each `src` is a root path to the file in the app's `public/fonts/`, so no build step renames it ([ui-rules.md](ui-rules.md#fonts-and-the-icon-sprite)). The fallback face is a local font resized to the web font's metrics, so the swap doesn't shift layout. Measure the override values once for each face, and list the fallback after the web font in `--font-sans` in `theme.css`.
```css
@font-face {
font-family: 'Yekan Bakh';
src: url('/fonts/yekan-bakh-vf.woff2') format('woff2');
font-weight: 100 900;
font-display: swap;
}
@font-face {
font-family: 'Yekan Bakh Fallback';
src: local('Tahoma');
size-adjust: 102%;
ascent-override: 95%;
descent-override: 28%;
line-gap-override: 0%;
}
```
`apps/<app>/src/styles/app.css` `apps/<app>/src/styles/app.css`
```css ```css
@import 'tailwindcss' source('../'); @import 'tailwindcss' source('../');
@import '@project/island/styles/island.css'; @import '@project/island/styles/island.css';
@source '../../../../platforms/<app>/src'; @source '../../../../platforms/<platform>/src';
``` ```
Tailwind generates only the classes it finds in registered sources. island registers itself in `island.css`; the app registers its own `src/`, its platform, and any integration that renders UI. CSS `@import` resolves package names through package.json `exports`, not TypeScript path aliases, so path-alias workspaces import `island.css` by relative path. Tailwind generates only the classes it finds in registered sources. island registers itself in `island.css`; the app registers its own `src/`, its platform, and any integration that renders UI. CSS `@import` resolves package names through package.json `exports`, not TypeScript path aliases, so path-alias workspaces import `island.css` by relative path.

View File

@ -70,7 +70,7 @@ Where a new implementation goes:
| Exhaustive check | `assertNever` in `packages/tools/src/assert-never/` | `assertNever(value: never): never` throws. Call it in the `default` of every `switch` over a union | | Exhaustive check | `assertNever` in `packages/tools/src/assert-never/` | `assertNever(value: never): never` throws. Call it in the `default` of every `switch` over a union |
| Generic hook with no feature data, such as `useDebouncedValue` | `packages/tools/src/use-debounced-value/use-debounced-value.ts` when more than one project needs it; otherwise beside its only user, such as an organism's `hooks/` | A `use-<name>.ts` hook that takes plain values and imports only React. A hook that reads a store, a query, or a `*Payload` belongs in the owning feature's `models/` or beside its store | | Generic hook with no feature data, such as `useDebouncedValue` | `packages/tools/src/use-debounced-value/use-debounced-value.ts` when more than one project needs it; otherwise beside its only user, such as an organism's `hooks/` | A `use-<name>.ts` hook that takes plain values and imports only React. A hook that reads a store, a query, or a `*Payload` belongs in the owning feature's `models/` or beside its store |
The examples use feature paths relative to `platforms/<app>/src/`, as code-patterns.md does. The examples use feature paths relative to `platforms/<platform>/src/`, as code-patterns.md does.
**Strategy.** An order's status picks its badge in the order list, the order header, and the timeline. One map replaces the three switches, and `satisfies` makes a new status fail type-check until it has an entry. **Strategy.** An order's status picks its badge in the order list, the order header, and the timeline. One map replaces the three switches, and `satisfies` makes a new status fail type-check until it has an entry.
@ -226,7 +226,7 @@ export const analytics: AnalyticsAdapter = {
}; };
``` ```
`platforms/<app>/src/app/app-shell/AppShell.tsx`, reduced to the subscription. `platforms/<platform>/src/app/app-shell/AppShell.tsx`, reduced to the subscription.
```tsx ```tsx
'use client'; 'use client';

View File

@ -2,7 +2,7 @@
The code for [error-handling.md](error-handling.md): island's error boundary, `ErrorFallback`, the part, page, and app boundaries, `readOnServer`, and the query client's error settings. Read it only when you build or change one of these. A feature that uses them needs only error-handling.md. The code for [error-handling.md](error-handling.md): island's error boundary, `ErrorFallback`, the part, page, and app boundaries, `readOnServer`, and the query client's error settings. Read it only when you build or change one of these. A feature that uses them needs only error-handling.md.
Paths are relative to `platforms/<app>/src/`, as in [code-patterns.md](code-patterns.md). Each `error-boundaries/<name>/` module is shaped like `guards/`: the component or function, its `types.ts`, and `index.ts`. Paths are relative to `platforms/<platform>/src/`, as in [code-patterns.md](code-patterns.md). Each `error-boundaries/<name>/` module is shaped like `guards/`: the component or function, its `types.ts`, and `index.ts`.
**island's error boundary.** `packages/island/src/primitives/error-boundary/ErrorBoundary.tsx` is a class, because React has no hook for catching render errors. It knows nothing about HTTP or reporting; the fallback does that. Its `types.ts` declares `ErrorBoundaryProps`: `children`, `fallback: (props: { error: unknown; reset: () => void }) => ReactNode`, `onReset?`, and `resetKeys?: readonly unknown[]`. **island's error boundary.** `packages/island/src/primitives/error-boundary/ErrorBoundary.tsx` is a class, because React has no hook for catching render errors. It knows nothing about HTTP or reporting; the fallback does that. Its `types.ts` declares `ErrorBoundaryProps`: `children`, `fallback: (props: { error: unknown; reset: () => void }) => ReactNode`, `onReset?`, and `resetKeys?: readonly unknown[]`.

View File

@ -4,6 +4,8 @@ Validates the app's environment variables and gives apps typed, read-only values
Only apps call it. Every other project gets its values from the app's bootstrap through its own `env/` (`setEnv` and `getEnv`), so no project below the app reads the environment. Only apps call it. Every other project gets its values from the app's bootstrap through its own `env/` (`setEnv` and `getEnv`), so no project below the app reads the environment.
No project hard-codes an env value. An env value is a value that changes between environments: a service or CDN address, a key, a third-party ID, a feature flag. Every env value comes from the `.env` of the app that serves it, and only apps have `.env` files.
Contents: Structure · Types · API · Validation · The app's env · Project env · Bootstrap · Implementation · Usage · Acceptance checklist Contents: Structure · Types · API · Validation · The app's env · Project env · Bootstrap · Implementation · Usage · Acceptance checklist
## Structure ## Structure
@ -52,8 +54,8 @@ export type ServerEnvOptions<TSchema extends EnvSchema> = {
- It has no `skipValidation`: public variables are inlined when the app is built, so they must be present at build time anyway. - It has no `skipValidation`: public variables are inlined when the app is built, so they must be present at build time anyway.
- `createServerEnv(options)` returns `EnvValues<TSchema>`. It is server-only, so a client import fails the build, and it reads `runtimeEnv: process.env` at runtime. - `createServerEnv(options)` returns `EnvValues<TSchema>`. It is server-only, so a client import fails the build, and it reads `runtimeEnv: process.env` at runtime.
- Both: - Both:
- Empty strings count as missing (`emptyStringAsUndefined`), so `API_URL=` in a `.env` file fails instead of passing as `''`, and an optional variable gets its default. - Empty strings count as missing (`emptyStringAsUndefined`), so `API_URL=` in a `.env` file fails instead of passing as `''`.
- The values are the schema outputs, so defaults and transforms apply: `v.optional(v.pipe(v.string(), v.transform(Number), v.integer()), '24')` gives the number `24`. - The values are the schema outputs, so transforms apply: `v.pipe(v.string(), v.transform(Number), v.integer())` turns `'24'` into the number `24`.
- On failure they throw one `Error` that lists every invalid variable and why: - On failure they throw one `Error` that lists every invalid variable and why:
``` ```
@ -68,7 +70,7 @@ export type ServerEnvOptions<TSchema extends EnvSchema> = {
- Validation runs when the app's env module first loads. Both bootstraps import it first, so a bad variable stops the app with one clear error before any page renders. - Validation runs when the app's env module first loads. Both bootstraps import it first, so a bad variable stops the app with one clear error before any page renders.
- Next.js: to fail the build instead, load `env/env.client.ts` from `next.config.ts` (with jiti when the config can't resolve it). Never load `env.server.ts` there: `server-only` throws outside the React server graph. - Next.js: to fail the build instead, load `env/env.client.ts` from `next.config.ts` (with jiti when the config can't resolve it). Never load `env.server.ts` there: `server-only` throws outside the React server graph.
- `skipValidation` (server env only) is for steps that run without the real env: lint, type-check, and a Docker image build without runtime secrets. The app sets it from a flag (`SKIP_ENV_VALIDATION=true`). Skipped validation returns the raw strings without defaults or transforms, so a running app never sets it. - `skipValidation` (server env only) is for steps that run without the real env: lint, type-check, and a Docker image build without runtime secrets. The app sets it from a flag (`SKIP_ENV_VALIDATION=true`). Skipped validation returns the raw strings without transforms, so a running app never sets it.
- Messages come from the schemas, and valibot's default messages repeat the received value. Give every secret's schema its own message (`v.minLength(32, 'Use at least 32 characters')`), and never log env values. - Messages come from the schemas, and valibot's default messages repeat the received value. Give every secret's schema its own message (`v.minLength(32, 'Use at least 32 characters')`), and never log env values.
## The app's env ## The app's env
@ -83,6 +85,8 @@ apps/<app>/src/env/
- These files are the only code in the repo that reads `process.env`. - These files are the only code in the repo that reads `process.env`.
- App code (bootstrap, configs) reads `clientEnv` and `serverEnv` directly. Only server code imports `../env/server`. - App code (bootstrap, configs) reads `clientEnv` and `serverEnv` directly. Only server code imports `../env/server`.
- Every value comes from the app's `.env` files. Only apps that serve in production have `.env` files; platforms, island, libs, integrations, and tools have none.
- Every variable is required. Never give a schema a default (`v.optional(schema, 'http://localhost:3000')`) or add a fallback in code (`clientEnv.NEXT_PUBLIC_API_URL ?? '...'`). A default or a fallback is a hard-coded value that hides a missing variable.
## Project env ## Project env
@ -99,7 +103,8 @@ Every project except apps that reads env has:
- The type uses the project's own names (`cdnUrl`, `catalogApiUrl`), not variable names. The bootstrap maps one to the other, so renaming a variable only touches the app. - The type uses the project's own names (`cdnUrl`, `catalogApiUrl`), not variable names. The bootstrap maps one to the other, so renaming a variable only touches the app.
- Read `getEnv()` inside functions, never at module top level, because bootstrap may not have run yet: `baseUrl: () => getEnv().catalogApiUrl`. - Read `getEnv()` inside functions, never at module top level, because bootstrap may not have run yet: `baseUrl: () => getEnv().catalogApiUrl`.
- The project never imports the app or reads the raw environment, so the dependency graph stays acyclic. - The project never imports the app or reads the raw environment, so the dependency graph stays acyclic.
- Libs have no project env; they never read env. The bootstrap passes their settings through `configure`: `http.configure({ baseUrl })`, `configureServerHttp({ baseUrl, getCookieHeader })`, `cookie.configure({ secure })`. - The project never hard-codes an env value: no literal address, key, ID, or flag, and no fallback for a `getEnv()` value. A new env value goes in the project's env type, and the app fills it from its `.env`.
- Libs have no project env; they never read env. The bootstrap passes their settings through `configure`: `http.configure({ baseUrl })`, `configureServerHttp({ baseUrl, getCookieHeader })`, `cookie.configure({ secure })`. A lib never has a default address, key, or ID; it gets them through `configure`.
## Bootstrap ## Bootstrap
@ -254,7 +259,7 @@ setPlatformEnv({ catalogApiUrl: clientEnv.NEXT_PUBLIC_CATALOG_API_URL });
http.configure({ baseUrl: clientEnv.NEXT_PUBLIC_API_URL }); http.configure({ baseUrl: clientEnv.NEXT_PUBLIC_API_URL });
``` ```
`platforms/<app>/src/features/catalog/http.ts` reads the platform's env. The server copy holds the internal address and the client copy the public one. `platforms/<platform>/src/features/catalog/http.ts` reads the platform's env. The server copy holds the internal address and the client copy the public one.
```ts ```ts
import { http } from '@project/libs/http'; import { http } from '@project/libs/http';
@ -268,7 +273,7 @@ export const catalogHttp = http.extend({ baseUrl: () => getEnv().catalogApiUrl }
For building or changing the lib: For building or changing the lib:
``` ```
[ ] createClientEnv and createServerEnv return typed, read-only values; defaults and transforms apply [ ] createClientEnv and createServerEnv return typed, read-only values; transforms apply
[ ] A public variable without the prefix, or a declared variable missing from runtimeEnv, is a type error [ ] A public variable without the prefix, or a declared variable missing from runtimeEnv, is a type error
[ ] A missing, empty, or invalid variable throws one Error that lists every invalid variable and why [ ] A missing, empty, or invalid variable throws one Error that lists every invalid variable and why
[ ] Importing @project/libs/env/server outside the React server graph throws (server-only), so a client import fails the build [ ] Importing @project/libs/env/server outside the React server graph throws (server-only), so a client import fails the build
@ -276,4 +281,5 @@ For building or changing the lib:
[ ] skipValidation returns the raw values without validating [ ] skipValidation returns the raw values without validating
[ ] A project's getEnv throws the clear error before setEnv and returns the values after it [ ] A project's getEnv throws the clear error before setEnv and returns the values after it
[ ] No process.env outside the app's env/ files [ ] No process.env outside the app's env/ files
[ ] No hard-coded env value, fallback, or schema default; every env value comes from the app's .env, and only apps have .env files
``` ```

View File

@ -2,7 +2,7 @@
A full page for [b2c-b2b.md](b2c-b2b.md): device detection, caches, a server page loader, the page entrypoint, streamed parts, and query hydration. Read it when you add a new page, or a part that reads server data in a way the repo doesn't have yet. Otherwise copy the shape of an existing page. A full page for [b2c-b2b.md](b2c-b2b.md): device detection, caches, a server page loader, the page entrypoint, streamed parts, and query hydration. Read it when you add a new page, or a part that reads server data in a way the repo doesn't have yet. Otherwise copy the shape of an existing page.
`platforms/<app>/src/shared/utils/get-device.ts` `platforms/<platform>/src/shared/utils/get-device.ts`
```ts ```ts
import 'server-only'; import 'server-only';
@ -15,7 +15,7 @@ export async function getDevice(): Promise<'mobile' | 'desktop'> {
} }
``` ```
`platforms/<app>/src/features/catalog/caches/products.ts` `platforms/<platform>/src/features/catalog/caches/products.ts`
```ts ```ts
import 'server-only'; import 'server-only';
@ -32,7 +32,7 @@ export const getRelatedProducts = cache((id: string) =>
export const getProductReviews = cache((id: string, page: number) => productsRepository.listReviews({ id, page })); export const getProductReviews = cache((id: string, page: number) => productsRepository.listReviews({ id, page }));
``` ```
`platforms/<app>/src/features/catalog/caches/server.ts` `platforms/<platform>/src/features/catalog/caches/server.ts`
```ts ```ts
import 'server-only'; import 'server-only';
@ -40,7 +40,7 @@ import 'server-only';
export { getProduct, getProductReviews, getRelatedProducts } from './products'; export { getProduct, getProductReviews, getRelatedProducts } from './products';
``` ```
`platforms/<app>/src/server.ts` `platforms/<platform>/src/server.ts`
```ts ```ts
import 'server-only'; import 'server-only';
@ -125,7 +125,7 @@ export async function ProductReviews({ productId }: ProductReviewsProps) {
} }
``` ```
`platforms/<app>/src/features/catalog/models/product/use-product-reviews-part.ts`. Page 1 comes from the server; later pages load in the browser while the current page stays visible. `platforms/<platform>/src/features/catalog/models/product/use-product-reviews-part.ts`. Page 1 comes from the server; later pages load in the browser while the current page stays visible.
```ts ```ts
import { keepPreviousData, useQuery } from '@tanstack/react-query'; import { keepPreviousData, useQuery } from '@tanstack/react-query';

View File

@ -1,14 +1,14 @@
# Project structure # Project structure
`<placeholders>` are names you choose. `@project` stands for the workspace's npm scope. `<placeholders>` are names you choose. `@project` stands for the workspace's npm scope. A product has one platform and one or more apps that share it: `<app>` names an app, `<platform>` the product's platform, and `<product>` the product.
Contents: Top level · App · Platform · Feature anatomy · Shared · island · libs, integrations, and tools packages · Env flow · Nx tags and boundaries · Exports and tree-shaking Contents: Top level · App · Platform · Feature anatomy · Shared · island · Choosing where a component goes · libs, integrations, and tools packages · Env flow · Nx tags and boundaries · Exports and tree-shaking
## Top level ## Top level
``` ```
apps/ # deployable apps apps/ # deployable apps
platforms/ # each app's logic, one project per app platforms/ # each product's logic, one project per product, shared by its apps
packages/ packages/
├── island/ # design system (atomic design) ├── island/ # design system (atomic design)
├── libs/ # framework-agnostic libraries, e.g. http and env ├── libs/ # framework-agnostic libraries, e.g. http and env
@ -21,7 +21,7 @@ Three folders are named `tools`. Keep them apart:
- Root `tools/`: scripts that run in a terminal, in CI, or through Nx (generators, validators). App code never imports them. TypeScript scripts run with jiti. - Root `tools/`: scripts that run in a terminal, in CI, or through Nx (generators, validators). App code never imports them. TypeScript scripts run with jiti.
- `packages/tools/`: shared runtime tools that apps and projects import. - `packages/tools/`: shared runtime tools that apps and projects import.
- `packages/island/src/tools/`: design-system tools such as `cn`, `cvx`, `icon-sprite-plugin`, and `icon-name-extraction`. - `packages/island/src/tools/`: design-system tools such as `cn`, `cvx`, `icon-sprite-plugin`, `font-copy-plugin`, and `icon-name-extraction`.
## App (Next.js) ## App (Next.js)
@ -65,14 +65,14 @@ apps/<app>/src/
``` ```
- Pages are thin entrypoints. A page picks the mobile or the desktop template on the server, so no component branches on viewport size. - Pages are thin entrypoints. A page picks the mobile or the desktop template on the server, so no component branches on viewport size.
- Every route level may keep its own `organisms/` and `templates/`, shaped like island organisms. They are not routable because they contain no `page.tsx`. - Every route level may keep its own `organisms/` and `templates/`, shaped like island organisms. They are not routable because they contain no `page.tsx`. They hold only what this route uses; UI that knows a domain and serves several routes or apps lives in the platform's `screens/`.
- `styles/`, `configs/`, and `constants/` grow as needed; each keeps an `index.ts`. - `styles/`, `configs/`, and `constants/` grow as needed; each keeps an `index.ts`.
- The app holds no features, stores, or business logic; those live in `platforms/<app>/`. - The app holds no features, stores, or business logic; those live in `platforms/<platform>/`. Apps never import each other.
## Platform ## Platform
``` ```
platforms/<app>/src/ platforms/<platform>/src/
├── app/ ├── app/
│ ├── app-shell/ # top-level provider shell shared by the mobile and desktop views │ ├── app-shell/ # top-level provider shell shared by the mobile and desktop views
│ │ ├── AppShell.tsx │ │ ├── AppShell.tsx
@ -87,14 +87,24 @@ platforms/<app>/src/
│ │ ├── error-fallback/ # ErrorFallback: what every boundary renders │ │ ├── error-fallback/ # ErrorFallback: what every boundary renders
│ │ ├── status-empty-state/ # the not-found and no-access empty states │ │ ├── status-empty-state/ # the not-found and no-access empty states
│ │ └── read-on-server/ # readOnServer; server-only, exported through server.ts │ │ └── read-on-server/ # readOnServer; server-only, exported through server.ts
│ └── navigation/ │ ├── navigation/
│ ├── navigation.ts # typed route paths and navigation menus │ │ ├── navigation.ts # typed route paths and navigation menus
│ ├── constants.ts │ │ ├── constants.ts
│ ├── types.ts │ │ ├── types.ts
│ ├── hooks/ │ │ ├── hooks/
│ │ └── use-<hook-name>.ts │ │ │ └── use-<hook-name>.ts
│ ├── components/ # navigation UI, shaped like organisms │ │ ├── components/ # navigation UI, shaped like organisms
│ └── index.ts │ │ └── index.ts
│ └── screens/ # UI that knows a domain and serves several routes or apps
│ ├── organisms/ # shared by routes with no common route level
│ ├── templates/
│ └── (auth)/ # mirrors the apps' route tree
│ ├── organisms/ # shared by routes under (auth)
│ ├── templates/
│ └── auth/
│ └── login/
│ ├── organisms/ # shared by the login route of several apps, or by routes under it
│ └── templates/
├── features/ # DDD, see Feature anatomy ├── features/ # DDD, see Feature anatomy
├── stores/ # one store per feature or domain ├── stores/ # one store per feature or domain
├── shared/ # see Shared ├── shared/ # see Shared
@ -102,6 +112,14 @@ platforms/<app>/src/
└── server.ts └── server.ts
``` ```
`screens/` holds organisms and templates that know a domain and that several routes, or the same route in several apps, use. They can't go to island, because island is domain-free. They can't go to an app's route level, because one route level can't serve another route or another app.
- Its folders mirror the route tree. A component sits at the nearest route level that every route using it shares. Create a level's folder only when something lives in it.
- `organisms/` and `templates/` hold component modules shaped like island organisms.
- Its components know a domain: they call a model or an action, read a store, or take a `*Payload`. The logic itself stays in the feature's models and actions, so the components stay presentational.
- It is UI: it may import `features/`, `stores/`, `shared/`, the rest of `app/`, island, and integrations. Nothing in `features/`, `stores/`, or `shared/` imports it.
- A module that reads caches is server-only, like `read-on-server/`: its entry is `server.ts`, and the platform's `server.ts` re-exports it.
## Feature anatomy ## Feature anatomy
``` ```
@ -190,7 +208,7 @@ packages/island/src/
├── templates/ # like organisms ├── templates/ # like organisms
├── primitives/ # non-visual structural pieces, e.g. portal, error-boundary; like organisms ├── primitives/ # non-visual structural pieces, e.g. portal, error-boundary; like organisms
├── tools/ ├── tools/
│ └── <tool-name>/ # e.g. cn, cvx, icon-sprite-plugin, icon-name-extraction │ └── <tool-name>/ # e.g. cn, cvx, icon-sprite-plugin, font-copy-plugin, icon-name-extraction
│ ├── <tool-name>.ts or <tool-name>.tsx │ ├── <tool-name>.ts or <tool-name>.tsx
│ ├── types.ts │ ├── types.ts
│ ├── constants.ts │ ├── constants.ts
@ -199,16 +217,16 @@ packages/island/src/
│ ├── island.css # entry that apps import into their Tailwind v4 CSS │ ├── island.css # entry that apps import into their Tailwind v4 CSS
│ ├── theme.css # primitive and semantic tokens │ ├── theme.css # primitive and semantic tokens
│ ├── utilities.css # custom @utility definitions │ ├── utilities.css # custom @utility definitions
│ └── fonts.css # @font-face rules for fonts/ │ └── fonts.css # @font-face rules; root paths to public/fonts/, never relative
├── env/ # island's env: setEnv and getEnv, filled by the app's bootstrap ├── env/ # island's env: setEnv and getEnv, filled by the app's bootstrap
│ ├── env.ts │ ├── env.ts
│ ├── types.ts │ ├── types.ts
│ └── index.ts │ └── index.ts
├── icons/ ├── icons/
│ ├── symbol-defs.svg # sprite generated by Icomoon │ ├── symbol-defs.svg # sprite generated by Icomoon; linked as symbol-defs.svg?v=<N>
│ └── selection.json # Icomoon snapshot; re-import it into Icomoon to update the set │ └── selection.json # Icomoon snapshot; re-import it into Icomoon to update the set
├── fonts/ # every app's fonts, e.g. yekan-bakh-vf.woff2 ├── fonts/ # every app's fonts, e.g. yekan-bakh-vf.woff2
├── constants.ts # island-level constants ├── constants.ts # island-level constants, e.g. ICON_SPRITE_VERSION, CRITICAL_FONT_URL
├── index.ts ├── index.ts
└── server.ts └── server.ts
``` ```
@ -227,9 +245,42 @@ Component module:
Tools: Tools:
- `icon-sprite-plugin` is a build and dev plugin. It optimizes the SVGs with svgo and writes the final sprite into each app's `public/` folder. Build-time tools are imported only from build configs, never from app code. - `icon-sprite-plugin` is a build and dev plugin. It optimizes the SVGs with svgo and writes the final sprite into each app's `public/icons/symbol-defs.svg`.
- `font-copy-plugin` is a build and dev plugin. It copies `fonts/` byte for byte into each app's `public/fonts/`.
- Neither plugin adds a hash or a version to a file name, and no later build step renames their files. The sprite's version lives only in its link ([ui-rules.md](ui-rules.md#fonts-and-the-icon-sprite)). Their output in `public/` is generated, so git ignores it.
- Build-time tools are imported only from build configs, never from app code.
- `icon-name-extraction` extracts icon names from the Icomoon files, for example to type the `Icon` component's `name` prop. - `icon-name-extraction` extracts icon names from the Icomoon files, for example to type the `Icon` component's `name` prop.
## Choosing where a component goes
Run these three steps for every component you add or move. Write one line per component in the plan: its path, its level, and the reason, for example `packages/island/src/molecules/form-field/: molecule; a label, an input, and an error text for one field; domain-free`.
**1. Reuse.** A component that already does the job is imported, not rebuilt. An island component that does the job but looks different gets a variant in its `variants.ts`, never a new component or a copy.
**2. Level.** Decide by what the component renders and what it imports, never by its size. First match wins.
1. It renders no UI of its own, only structure or behavior (a portal, an error boundary, `LoadOnVisible`) → primitive.
2. It wraps one native element or draws one visual unit, and uses only other atoms (`Button` shows the `Spinner` atom) → atom: `Button`, `Input`, `Badge`, `Icon`, `Skeleton`.
3. It groups atoms for one job and holds no more than UI state, such as open or focused → molecule: `FormField`, `SearchBox`, `EmptyState`.
4. It's a distinct section of a screen: it composes molecules, owns interaction state or a context, or is a compound component → organism: `Tabs`, `DataTable`, `ProductRail`.
5. It arranges organisms into a page layout through slots and holds no data → template, such as a route's mobile or desktop template.
Then check the imports: nothing the component imports sits above its level. A component that needs a higher level belongs at that level. Move it up; never import upward.
**3. Owner.** A component is domain-free when it takes only plain props (strings, numbers, its own prop types, `ReactNode` slots, and callbacks) and imports only island, libs, and tools. It knows a domain when it takes a `*Payload` type, calls a model or an action, reads a store, or shows a feature's text. First match wins.
1. Only one organism, template, or primitive uses it → that module's private `components/`, shaped like an atom.
2. It's a route's mobile or desktop template → that route's `templates/`. When several apps render the same template for that route → `screens/` at that route's path, such as `screens/(auth)/auth/login/templates/`.
3. It knows a domain:
- Navigation UI → `platforms/<platform>/src/app/navigation/components/`.
- Third-party UI, such as a chat widget or its facade → the integration's `components/`.
- One route in one app uses it → that route's `organisms/` in the app.
- Several routes, or the same route in several apps, use it → `platforms/<platform>/src/app/screens/`, in the `organisms/` or `templates/` of the nearest route level they share, such as `screens/(shop)/organisms/`. With no shared level, `screens/organisms/`.
4. It's a domain-free organism that one route uses → that route's `organisms/`. When a second route needs it, move it to island's `organisms/` at once, as [refactoring.md](refactoring.md#when-and-how) describes; never copy it.
5. Otherwise → island, in the folder of its level. Route levels hold only `organisms/` and `templates/`, so every domain-free atom and molecule goes to island at once.
A piece that knows a domain but is smaller than an organism, such as a price line that formats a `*Payload`, is a private component of the organism that uses it. When other code needs it too, give it plain props instead and put it in island. A component that two products need also moves to island with plain props, because one product never imports another's code.
## libs, integrations, and tools packages ## libs, integrations, and tools packages
``` ```
@ -273,7 +324,7 @@ Fundamental libs have full specs:
## Env flow ## Env flow
1. The app declares its variables in `apps/<app>/src/env/` and validates them with the env lib: `createClientEnv` for public variables and `createServerEnv` for server variables. These files are the only code that reads `process.env`, and a bad variable stops the app with one error that lists every problem. 1. The app declares its variables in `apps/<app>/src/env/` and validates them with the env lib: `createClientEnv` for public variables and `createServerEnv` for server variables. These files are the only code that reads `process.env`, and a bad variable stops the app with one error that lists every problem. The values come only from the app's `.env` files; only apps have `.env` files, and no project hard-codes an env value, a fallback, or a schema default.
2. Every other project that reads env has `src/env/` (`env.ts`, `types.ts`, `index.ts`) with `setEnv`, which stores its own values, and `getEnv`, which returns them and throws a clear error before `setEnv` has run. Its code reads env only through `getEnv`, inside functions, never at module top level. 2. Every other project that reads env has `src/env/` (`env.ts`, `types.ts`, `index.ts`) with `setEnv`, which stores its own values, and `getEnv`, which returns them and throws a clear error before `setEnv` has run. Its code reads env only through `getEnv`, inside functions, never at module top level.
3. At startup the app's bootstrap calls each project's `setEnv` with the values that project needs. Projects never import the app, so the dependency graph stays acyclic. Libs never read env: the bootstrap passes their settings through `configure`. 3. At startup the app's bootstrap calls each project's `setEnv` with the values that project needs. Projects never import the app, so the dependency graph stays acyclic. Libs never read env: the bootstrap passes their settings through `configure`.
4. `bootstrap.server.ts` fills the server module graph and may pass server-side values, such as an internal service address; `bootstrap.client.ts` fills the client module graph with public values only. Public variables use the `NEXT_PUBLIC_` prefix and are listed one by one in `runtimeEnv`, because Next.js inlines only literal `process.env.NEXT_PUBLIC_*` references. 4. `bootstrap.server.ts` fills the server module graph and may pass server-side values, such as an internal service address; `bootstrap.client.ts` fills the client module graph with public values only. Public variables use the `NEXT_PUBLIC_` prefix and are listed one by one in `runtimeEnv`, because Next.js inlines only literal `process.env.NEXT_PUBLIC_*` references.
@ -286,8 +337,8 @@ Default tags. Reuse the repo's own tags if it already has them.
| Project | Tags | | Project | Tags |
|---|---| |---|---|
| `apps/<app>` | `type:app`, `scope:<app>` | | `apps/<app>` | `type:app`, `scope:<product>` |
| `platforms/<app>` | `type:platform`, `scope:<app>` | | `platforms/<platform>` | `type:platform`, `scope:<product>` |
| `packages/integrations` | `type:integration`, `scope:shared` | | `packages/integrations` | `type:integration`, `scope:shared` |
| `packages/island` | `type:ui`, `scope:shared` | | `packages/island` | `type:ui`, `scope:shared` |
| `packages/libs` | `type:lib`, `scope:shared` | | `packages/libs` | `type:lib`, `scope:shared` |
@ -303,7 +354,7 @@ Default tags. Reuse the repo's own tags if it already has them.
| `type:ui` | `type:lib`, `type:tool` | | `type:ui` | `type:lib`, `type:tool` |
| `type:lib` | `type:tool` | | `type:lib` | `type:tool` |
| `type:tool` | Nothing | | `type:tool` | Nothing |
| `scope:<app>` | `scope:<app>`, `scope:shared` | | `scope:<product>` | `scope:<product>`, `scope:shared` |
| `scope:shared` | `scope:shared` | | `scope:shared` | `scope:shared` |
Layer rules inside a project are checked in review, or by `eslint-plugin-boundaries` when the repo configures it: Layer rules inside a project are checked in review, or by `eslint-plugin-boundaries` when the repo configures it:
@ -311,6 +362,7 @@ Layer rules inside a project are checked in review, or by `eslint-plugin-boundar
- island: no import from a higher atomic level; an organism's `components/` and `hooks/` stay private. - island: no import from a higher atomic level; an organism's `components/` and `hooks/` stay private.
- features: the layer order in Feature anatomy. - features: the layer order in Feature anatomy.
- `shared/`: imports nothing above it. - `shared/`: imports nothing above it.
- platform `app/`: `features/`, `stores/`, and `shared/` never import it, so `screens/` stays the UI on top.
## Exports and tree-shaking ## Exports and tree-shaking

View File

@ -40,7 +40,7 @@ When to refactor:
- Before a feature the code resists: reshape the code until the feature is a small, obvious edit, then make that edit. - Before a feature the code resists: reshape the code until the feature is a small, obvious edit, then make that edit.
- While fixing a bug, in the layer that owns the fault ([SKILL.md](../SKILL.md#4-workflow)), and only as far as the fix needs. - While fixing a bug, in the layer that owns the fault ([SKILL.md](../SKILL.md#4-workflow)), and only as far as the fix needs.
- In review (see Review comments). - In review (see Review comments).
- At the third duplication, not the second (the rule of three), because by then the copies show what actually varies. island is the exception: a component that needs a second style gets an island variant at once, never a copy ([SKILL.md](../SKILL.md#3-architecture-rules)). - At the third duplication, not the second (the rule of three), because by then the copies show what actually varies. island is the exception: a component that needs a second style gets an island variant at once, never a copy ([SKILL.md](../SKILL.md#3-architecture-rules)). A route's organism that a second route needs also moves at once, never as a copy: to island when it's domain-free, or to the platform's `screens/`, at the nearest route level both share, when it knows a domain ([project-structure.md](project-structure.md#choosing-where-a-component-goes)).
Refactor only the code the change touches, unless the plan says otherwise. Record other smells you notice as debt in the PR's trade-offs note. Refactor only the code the change touches, unless the plan says otherwise. Record other smells you notice as debt in the PR's trade-offs note.
@ -162,8 +162,9 @@ The catalog doesn't name these, but this stack has them. Each line gives the sme
- An action that runs another action as one of its steps, emits its own event, and still lets the inner action emit → pass `{ emit: false }` to the inner action, so listeners hear one event per operation ([code-patterns.md](code-patterns.md#action)). - An action that runs another action as one of its steps, emits its own event, and still lets the inner action emit → pass `{ emit: false }` to the inner action, so listeners hear one event per operation ([code-patterns.md](code-patterns.md#action)).
- An event subscription in a component or at module top level, or one without an unsubscribe → subscribe once in an effect of the `AppShell` and unsubscribe in its cleanup ([code-patterns.md](code-patterns.md#action)). - An event subscription in a component or at module top level, or one without an unsubscribe → subscribe once in an effect of the `AppShell` and unsubscribe in its cleanup ([code-patterns.md](code-patterns.md#action)).
- `process.env` outside the app's `env/` → the app's env, or the project's `getEnv()` inside a function ([lib-env.md](lib-env.md#project-env)). - `process.env` outside the app's `env/` → the app's env, or the project's `getEnv()` inside a function ([lib-env.md](lib-env.md#project-env)).
- A hard-coded env value (an address, key, third-party ID, or flag), a fallback such as `?? 'http://localhost:3000'`, a schema default, or a `.env` file outside an app → a required variable in the app's `.env`, read through the app's env or the project's `getEnv()` ([lib-env.md](lib-env.md#the-apps-env)).
Many of these show up in a plain text search, which makes a quick first pass in review: `export *`, `'use client'` in a `page.tsx` or `layout.tsx`, `process.env` outside `env/`, `fetch(` outside the HTTP lib, and `key={index}`. Many of these show up in a plain text search, which makes a quick first pass in review: `export *`, `'use client'` in a `page.tsx` or `layout.tsx`, `process.env` outside `env/`, `localhost` or `http` address literals outside an app's `.env`, `fetch(` outside the HTTP lib, and `key={index}`.
## Techniques used most ## Techniques used most
@ -194,7 +195,7 @@ Grouped as in refactoring.guru's technique catalog. Each line says how the techn
- Replace Type Code with Class: a string-literal union in the entity, like `OrderStatus`, or an `as const` object when code needs the values at runtime. - Replace Type Code with Class: a string-literal union in the entity, like `OrderStatus`, or an `as const` object when code needs the values at runtime.
- Replace Type Code with Subclasses: a discriminated union with one component per member, chosen through one map. - Replace Type Code with Subclasses: a discriminated union with one component per member, chosen through one map.
- Replace Type Code with State/Strategy: a discriminated-union status for a flow, and a `Record` of handlers for behavior that varies per member. - Replace Type Code with State/Strategy: a discriminated-union status for a flow, and a `Record` of handlers for behavior that varies per member.
- Encapsulate Collection: only the store's actions change its arrays. Type the arrays `readonly` in the store's `types.ts`. For the persisted cart store in [code-patterns.md](code-patterns.md#persisted-store), its state becomes the one below. As in code-patterns.md, the path is relative to `platforms/<app>/src/`. - Encapsulate Collection: only the store's actions change its arrays. Type the arrays `readonly` in the store's `types.ts`. For the persisted cart store in [code-patterns.md](code-patterns.md#persisted-store), its state becomes the one below. As in code-patterns.md, the path is relative to `platforms/<platform>/src/`.
`stores/cart/types.ts` `stores/cart/types.ts`

View File

@ -55,7 +55,7 @@ How:
- A page that needs a logged-in user, such as every `(account)` page: the route group's layout wraps its children in the platform's `AuthGuard` (`app/guards/auth-guard/`). This client component renders the page skeleton while the status is `'unknown'`, sends a guest to login with a return URL, and renders the page for a member. The page stays a thin Server Component that resolves the device and passes only URL parameters to its template, and the template's parts load in the browser. `generateMetadata` reads no data: it returns a generic title and `robots: { index: false }`. - A page that needs a logged-in user, such as every `(account)` page: the route group's layout wraps its children in the platform's `AuthGuard` (`app/guards/auth-guard/`). This client component renders the page skeleton while the status is `'unknown'`, sends a guest to login with a return URL, and renders the page for a member. The page stays a thin Server Component that resolves the device and passes only URL parameters to its template, and the template's parts load in the browser. `generateMetadata` reads no data: it returns a generic title and `robots: { index: false }`.
- An action that changes the viewer, such as login, logout, or a payment, updates the auth store, so every auth-dependent part renders its new variant. It doesn't call `router.refresh()`, because no server-rendered content changed. - An action that changes the viewer, such as login, logout, or a payment, updates the auth store, so every auth-dependent part renders its new variant. It doesn't call `router.refresh()`, because no server-rendered content changed.
`platforms/<app>/src/features/membership/models/product/use-membership-offer-part.ts`. A guest sees an invitation to log in, a member without a subscription sees the subscription offer, and a subscriber (`user.hasSubscription`) sees their benefit. `types.ts` declares `MembershipOfferVariant = 'pending' | 'guest' | 'member' | 'subscriber'`. `platforms/<platform>/src/features/membership/models/product/use-membership-offer-part.ts`. A guest sees an invitation to log in, a member without a subscription sees the subscription offer, and a subscriber (`user.hasSubscription`) sees their benefit. `types.ts` declares `MembershipOfferVariant = 'pending' | 'guest' | 'member' | 'subscriber'`.
```ts ```ts
import { useCurrentUser, useViewerStatus } from '../../../../stores/auth'; import { useCurrentUser, useViewerStatus } from '../../../../stores/auth';

View File

@ -1,16 +1,35 @@
# UI rules # UI rules
UX, SEO, and asset rules for [b2c-b2b.md](b2c-b2b.md). Read it when you build or change what the user sees or what search engines read: a page, template, organism, form, copy, upload, image, font, or metadata. Work only on repositories, caches, actions, stores, or libs doesn't need it. UX, SEO, and asset rules for [b2c-b2b.md](b2c-b2b.md). Read it when you build or change what the user sees or what search engines read: a page, template, organism, form, copy, upload, image, font, icon, or metadata. Work only on repositories, caches, actions, stores, or libs doesn't need it.
Contents: Images, fonts, and CSS · SEO and i18n · Copy · Feedback · Stability · Loading, progress, and empty states · File uploads · Forms · Keyboard and context Contents: Images, fonts, and CSS (Fonts and the icon sprite) · SEO and i18n · Copy · Feedback · Stability · Loading, progress, and empty states · File uploads · Forms · Keyboard and context
## Images, fonts, and CSS ## Images, fonts, and CSS
- Use `next/image` with explicit dimensions and `sizes`. Never lazy-load the LCP image: give it `loading="eager"` and `fetchPriority="high"`, or `preload` when it's discovered late. `priority` is deprecated in Next.js 16. Everything below the fold stays lazy. - Use `next/image` with explicit dimensions and `sizes`. Never lazy-load the LCP image: give it `loading="eager"` and `fetchPriority="high"`, or `preload` when it's discovered late. `priority` is deprecated in Next.js 16. Everything below the fold stays lazy.
- Fonts come from `island/fonts` as variable woff2. Preload only the critical face, use `font-display: swap`, and use a size-adjusted fallback so the swap doesn't shift layout. `next/font/local` does both. - Fonts come from `island/fonts` as variable woff2. Preload only the critical face, use `font-display: swap`, and give each face a size-adjusted fallback face so the swap doesn't shift layout ([code-patterns.md](code-patterns.md#tokens-and-tailwind-wiring)). Never use `next/font`: it renames the files (next section).
- Reserve space for images, banners, ads, and embeds with fixed aspect ratios. - Reserve space for images, banners, ads, and embeds with fixed aspect ratios.
- Register every project whose components use Tailwind classes as a source (see code-patterns.md). - Register every project whose components use Tailwind classes as a source (see code-patterns.md).
### Fonts and the icon sprite
Fonts and the icon sprite change rarely, and every page needs them. A hash in their file names changes whenever a build step changes its output, such as a Next.js or svgo upgrade or a new loader option, even when the file itself didn't change. Every visitor then downloads them again. So they keep fixed names, and only a developer decides when visitors download them again.
- Names: fonts keep their own names, such as `yekan-bakh-vf.woff2`, and the sprite stays `symbol-defs.svg`. Each app serves them from `public/fonts/` and `public/icons/`.
- No step adds a hash to them or renames them: not the bundler, not the CSS pipeline, not `next/font` (it copies fonts to `_next/static/media/<hash>.woff2`), not `icon-sprite-plugin`, not a CDN upload. `fonts.css` names each file by its root path, `url('/fonts/yekan-bakh-vf.woff2')`, which Next.js leaves alone. A relative path such as `url('../fonts/...')` goes through the bundler and gets a hash.
- Fonts have no version. A font file never changes under its name: a changed font ships as a new file with a new name.
- The sprite has a version in its link, never in its file name: `/icons/symbol-defs.svg?v=1`. island `constants.ts` holds `ICON_SPRITE_VERSION` and the `ICON_SPRITE_URL` built from it, and the `Icon` atom points `<use href>` at `${ICON_SPRITE_URL}#${name}`. A new Icomoon import or a changed svgo config raises `ICON_SPRITE_VERSION` in the same commit. Never reuse or lower a version.
- The critical font's path lives in island `constants.ts` as `CRITICAL_FONT_URL`, and each root layout preloads it with `preload(CRITICAL_FONT_URL, { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' })`. The preload URL must equal the one in `fonts.css`, or the browser downloads the font twice.
- Serve them as immutable. Next.js serves `public/` with `Cache-Control: public, max-age=0`, so the browser asks again on every visit. Add this to the `headers()` in `next.config.ts`, and keep the same header on the CDN. The CDN must keep the query string in its cache key, or a new `?v=` still gets the old sprite.
```ts
const immutable = [{ key: 'Cache-Control', value: 'public, max-age=31536000, immutable' }];
// inside headers()
{ source: '/fonts/:path*', headers: immutable },
{ source: '/icons/:path*', headers: immutable },
```
## SEO and i18n ## SEO and i18n
- Build `generateMetadata` from `configs/seo.ts`: title, description, canonical URL, `hreflang` alternates, and Open Graph. Add JSON-LD for products, breadcrumbs, and the organization. Provide `sitemap.ts` and `robots.ts`. - Build `generateMetadata` from `configs/seo.ts`: title, description, canonical URL, `hreflang` alternates, and Open Graph. Add JSON-LD for products, breadcrumbs, and the organization. Provide `sitemap.ts` and `robots.ts`.

2
.gitignore vendored
View File

@ -26,7 +26,7 @@ build
.next .next
next-env.d.ts next-env.d.ts
.vercel .vercel
# Hashed fonts and icon sprite, written by island's asset plugin on next dev and next build (0008) # Fonts and icon sprite, written by island's font-copy and icon-sprite plugins on next dev and next build (0012)
apps/*/public/icons/ apps/*/public/icons/
apps/*/public/fonts/ apps/*/public/fonts/

View File

@ -6,10 +6,6 @@ NEXT_PUBLIC_BALE_HANDLE=lumina_support
NEXT_PUBLIC_TELEGRAM_HANDLE=lumina_support NEXT_PUBLIC_TELEGRAM_HANDLE=lumina_support
NEXT_PUBLIC_SUPPORT_HOURS=شنبه تا پنجشنبه، ۹ تا ۱۸ NEXT_PUBLIC_SUPPORT_HOURS=شنبه تا پنجشنبه، ۹ تا ۱۸
# Optional: the CDN origin, without a trailing slash, that serves public/fonts/ under the same paths.
# It must send Access-Control-Allow-Origin. The icon sprite always loads from the app's own origin.
NEXT_PUBLIC_CDN_ORIGIN=
# Server only: the API origin from inside the deployment network. # Server only: the API origin from inside the deployment network.
API_INTERNAL_ORIGIN=http://localhost:3000 API_INTERNAL_ORIGIN=http://localhost:3000

View File

@ -1,6 +1,13 @@
import { withIslandAssets } from '@lumina/island/tools/asset-plugin'; import { withFontCopy } from '@lumina/island/tools/font-copy-plugin';
import { withIconSprite } from '@lumina/island/tools/icon-sprite-plugin';
import type { NextConfig } from 'next'; import type { NextConfig } from 'next';
// Fonts and the icon sprite keep fixed names; a changed font gets a new name, and the sprite a new
// ?v= (0011, 0012). Next serves public/ with max-age=0, so without this every visit asks for them again.
const immutable = [
{ key: 'Cache-Control', value: 'public, max-age=31536000, immutable' },
];
const nextConfig: NextConfig = { const nextConfig: NextConfig = {
// Workspace packages export TypeScript source, so Next.js compiles them. // Workspace packages export TypeScript source, so Next.js compiles them.
transpilePackages: [ transpilePackages: [
@ -21,6 +28,12 @@ const nextConfig: NextConfig = {
}, },
]; ];
}, },
async headers() {
return [
{ source: '/fonts/:path*', headers: immutable },
{ source: '/icons/:path*', headers: immutable },
];
},
// One canonical URL per channel: send direct `/channels/…` hits to `/@…`. // One canonical URL per channel: send direct `/channels/…` hits to `/@…`.
async redirects() { async redirects() {
return [ return [
@ -33,5 +46,6 @@ const nextConfig: NextConfig = {
}, },
}; };
// On next dev and next build, writes island's hashed fonts and icon sprite into public/ (0008). // On next dev and next build, island's plugins write the fonts and icon sprite into public/
export default withIslandAssets(nextConfig); // under their fixed names, with no hash (0012).
export default withIconSprite(withFontCopy(nextConfig));

View File

@ -1,3 +1,3 @@
'use client'; 'use client';
export { PageError as default } from '../organisms/page-error'; export { PageError as default } from '@lumina/market/app/screens/organisms/page-error';

View File

@ -1,3 +1,3 @@
'use client'; 'use client';
export { PageError as default } from '../organisms/page-error'; export { PageError as default } from '@lumina/market/app/screens/organisms/page-error';

View File

@ -1,3 +1,3 @@
'use client'; 'use client';
export { PageError as default } from '../organisms/page-error'; export { PageError as default } from '@lumina/market/app/screens/organisms/page-error';

View File

@ -1,3 +1,3 @@
'use client'; 'use client';
export { PageError as default } from '../organisms/page-error'; export { PageError as default } from '@lumina/market/app/screens/organisms/page-error';

View File

@ -8,7 +8,6 @@ import { Element } from '@lumina/island/primitives/element';
import { ErrorFallback } from '@lumina/market/app/error-boundaries'; import { ErrorFallback } from '@lumina/market/app/error-boundaries';
import { i18n } from '../i18n/i18n.client'; import { i18n } from '../i18n/i18n.client';
import { yekanBakh } from '../styles';
type GlobalErrorProps = { type GlobalErrorProps = {
error: Error & { digest?: string }; error: Error & { digest?: string };
@ -17,12 +16,7 @@ type GlobalErrorProps = {
/** The app boundary (EB-W): the last resort when nothing below caught the error. */ /** The app boundary (EB-W): the last resort when nothing below caught the error. */
export default function GlobalError({ error }: GlobalErrorProps) { export default function GlobalError({ error }: GlobalErrorProps) {
return ( return (
<Element <Element tag="html" lang={i18n.language} dir={i18n.dir()}>
tag="html"
lang={i18n.language}
dir={i18n.dir()}
className={yekanBakh.variable}
>
<Element tag="body"> <Element tag="body">
<Element tag="meta" name="robots" content="noindex" /> <Element tag="meta" name="robots" content="noindex" />
<ErrorFallback <ErrorFallback

View File

@ -2,13 +2,14 @@
import '../bootstrap/bootstrap.server'; import '../bootstrap/bootstrap.server';
import '../styles/app.css'; import '../styles/app.css';
import { CRITICAL_FONT_URL } from '@lumina/island/constants';
import { Element } from '@lumina/island/primitives/element'; import { Element } from '@lumina/island/primitives/element';
import type { Metadata } from 'next'; import type { Metadata } from 'next';
import type { ReactNode } from 'react'; import type { ReactNode } from 'react';
import { preload } from 'react-dom';
import { rootMetadata } from '../configs'; import { rootMetadata } from '../configs';
import { i18n } from '../i18n'; import { i18n } from '../i18n';
import { yekanBakh, yekanBakhLatin } from '../styles';
import { AppProviders } from './organisms/app-providers'; import { AppProviders } from './organisms/app-providers';
export function generateMetadata(): Metadata { export function generateMetadata(): Metadata {
@ -16,13 +17,15 @@ export function generateMetadata(): Metadata {
} }
export default function RootLayout({ children }: { children: ReactNode }) { export default function RootLayout({ children }: { children: ReactNode }) {
// Only the face every page renders first; the Latin face loads where شبا is shown.
preload(CRITICAL_FONT_URL, {
as: 'font',
type: 'font/woff2',
crossOrigin: 'anonymous',
});
return ( return (
<Element <Element tag="html" lang={i18n.language} dir={i18n.dir()}>
tag="html"
lang={i18n.language}
dir={i18n.dir()}
className={`${yekanBakh.variable} ${yekanBakhLatin.variable}`}
>
<Element tag="body"> <Element tag="body">
<AppProviders>{children}</AppProviders> <AppProviders>{children}</AppProviders>
</Element> </Element>

View File

@ -1,6 +1,5 @@
import { configureErrorHandler } from '@lumina/libs/error-handler'; import { configureErrorHandler } from '@lumina/libs/error-handler';
import { eventEmitter } from '@lumina/libs/event-emitter'; import { eventEmitter } from '@lumina/libs/event-emitter';
import { setEnv as setIslandEnv } from '@lumina/island/env';
import { http } from '@lumina/libs/http'; import { http } from '@lumina/libs/http';
import { mapApiErrorBody } from '@lumina/market/app/http'; import { mapApiErrorBody } from '@lumina/market/app/http';
import { setEnv as setMarketEnv } from '@lumina/market/env'; import { setEnv as setMarketEnv } from '@lumina/market/env';
@ -9,7 +8,6 @@ import { AUTH_ENDPOINTS, AUTH_EVENTS } from '@lumina/market/features/auth';
import { API_VERSION_PATH } from '../constants'; import { API_VERSION_PATH } from '../constants';
import { clientEnv } from '../env'; import { clientEnv } from '../env';
import { ERROR_HANDLER_CONFIG } from './error-reporting'; import { ERROR_HANDLER_CONFIG } from './error-reporting';
import { ISLAND_ENV } from './island-env';
// Fills the client module graph with public values only, before client components render (during // Fills the client module graph with public values only, before client components render (during
// SSR and in the browser). Idempotent: safe to run again. // SSR and in the browser). Idempotent: safe to run again.
@ -19,7 +17,6 @@ setMarketEnv({
telegramHandle: clientEnv.NEXT_PUBLIC_TELEGRAM_HANDLE, telegramHandle: clientEnv.NEXT_PUBLIC_TELEGRAM_HANDLE,
supportHours: clientEnv.NEXT_PUBLIC_SUPPORT_HOURS, supportHours: clientEnv.NEXT_PUBLIC_SUPPORT_HOURS,
}); });
setIslandEnv(ISLAND_ENV);
// The session lives in HttpOnly cookies the browser sends itself. A 401 runs one refresh for the // The session lives in HttpOnly cookies the browser sends itself. A 401 runs one refresh for the
// whole app; when that fails the session is over and the shell signs the user out. // whole app; when that fails the session is over and the shell signs the user out.
http.configure({ http.configure({

View File

@ -1,6 +1,5 @@
import 'server-only'; import 'server-only';
import { setEnv as setIslandEnv } from '@lumina/island/env';
import { configureErrorHandler } from '@lumina/libs/error-handler'; import { configureErrorHandler } from '@lumina/libs/error-handler';
import { http } from '@lumina/libs/http'; import { http } from '@lumina/libs/http';
import { configureServerHttp } from '@lumina/libs/server'; import { configureServerHttp } from '@lumina/libs/server';
@ -12,7 +11,6 @@ import { API_VERSION_PATH, FORWARDED_COOKIES } from '../constants';
import { clientEnv } from '../env'; import { clientEnv } from '../env';
import { serverEnv } from '../env/server'; import { serverEnv } from '../env/server';
import { ERROR_HANDLER_CONFIG } from './error-reporting'; import { ERROR_HANDLER_CONFIG } from './error-reporting';
import { ISLAND_ENV } from './island-env';
// Fills the server module graph once, before rendering. Idempotent: safe to run again. // Fills the server module graph once, before rendering. Idempotent: safe to run again.
setMarketEnv({ setMarketEnv({
@ -21,7 +19,6 @@ setMarketEnv({
telegramHandle: clientEnv.NEXT_PUBLIC_TELEGRAM_HANDLE, telegramHandle: clientEnv.NEXT_PUBLIC_TELEGRAM_HANDLE,
supportHours: clientEnv.NEXT_PUBLIC_SUPPORT_HOURS, supportHours: clientEnv.NEXT_PUBLIC_SUPPORT_HOURS,
}); });
setIslandEnv(ISLAND_ENV);
// Server requests forward only the allowlisted cookies, never the session: the server render is // Server requests forward only the allowlisted cookies, never the session: the server render is
// the same for every visitor, and the browser loads whatever depends on the viewer. Read on each // the same for every visitor, and the browser loads whatever depends on the viewer. Read on each
// request; nothing per visitor is kept in module state. // request; nothing per visitor is kept in module state.

View File

@ -1,18 +0,0 @@
import type { IslandEnv } from '@lumina/island/env';
import { clientEnv } from '../env';
const cdnOrigin = clientEnv.NEXT_PUBLIC_CDN_ORIGIN ?? '';
/**
* island's settings for both sides, from the hashed paths its asset plugin wrote into `public/`.
* Fonts may load from the CDN under the same paths; the sprite never does, because `<use href>`
* only loads same-origin.
*/
export const ISLAND_ENV: IslandEnv = {
iconSpritePath: clientEnv.NEXT_PUBLIC_ISLAND_ICON_SPRITE_PATH,
fontUrls: {
sans: `${cdnOrigin}${clientEnv.NEXT_PUBLIC_ISLAND_FONT_SANS_PATH}`,
latin: `${cdnOrigin}${clientEnv.NEXT_PUBLIC_ISLAND_FONT_LATIN_PATH}`,
},
};

View File

@ -3,7 +3,6 @@ import * as v from 'valibot';
const required = v.pipe(v.string(), v.nonEmpty()); const required = v.pipe(v.string(), v.nonEmpty());
const url = v.pipe(v.string(), v.url()); const url = v.pipe(v.string(), v.url());
const rootPath = v.pipe(v.string(), v.startsWith('/'));
/** Public variables, inlined into the browser bundle. Next.js inlines only literal reads. */ /** Public variables, inlined into the browser bundle. Next.js inlines only literal reads. */
export const clientEnv = createClientEnv({ export const clientEnv = createClientEnv({
@ -14,11 +13,6 @@ export const clientEnv = createClientEnv({
NEXT_PUBLIC_BALE_HANDLE: required, NEXT_PUBLIC_BALE_HANDLE: required,
NEXT_PUBLIC_TELEGRAM_HANDLE: required, NEXT_PUBLIC_TELEGRAM_HANDLE: required,
NEXT_PUBLIC_SUPPORT_HOURS: required, NEXT_PUBLIC_SUPPORT_HOURS: required,
NEXT_PUBLIC_CDN_ORIGIN: v.optional(url),
// Written by island's asset plugin in next.config, never set in .env.
NEXT_PUBLIC_ISLAND_ICON_SPRITE_PATH: rootPath,
NEXT_PUBLIC_ISLAND_FONT_SANS_PATH: rootPath,
NEXT_PUBLIC_ISLAND_FONT_LATIN_PATH: rootPath,
}, },
runtimeEnv: { runtimeEnv: {
NEXT_PUBLIC_API_ORIGIN: process.env.NEXT_PUBLIC_API_ORIGIN, NEXT_PUBLIC_API_ORIGIN: process.env.NEXT_PUBLIC_API_ORIGIN,
@ -26,12 +20,5 @@ export const clientEnv = createClientEnv({
NEXT_PUBLIC_BALE_HANDLE: process.env.NEXT_PUBLIC_BALE_HANDLE, NEXT_PUBLIC_BALE_HANDLE: process.env.NEXT_PUBLIC_BALE_HANDLE,
NEXT_PUBLIC_TELEGRAM_HANDLE: process.env.NEXT_PUBLIC_TELEGRAM_HANDLE, NEXT_PUBLIC_TELEGRAM_HANDLE: process.env.NEXT_PUBLIC_TELEGRAM_HANDLE,
NEXT_PUBLIC_SUPPORT_HOURS: process.env.NEXT_PUBLIC_SUPPORT_HOURS, NEXT_PUBLIC_SUPPORT_HOURS: process.env.NEXT_PUBLIC_SUPPORT_HOURS,
NEXT_PUBLIC_CDN_ORIGIN: process.env.NEXT_PUBLIC_CDN_ORIGIN,
NEXT_PUBLIC_ISLAND_ICON_SPRITE_PATH:
process.env.NEXT_PUBLIC_ISLAND_ICON_SPRITE_PATH,
NEXT_PUBLIC_ISLAND_FONT_SANS_PATH:
process.env.NEXT_PUBLIC_ISLAND_FONT_SANS_PATH,
NEXT_PUBLIC_ISLAND_FONT_LATIN_PATH:
process.env.NEXT_PUBLIC_ISLAND_FONT_LATIN_PATH,
}, },
}); });

View File

@ -1,23 +0,0 @@
import localFont from 'next/font/local';
// Variable fonts from island. next/font self-hosts them, preloads the critical face,
// and adds a size-adjusted fallback so the swap doesn't shift the layout.
/** Yekan Bakh with Persian digit shapes: every UI text. */
export const yekanBakh = localFont({
src: '../../../../packages/island/src/fonts/yekan-bakh-fa-num-vf.woff2',
variable: '--font-yekan-bakh',
weight: '100 1000',
display: 'swap',
adjustFontFallback: 'Arial',
});
/** Yekan Bakh with Latin digits: شبا and other bank codes. Loaded only where used. */
export const yekanBakhLatin = localFont({
src: '../../../../packages/island/src/fonts/yekan-bakh-vf.woff2',
variable: '--font-yekan-bakh-latin',
weight: '100 1000',
display: 'swap',
preload: false,
adjustFontFallback: 'Arial',
});

View File

@ -1 +0,0 @@
export { yekanBakh, yekanBakhLatin } from './fonts';

View File

@ -6,10 +6,6 @@ NEXT_PUBLIC_BALE_HANDLE=lumina_support
NEXT_PUBLIC_TELEGRAM_HANDLE=lumina_support NEXT_PUBLIC_TELEGRAM_HANDLE=lumina_support
NEXT_PUBLIC_SUPPORT_HOURS=شنبه تا پنجشنبه، ۹ تا ۱۸ NEXT_PUBLIC_SUPPORT_HOURS=شنبه تا پنجشنبه، ۹ تا ۱۸
# Optional: the CDN origin, without a trailing slash, that serves public/fonts/ under the same paths.
# It must send Access-Control-Allow-Origin. The icon sprite always loads from the app's own origin.
NEXT_PUBLIC_CDN_ORIGIN=
# Server only: the API origin from inside the deployment network. # Server only: the API origin from inside the deployment network.
API_INTERNAL_ORIGIN=http://localhost:3000 API_INTERNAL_ORIGIN=http://localhost:3000

View File

@ -1,6 +1,13 @@
import { withIslandAssets } from '@lumina/island/tools/asset-plugin'; import { withFontCopy } from '@lumina/island/tools/font-copy-plugin';
import { withIconSprite } from '@lumina/island/tools/icon-sprite-plugin';
import type { NextConfig } from 'next'; import type { NextConfig } from 'next';
// Fonts and the icon sprite keep fixed names; a changed font gets a new name, and the sprite a new
// ?v= (0011, 0012). Next serves public/ with max-age=0, so without this every visit asks for them again.
const immutable = [
{ key: 'Cache-Control', value: 'public, max-age=31536000, immutable' },
];
const nextConfig: NextConfig = { const nextConfig: NextConfig = {
// Workspace packages export TypeScript source, so Next.js compiles them. // Workspace packages export TypeScript source, so Next.js compiles them.
transpilePackages: [ transpilePackages: [
@ -21,6 +28,12 @@ const nextConfig: NextConfig = {
}, },
]; ];
}, },
async headers() {
return [
{ source: '/fonts/:path*', headers: immutable },
{ source: '/icons/:path*', headers: immutable },
];
},
// One canonical URL per channel: send direct `/channels/…` hits to `/@…`. // One canonical URL per channel: send direct `/channels/…` hits to `/@…`.
async redirects() { async redirects() {
return [ return [
@ -33,5 +46,6 @@ const nextConfig: NextConfig = {
}, },
}; };
// On next dev and next build, writes island's hashed fonts and icon sprite into public/ (0008). // On next dev and next build, island's plugins write the fonts and icon sprite into public/
export default withIslandAssets(nextConfig); // under their fixed names, with no hash (0012).
export default withIconSprite(withFontCopy(nextConfig));

View File

@ -1,3 +1,3 @@
'use client'; 'use client';
export { PageError as default } from '../organisms/page-error'; export { PageError as default } from '@lumina/market/app/screens/organisms/page-error';

View File

@ -1,3 +1,3 @@
'use client'; 'use client';
export { PageError as default } from '../organisms/page-error'; export { PageError as default } from '@lumina/market/app/screens/organisms/page-error';

View File

@ -1,3 +1,3 @@
'use client'; 'use client';
export { PageError as default } from '../organisms/page-error'; export { PageError as default } from '@lumina/market/app/screens/organisms/page-error';

View File

@ -1,3 +1,3 @@
'use client'; 'use client';
export { PageError as default } from '../organisms/page-error'; export { PageError as default } from '@lumina/market/app/screens/organisms/page-error';

View File

@ -8,7 +8,6 @@ import { Element } from '@lumina/island/primitives/element';
import { ErrorFallback } from '@lumina/market/app/error-boundaries'; import { ErrorFallback } from '@lumina/market/app/error-boundaries';
import { i18n } from '../i18n/i18n.client'; import { i18n } from '../i18n/i18n.client';
import { yekanBakh } from '../styles';
type GlobalErrorProps = { type GlobalErrorProps = {
error: Error & { digest?: string }; error: Error & { digest?: string };
@ -17,12 +16,7 @@ type GlobalErrorProps = {
/** The app boundary (EB-W): the last resort when nothing below caught the error. */ /** The app boundary (EB-W): the last resort when nothing below caught the error. */
export default function GlobalError({ error }: GlobalErrorProps) { export default function GlobalError({ error }: GlobalErrorProps) {
return ( return (
<Element <Element tag="html" lang={i18n.language} dir={i18n.dir()}>
tag="html"
lang={i18n.language}
dir={i18n.dir()}
className={yekanBakh.variable}
>
<Element tag="body"> <Element tag="body">
<Element tag="meta" name="robots" content="noindex" /> <Element tag="meta" name="robots" content="noindex" />
<ErrorFallback <ErrorFallback

View File

@ -2,13 +2,14 @@
import '../bootstrap/bootstrap.server'; import '../bootstrap/bootstrap.server';
import '../styles/app.css'; import '../styles/app.css';
import { CRITICAL_FONT_URL } from '@lumina/island/constants';
import { Element } from '@lumina/island/primitives/element'; import { Element } from '@lumina/island/primitives/element';
import type { Metadata } from 'next'; import type { Metadata } from 'next';
import type { ReactNode } from 'react'; import type { ReactNode } from 'react';
import { preload } from 'react-dom';
import { rootMetadata } from '../configs'; import { rootMetadata } from '../configs';
import { i18n } from '../i18n'; import { i18n } from '../i18n';
import { yekanBakh, yekanBakhLatin } from '../styles';
import { AppProviders } from './organisms/app-providers'; import { AppProviders } from './organisms/app-providers';
export function generateMetadata(): Metadata { export function generateMetadata(): Metadata {
@ -16,13 +17,15 @@ export function generateMetadata(): Metadata {
} }
export default function RootLayout({ children }: { children: ReactNode }) { export default function RootLayout({ children }: { children: ReactNode }) {
// Only the face every page renders first; the Latin face loads where شبا is shown.
preload(CRITICAL_FONT_URL, {
as: 'font',
type: 'font/woff2',
crossOrigin: 'anonymous',
});
return ( return (
<Element <Element tag="html" lang={i18n.language} dir={i18n.dir()}>
tag="html"
lang={i18n.language}
dir={i18n.dir()}
className={`${yekanBakh.variable} ${yekanBakhLatin.variable}`}
>
<Element tag="body"> <Element tag="body">
<AppProviders>{children}</AppProviders> <AppProviders>{children}</AppProviders>
</Element> </Element>

View File

@ -1,30 +0,0 @@
'use client';
import { Element } from '@lumina/island/primitives/element';
import { ErrorFallback } from '@lumina/market/app/error-boundaries';
import { useQueryErrorResetBoundary } from '@tanstack/react-query';
import type { PageErrorProps } from './types';
/**
* The page-size boundary (EB-S) every route group's error.tsx renders, inside the shell, so a
* failed page keeps the bars usable. Try again resets the failed queries first, or they would
* throw again at once. Never indexed.
*/
export function PageError({ error, retry }: PageErrorProps) {
const queryErrors = useQueryErrorResetBoundary();
return (
<>
<Element tag="meta" name="robots" content="noindex" />
<ErrorFallback
error={error}
size="page"
onRetry={() => {
queryErrors.reset();
retry();
}}
/>
</>
);
}

View File

@ -1,2 +0,0 @@
export { PageError } from './PageError';
export type { PageErrorProps } from './types';

View File

@ -1,5 +0,0 @@
export type PageErrorProps = {
error: Error & { digest?: string };
/** Next.js re-fetches and re-renders the segment. */
retry: () => void;
};

View File

@ -1,6 +1,5 @@
import { configureErrorHandler } from '@lumina/libs/error-handler'; import { configureErrorHandler } from '@lumina/libs/error-handler';
import { eventEmitter } from '@lumina/libs/event-emitter'; import { eventEmitter } from '@lumina/libs/event-emitter';
import { setEnv as setIslandEnv } from '@lumina/island/env';
import { http } from '@lumina/libs/http'; import { http } from '@lumina/libs/http';
import { mapApiErrorBody } from '@lumina/market/app/http'; import { mapApiErrorBody } from '@lumina/market/app/http';
import { setEnv as setMarketEnv } from '@lumina/market/env'; import { setEnv as setMarketEnv } from '@lumina/market/env';
@ -9,7 +8,6 @@ import { AUTH_ENDPOINTS, AUTH_EVENTS } from '@lumina/market/features/auth';
import { API_VERSION_PATH } from '../constants'; import { API_VERSION_PATH } from '../constants';
import { clientEnv } from '../env'; import { clientEnv } from '../env';
import { ERROR_HANDLER_CONFIG } from './error-reporting'; import { ERROR_HANDLER_CONFIG } from './error-reporting';
import { ISLAND_ENV } from './island-env';
// Fills the client module graph with public values only, before client components render (during // Fills the client module graph with public values only, before client components render (during
// SSR and in the browser). Idempotent: safe to run again. // SSR and in the browser). Idempotent: safe to run again.
@ -19,7 +17,6 @@ setMarketEnv({
telegramHandle: clientEnv.NEXT_PUBLIC_TELEGRAM_HANDLE, telegramHandle: clientEnv.NEXT_PUBLIC_TELEGRAM_HANDLE,
supportHours: clientEnv.NEXT_PUBLIC_SUPPORT_HOURS, supportHours: clientEnv.NEXT_PUBLIC_SUPPORT_HOURS,
}); });
setIslandEnv(ISLAND_ENV);
// The session lives in HttpOnly cookies the browser sends itself. A 401 runs one refresh for the // The session lives in HttpOnly cookies the browser sends itself. A 401 runs one refresh for the
// whole app; when that fails the session is over and the shell signs the user out. // whole app; when that fails the session is over and the shell signs the user out.
http.configure({ http.configure({

View File

@ -1,6 +1,5 @@
import 'server-only'; import 'server-only';
import { setEnv as setIslandEnv } from '@lumina/island/env';
import { configureErrorHandler } from '@lumina/libs/error-handler'; import { configureErrorHandler } from '@lumina/libs/error-handler';
import { http } from '@lumina/libs/http'; import { http } from '@lumina/libs/http';
import { configureServerHttp } from '@lumina/libs/server'; import { configureServerHttp } from '@lumina/libs/server';
@ -12,7 +11,6 @@ import { API_VERSION_PATH, FORWARDED_COOKIES } from '../constants';
import { clientEnv } from '../env'; import { clientEnv } from '../env';
import { serverEnv } from '../env/server'; import { serverEnv } from '../env/server';
import { ERROR_HANDLER_CONFIG } from './error-reporting'; import { ERROR_HANDLER_CONFIG } from './error-reporting';
import { ISLAND_ENV } from './island-env';
// Fills the server module graph once, before rendering. Idempotent: safe to run again. // Fills the server module graph once, before rendering. Idempotent: safe to run again.
setMarketEnv({ setMarketEnv({
@ -21,7 +19,6 @@ setMarketEnv({
telegramHandle: clientEnv.NEXT_PUBLIC_TELEGRAM_HANDLE, telegramHandle: clientEnv.NEXT_PUBLIC_TELEGRAM_HANDLE,
supportHours: clientEnv.NEXT_PUBLIC_SUPPORT_HOURS, supportHours: clientEnv.NEXT_PUBLIC_SUPPORT_HOURS,
}); });
setIslandEnv(ISLAND_ENV);
// Server requests forward only the allowlisted cookies, never the session: the server render is // Server requests forward only the allowlisted cookies, never the session: the server render is
// the same for every visitor, and the browser loads whatever depends on the viewer. Read on each // the same for every visitor, and the browser loads whatever depends on the viewer. Read on each
// request; nothing per visitor is kept in module state. // request; nothing per visitor is kept in module state.

View File

@ -1,18 +0,0 @@
import type { IslandEnv } from '@lumina/island/env';
import { clientEnv } from '../env';
const cdnOrigin = clientEnv.NEXT_PUBLIC_CDN_ORIGIN ?? '';
/**
* island's settings for both sides, from the hashed paths its asset plugin wrote into `public/`.
* Fonts may load from the CDN under the same paths; the sprite never does, because `<use href>`
* only loads same-origin.
*/
export const ISLAND_ENV: IslandEnv = {
iconSpritePath: clientEnv.NEXT_PUBLIC_ISLAND_ICON_SPRITE_PATH,
fontUrls: {
sans: `${cdnOrigin}${clientEnv.NEXT_PUBLIC_ISLAND_FONT_SANS_PATH}`,
latin: `${cdnOrigin}${clientEnv.NEXT_PUBLIC_ISLAND_FONT_LATIN_PATH}`,
},
};

View File

@ -3,7 +3,6 @@ import * as v from 'valibot';
const required = v.pipe(v.string(), v.nonEmpty()); const required = v.pipe(v.string(), v.nonEmpty());
const url = v.pipe(v.string(), v.url()); const url = v.pipe(v.string(), v.url());
const rootPath = v.pipe(v.string(), v.startsWith('/'));
/** Public variables, inlined into the browser bundle. Next.js inlines only literal reads. */ /** Public variables, inlined into the browser bundle. Next.js inlines only literal reads. */
export const clientEnv = createClientEnv({ export const clientEnv = createClientEnv({
@ -14,11 +13,6 @@ export const clientEnv = createClientEnv({
NEXT_PUBLIC_BALE_HANDLE: required, NEXT_PUBLIC_BALE_HANDLE: required,
NEXT_PUBLIC_TELEGRAM_HANDLE: required, NEXT_PUBLIC_TELEGRAM_HANDLE: required,
NEXT_PUBLIC_SUPPORT_HOURS: required, NEXT_PUBLIC_SUPPORT_HOURS: required,
NEXT_PUBLIC_CDN_ORIGIN: v.optional(url),
// Written by island's asset plugin in next.config, never set in .env.
NEXT_PUBLIC_ISLAND_ICON_SPRITE_PATH: rootPath,
NEXT_PUBLIC_ISLAND_FONT_SANS_PATH: rootPath,
NEXT_PUBLIC_ISLAND_FONT_LATIN_PATH: rootPath,
}, },
runtimeEnv: { runtimeEnv: {
NEXT_PUBLIC_API_ORIGIN: process.env.NEXT_PUBLIC_API_ORIGIN, NEXT_PUBLIC_API_ORIGIN: process.env.NEXT_PUBLIC_API_ORIGIN,
@ -26,12 +20,5 @@ export const clientEnv = createClientEnv({
NEXT_PUBLIC_BALE_HANDLE: process.env.NEXT_PUBLIC_BALE_HANDLE, NEXT_PUBLIC_BALE_HANDLE: process.env.NEXT_PUBLIC_BALE_HANDLE,
NEXT_PUBLIC_TELEGRAM_HANDLE: process.env.NEXT_PUBLIC_TELEGRAM_HANDLE, NEXT_PUBLIC_TELEGRAM_HANDLE: process.env.NEXT_PUBLIC_TELEGRAM_HANDLE,
NEXT_PUBLIC_SUPPORT_HOURS: process.env.NEXT_PUBLIC_SUPPORT_HOURS, NEXT_PUBLIC_SUPPORT_HOURS: process.env.NEXT_PUBLIC_SUPPORT_HOURS,
NEXT_PUBLIC_CDN_ORIGIN: process.env.NEXT_PUBLIC_CDN_ORIGIN,
NEXT_PUBLIC_ISLAND_ICON_SPRITE_PATH:
process.env.NEXT_PUBLIC_ISLAND_ICON_SPRITE_PATH,
NEXT_PUBLIC_ISLAND_FONT_SANS_PATH:
process.env.NEXT_PUBLIC_ISLAND_FONT_SANS_PATH,
NEXT_PUBLIC_ISLAND_FONT_LATIN_PATH:
process.env.NEXT_PUBLIC_ISLAND_FONT_LATIN_PATH,
}, },
}); });

View File

@ -1,23 +0,0 @@
import localFont from 'next/font/local';
// Variable fonts from island. next/font self-hosts them, preloads the critical face,
// and adds a size-adjusted fallback so the swap doesn't shift the layout.
/** Yekan Bakh with Persian digit shapes: every UI text. */
export const yekanBakh = localFont({
src: '../../../../packages/island/src/fonts/yekan-bakh-fa-num-vf.woff2',
variable: '--font-yekan-bakh',
weight: '100 1000',
display: 'swap',
adjustFontFallback: 'Arial',
});
/** Yekan Bakh with Latin digits: شبا and other bank codes. Loaded only where used. */
export const yekanBakhLatin = localFont({
src: '../../../../packages/island/src/fonts/yekan-bakh-vf.woff2',
variable: '--font-yekan-bakh-latin',
weight: '100 1000',
display: 'swap',
preload: false,
adjustFontFallback: 'Arial',
});

View File

@ -1 +0,0 @@
export { yekanBakh, yekanBakhLatin } from './fonts';

View File

@ -1,11 +1,13 @@
# 0007 Yekan Bakh served from the app's public folder or a CDN # 0007 Yekan Bakh served from the app's public folder or a CDN
Status: Accepted · Area: design · Date: 2026-10-04 · Decided by: user · Supersedes: 0004 Status: Superseded by 0009 · Area: design · Date: 2026-10-04 · Decided by: user · Supersedes: 0004
## Context ## Context
Lumina uses two variable faces from `packages/island/src/fonts/`: Yekan Bakh FaNum (`yekan-bakh-fa-num-vf.woff2`), which draws Latin digits as Persian, and Yekan Bakh (`yekan-bakh-vf.woff2`), which keeps Latin digits. 0004 loaded them with `next/font/local`, which serves them only from `/_next/static/media`. The user wants fonts served as plain files from each app's `public/` or from a CDN, put there by a plugin (0008). Lumina uses two variable faces from `packages/island/src/fonts/`: Yekan Bakh FaNum (`yekan-bakh-fa-num-vf.woff2`), which draws Latin digits as Persian, and Yekan Bakh (`yekan-bakh-vf.woff2`), which keeps Latin digits. 0004 loaded them with `next/font/local`, which serves them only from `/_next/static/media`. The user wants fonts served as plain files from each app's `public/` or from a CDN, put there by a plugin (0008).
## Decision ## Decision
- `font-sans` is Yekan Bakh FaNum, for every UI text. Formatters output Latin digits, which the font draws as Persian, and insert `٬` and `٫` themselves, because the font doesn't map `,` and `.`. - `font-sans` is Yekan Bakh FaNum, for every UI text. Formatters output Latin digits, which the font draws as Persian, and insert `٬` and `٫` themselves, because the font doesn't map `,` and `.`.
- `font-latin` is Yekan Bakh, only for text that must show Latin digits: شبا and other codes banks print in Latin digits. - `font-latin` is Yekan Bakh, only for text that must show Latin digits: شبا and other codes banks print in Latin digits.
- Serve both as content-hashed files from the app's `public/fonts/`, or from a CDN under the same paths. Never use `next/font`, and never use a public third-party font CDN. - Serve both as content-hashed files from the app's `public/fonts/`, or from a CDN under the same paths. Never use `next/font`, and never use a public third-party font CDN.
@ -14,9 +16,11 @@ Lumina uses two variable faces from `packages/island/src/fonts/`: Yekan Bakh FaN
- A CDN on another origin must send `Access-Control-Allow-Origin`, because browsers fetch `@font-face` URLs in CORS mode. - A CDN on another origin must send `Access-Control-Allow-Origin`, because browsers fetch `@font-face` URLs in CORS mode.
## Alternatives ## Alternatives
- `next/font/local` with `assetPrefix` for the CDN (0004): it gives hashing, preload, and fallback metrics for free, but fonts can't live in `public/`. - `next/font/local` with `assetPrefix` for the CDN (0004): it gives hashing, preload, and fallback metrics for free, but fonts can't live in `public/`.
## Consequences ## Consequences
- We now own what `next/font` did: hashed names and immutable `Cache-Control` (the asset plugin), the preload (`FontFaces`), and the fallback metrics (`FONT_FALLBACK` in island `constants.ts`, measured on Persian text). - We now own what `next/font` did: hashed names and immutable `Cache-Control` (the asset plugin), the preload (`FontFaces`), and the fallback metrics (`FONT_FALLBACK` in island `constants.ts`, measured on Persian text).
- The font is licensed. "Never a public CDN" means only the company's own CDN. Confirm the licence covers web embedding from that CDN. - The font is licensed. "Never a public CDN" means only the company's own CDN. Confirm the licence covers web embedding from that CDN.
- Debt: both apps still load the faces with `next/font/local` in `src/styles/fonts.ts`, and `island.css` says so. `FontFaces` and `FONT_FALLBACK` don't exist yet; island env and the asset plugin do, and already write and pass the hashed font URLs. - Debt: both apps still load the faces with `next/font/local` in `src/styles/fonts.ts`, and `island.css` says so. `FontFaces` and `FONT_FALLBACK` don't exist yet; island env and the asset plugin do, and already write and pass the hashed font URLs.

View File

@ -1,11 +1,13 @@
# 0008 Island asset plugin in each app's next.config # 0008 Island asset plugin in each app's next.config
Status: Accepted · Area: architecture · Date: 2026-10-04 · Decided by: user Status: Superseded by 0010 · Area: architecture · Date: 2026-10-04 · Decided by: user
## Context ## Context
Fonts (0007) and the icon sprite live in island, but browsers load them from each app's `public/` or a CDN. Something must put them there in dev and in build. Fonts (0007) and the icon sprite live in island, but browsers load them from each app's `public/` or a CDN. Something must put them there in dev and in build.
## Decision ## Decision
- Island ships one build-time plugin, `withIslandAssets` in `tools/asset-plugin` (it replaces the planned `icon-sprite-plugin`). Each app wraps its `next.config.ts` export with it. - Island ships one build-time plugin, `withIslandAssets` in `tools/asset-plugin` (it replaces the planned `icon-sprite-plugin`). Each app wraps its `next.config.ts` export with it.
- On `next dev` and `next build` (gated on `PHASE_DEVELOPMENT_SERVER` and `PHASE_PRODUCTION_BUILD`), it writes into the app's `public/`: - On `next dev` and `next build` (gated on `PHASE_DEVELOPMENT_SERVER` and `PHASE_PRODUCTION_BUILD`), it writes into the app's `public/`:
- the fonts, under content-hashed names; - the fonts, under content-hashed names;
@ -17,10 +19,12 @@ Fonts (0007) and the icon sprite live in island, but browsers load them from eac
- The sprite always loads from a root-relative, same-origin URL (`/icons/symbol-defs.<hash>.svg#icon-x`). `<use href>` is same-origin only in every engine, and CORS can't change that. To serve it through a CDN, put the CDN in front of the app's own domain, or add a `beforeFiles` rewrite. Never use an absolute CDN URL or `assetPrefix`. - The sprite always loads from a root-relative, same-origin URL (`/icons/symbol-defs.<hash>.svg#icon-x`). `<use href>` is same-origin only in every engine, and CORS can't change that. To serve it through a CDN, put the CDN in front of the app's own domain, or add a `beforeFiles` rewrite. Never use an absolute CDN URL or `assetPrefix`.
## Alternatives ## Alternatives
- An Nx target or `predev`/`prebuild` script: runs exactly once per command, but the user chose the next.config plugin. - An Nx target or `predev`/`prebuild` script: runs exactly once per command, but the user chose the next.config plugin.
- Inlining the sprite in the root layout: no request, but it adds weight to every HTML response. - Inlining the sprite in the root layout: no request, but it adds weight to every HTML response.
## Consequences ## Consequences
- Every app gets fonts and icons by registering one plugin; island stays the single source. - Every app gets fonts and icons by registering one plugin; island stays the single source.
- In dev, edits to island assets need a dev-server restart (Next watches only next.config), unless the plugin adds a watcher. - In dev, edits to island assets need a dev-server restart (Next watches only next.config), unless the plugin adds a watcher.
- Other phases, `next start` included, get the config back unchanged: the build already inlined `env` and wrote the headers into its routes manifest, so production needs neither island's sources nor svgo. `next typegen` and other build-phase commands still run it. - Other phases, `next start` included, get the config back unchanged: the build already inlined `env` and wrote the headers into its routes manifest, so production needs neither island's sources nor svgo. `next typegen` and other build-phase commands still run it.

View File

@ -0,0 +1,27 @@
# 0009 Yekan Bakh under versioned names, never hashed
Status: Superseded by 0011 · Area: design · Date: 2026-10-05 · Decided by: user · Supersedes: 0007
## Context
0007 served the fonts under content-hashed names, and the apps still loaded them with `next/font`, which hashes them again into `/_next/static/media/`. A hash changes whenever a build step changes its output, such as a Next.js upgrade, even when the font didn't change. Every visitor then downloads the fonts again, though the cached copy was still correct.
## Decision
- `font-sans` is Yekan Bakh FaNum, for every UI text. `font-latin` is Yekan Bakh, only for شبا and other codes that banks print in Latin digits.
- Name each font file `<name>.v<N>.woff2` in island `fonts/`. Serve it from each app's `public/fonts/` under that exact name, with `Cache-Control: public, max-age=31536000, immutable`. No step hashes or renames it, `next/font` included.
- Declare the faces in island `styles/fonts.css`, with root paths (`url('/fonts/…')`), `font-display: swap`, the variable ranges (`font-weight: 100 950`, `font-stretch: 62.5% 150%`), and a fallback face that has Yekan Bakh's vertical metrics.
- Preload only `CRITICAL_FONT_URL` (FaNum), from each root layout.
- A changed font gets the next version, in the same commit. Never overwrite a versioned file or reuse a version.
- A CDN serves the fonts only in front of the app's own domain, under the same paths.
## Alternatives
- Content hashes (0007): stable for unchanged bytes, but a pipeline change can rename them, and the user wants the cache to survive deploys.
- `next/font/local`: hashes the files and moves them out of `public/`.
## Consequences
- A developer, not the build, decides when visitors download a font again. Review must block a changed font that kept its version.
- A cross-origin font CDN isn't supported anymore. `NEXT_PUBLIC_CDN_ORIGIN` was removed.
- Debt: the fallback face has no `size-adjust` yet. Measure it with Persian text set in Tahoma against Yekan Bakh.

View File

@ -0,0 +1,29 @@
# 0010 Island icon-sprite and font-copy plugins, versioned and unhashed
Status: Superseded by 0012 · Area: architecture · Date: 2026-10-05 · Decided by: user · Supersedes: 0008
## Context
0008's single asset plugin wrote the fonts and the svgo sprite into `public/` under content-hashed names, and passed those names to island through env. An svgo or Next.js upgrade changes the bytes, so the hash renames the sprite even when no icon changed, and every visitor downloads it again. The user wants unchanged files to stay cached across deploys.
## Decision
- island ships two build-time plugins, and each app wraps its `next.config.ts` export with both: `withIconSprite(withFontCopy(config))`.
- `tools/icon-sprite-plugin` builds the sprite from `icons/*.svg` with svgo and writes it to `ICON_SPRITE_URL` (`/icons/symbol-defs.v<N>.svg`).
- `tools/font-copy-plugin` copies `fonts/` byte for byte into `public/fonts/`.
- Neither plugin adds a hash. The versions live in island `constants.ts`: `ICON_SPRITE_VERSION`, `ICON_SPRITE_URL`, and `CRITICAL_FONT_URL`. The `Icon` atom and the root layouts read them directly, so island needs no env.
- Raise `ICON_SPRITE_VERSION` with every change to an icon or to the svgo step, in the same commit.
- The plugins write in `headers()`, which only `next dev` and `next build` call. They skip unchanged files, write atomically (temp file, then rename), and warn in dev when a file changed under the same version.
- Each app's `next.config.ts` sends `Cache-Control: public, max-age=31536000, immutable` for `/fonts/:path*` and `/icons/:path*`. Configure the same header on the CDN.
- The sprite always loads from a root-relative, same-origin URL, because `<use href>` never loads across origins.
- The generated files are gitignored.
## Alternatives
- Content hashes (0008): automatic, but a pipeline change renames the files and empties every visitor's cache.
## Consequences
- island's `env/` module, the app's `island-env.ts`, and the `NEXT_PUBLIC_ISLAND_*` variables are gone.
- svgo loads only while the sprite is built, so `next start` doesn't need it.
- Shipping a changed icon or svgo config without a version bump leaves visitors on the old sprite for a year. Review blocks it, and the dev-time warning helps catch it.

View File

@ -0,0 +1,25 @@
# 0011 Yekan Bakh under fixed names, never hashed or versioned
Status: Accepted · Area: design · Date: 2026-10-05 · Decided by: user · Supersedes: 0009
## Context
0009 put a version in each font's file name (`<name>.v<N>.woff2`). The front-end-architect skill gives fonts fixed names with no version, and the user chose the skill's rule for this project.
## Decision
- `font-sans` is Yekan Bakh FaNum, for every UI text. `font-latin` is Yekan Bakh, only for شبا and other codes that banks print in Latin digits.
- Keep each font under its own fixed name in island `fonts/` (`yekan-bakh-fa-num-vf.woff2`, `yekan-bakh-vf.woff2`). Serve it from each app's `public/fonts/` under that exact name, with `Cache-Control: public, max-age=31536000, immutable`. No step hashes or renames it, `next/font` included.
- Fonts have no version. Never change a font under its name: a changed font ships as a new file with a new name, in `fonts/`, `styles/fonts.css`, and `CRITICAL_FONT_URL`, in the same commit.
- Declare the faces in island `styles/fonts.css`, with root paths (`url('/fonts/…')`), `font-display: swap`, the variable ranges, and a fallback face with Yekan Bakh's vertical metrics.
- Preload only `CRITICAL_FONT_URL` (FaNum), from each root layout.
- A CDN serves the fonts only in front of the app's own domain, under the same paths.
## Alternatives
- Versioned names (0009): the same caching, but a version number the skill doesn't use.
## Consequences
- A developer, not the build, decides when visitors download a font again. Review blocks a font changed under its old name.
- Debt: the fallback face has no `size-adjust` yet. Measure it with Persian text set in Tahoma against Yekan Bakh.

View File

@ -0,0 +1,26 @@
# 0012 Icon sprite under a fixed name, versioned in its link
Status: Accepted · Area: architecture · Date: 2026-10-05 · Decided by: user · Supersedes: 0010
## Context
0010 wrote the sprite as `symbol-defs.v<N>.svg`. The front-end-architect skill keeps `symbol-defs.svg` as a fixed name and puts the version in its link, and the user chose the skill's rule for this project.
## Decision
- island ships two build-time plugins, and each app wraps its `next.config.ts` export with both: `withIconSprite(withFontCopy(config))`. island's root `index.ts` leaves them out.
- `tools/icon-sprite-plugin` builds the sprite from `icons/*.svg` with svgo and writes it to `ICON_SPRITE_PATH` (`/icons/symbol-defs.svg`).
- `tools/font-copy-plugin` copies `fonts/` byte for byte into `public/fonts/`.
- Neither plugin adds a hash or a version to a file name. island `constants.ts` holds `ICON_SPRITE_VERSION`, and `ICON_SPRITE_URL` (`/icons/symbol-defs.svg?v=<N>`) built from it. The `Icon` atom links `${ICON_SPRITE_URL}#<name>`.
- Raise `ICON_SPRITE_VERSION` with every change to an icon or to the svgo step, in the same commit. Never reuse or lower it.
- The plugins write in `headers()`, skip unchanged files, write atomically, and warn in dev when a file changed without a new version or name. The sprite's first line stamps its version for that check.
- Each app sends `Cache-Control: public, max-age=31536000, immutable` for `/fonts/:path*` and `/icons/:path*`. The CDN keeps the same header and keeps the query string in its cache key. The sprite stays same-origin and root-relative. The generated files are gitignored.
## Alternatives
- Version in the file name (0010): a deploy that mixes old and new instances returns 404 for the new sprite, instead of old icons under the new `?v=`.
## Consequences
- During a rolling deploy, an old instance can answer `?v=<N+1>` with the old sprite, and a CDN would cache it for a year. Finish the rollout, or purge that URL, before the CDN caches it.
- A CDN that drops the query string from its cache key serves the old sprite after every bump.

View File

@ -1,14 +1,17 @@
# Decisions # Decisions
## Design (DDR) ## Design (DDR)
- 0002 Render every tag through island `Element`, flex layouts through `FlexBox`, grid layouts through `GridBox`; never native JSX tags or `flex`/`grid` classes, island included. - 0002 Render every tag through island `Element`, flex layouts through `FlexBox`, grid layouts through `GridBox`; never native JSX tags or `flex`/`grid` classes, island included.
- 0007 Serve Yekan Bakh FaNum (`font-sans`, all UI text) and Yekan Bakh (`font-latin`, شبا and bank codes only) as hashed `@font-face` files from the app's `public/fonts/` or our CDN, never `next/font`. - 0011 Serve Yekan Bakh FaNum (`font-sans`, all UI text) and Yekan Bakh (`font-latin`, شبا and bank codes only) from `public/fonts/` under fixed names declared in island `fonts.css`; no version, never hashed, never `next/font`; a changed font gets a new name.
## Architecture (ADR) ## Architecture (ADR)
- 0001 Share one platform, `platforms/market`, between `apps/bull` and `apps/bear`; tag all three `scope:market`. - 0001 Share one platform, `platforms/market`, between `apps/bull` and `apps/bear`; tag all three `scope:market`.
- 0008 Register island's asset plugin in each app's `next.config`; on dev and build it writes hashed fonts and the svgo sprite into `public/`; the sprite stays same-origin. - 0012 Wrap each app's `next.config` in island's `withIconSprite` and `withFontCopy`; they write `symbol-defs.svg` and the fonts into `public/` unhashed, served immutable; link the sprite as `?v=<ICON_SPRITE_VERSION>`.
## Proposed ## Proposed
- 0003 design: Only semantic tokens, named as in the Lumina Design System, produce Tailwind utilities (`@theme inline`); primitives stay plain `:root` variables and Tailwind's defaults are removed. - 0003 design: Only semantic tokens, named as in the Lumina Design System, produce Tailwind utilities (`@theme inline`); primitives stay plain `:root` variables and Tailwind's defaults are removed.
- 0005 design: Island holds Lumina's product components and status-to-tone map; they take every text as props (`children` or `labels`) and never import i18next or platform code. - 0005 design: Island holds Lumina's product components and status-to-tone map; they take every text as props (`children` or `labels`) and never import i18next or platform code.
- 0006 architecture: Make every non-app project a pnpm workspace package `@lumina/<name>` with subpath `exports`; third-party dependencies stay in the root package.json. - 0006 architecture: Make every non-app project a pnpm workspace package `@lumina/<name>` with subpath `exports`; third-party dependencies stay in the root package.json.

View File

@ -16,7 +16,7 @@
"./primitives/*": "./src/primitives/*/index.ts", "./primitives/*": "./src/primitives/*/index.ts",
"./hooks/*": "./src/hooks/*/index.ts", "./hooks/*": "./src/hooks/*/index.ts",
"./tools/*": "./src/tools/*/index.ts", "./tools/*": "./src/tools/*/index.ts",
"./env": "./src/env/index.ts", "./constants": "./src/constants.ts",
"./styles/*": "./src/styles/*", "./styles/*": "./src/styles/*",
"./icons/*": "./src/icons/*", "./icons/*": "./src/icons/*",
"./fonts/*": "./src/fonts/*", "./fonts/*": "./src/fonts/*",

View File

@ -3,9 +3,9 @@
import { useEffect, useEffectEvent, useRef, useState } from 'react'; import { useEffect, useEffectEvent, useRef, useState } from 'react';
import type { MouseEvent, PointerEvent, SyntheticEvent } from 'react'; import type { MouseEvent, PointerEvent, SyntheticEvent } from 'react';
import { FlexBox } from '../../atoms/flex-box'; import { FlexBox } from '../flex-box';
import { cn } from '../../tools/cn'; import { cn } from '../../tools/cn';
import { Element } from '../element'; import { Element } from '../../primitives/element';
import { import {
DIALOG_CLOSE_EVENT, DIALOG_CLOSE_EVENT,
DIALOG_OPEN_EVENT, DIALOG_OPEN_EVENT,

View File

@ -1,4 +1,4 @@
import { getEnv } from '../../env'; import { ICON_SPRITE_URL } from '../../constants';
import { Element } from '../../primitives/element'; import { Element } from '../../primitives/element';
import { cn } from '../../tools/cn'; import { cn } from '../../tools/cn';
import type { IconProps } from './types'; import type { IconProps } from './types';
@ -30,8 +30,8 @@ export function Icon({
className={cn('inline-block flex-none align-middle', className)} className={cn('inline-block flex-none align-middle', className)}
{...props} {...props}
> >
{/* One hashed sprite the browser caches; each icon is a `<use>` into it, so icons add no JavaScript. */} {/* One sprite under a fixed name, linked with its version, that the browser caches across deploys; each icon is a `<use>` into it, so icons add no JavaScript. */}
<Element tag="use" href={`${getEnv().iconSpritePath}#${name}`} /> <Element tag="use" href={`${ICON_SPRITE_URL}#${name}`} />
</Element> </Element>
); );
} }

View File

@ -0,0 +1,24 @@
// Fonts and the icon sprite keep fixed names that no build step hashes or renames, so a file that
// didn't change stays in every visitor's cache across deploys (0011, 0012). Fonts have no version: a
// changed font ships as a new file with a new name. The sprite's version lives only in its link.
/**
* Raise it with every change to `icons/*.svg` or to the svgo step in `icon-sprite-plugin`, in the
* same commit. Never reuse or lower it.
*/
export const ICON_SPRITE_VERSION = 1;
/** Where `icon-sprite-plugin` writes the sprite, under each app's `public/`. Its name never changes. */
export const ICON_SPRITE_PATH = '/icons/symbol-defs.svg';
/**
* Root-relative and same-origin: `<use href>` never loads across origins, and CORS can't change
* that. The version is a query string, so a CDN must keep the query in its cache key.
*/
export const ICON_SPRITE_URL = `${ICON_SPRITE_PATH}?v=${ICON_SPRITE_VERSION}`;
/**
* The face every page renders first, Yekan Bakh FaNum. Each root layout preloads it. A font file
* is named only here and in `styles/fonts.css`.
*/
export const CRITICAL_FONT_URL = '/fonts/yekan-bakh-fa-num-vf.woff2';

View File

@ -1,18 +0,0 @@
import type { IslandEnv } from './types';
let islandEnv: IslandEnv | undefined;
/** Called by each app bootstrap, on the server and in the browser. Idempotent. */
export function setEnv(env: IslandEnv): void {
islandEnv = env;
}
/** Read inside functions, never at module top level: bootstrap may not have run yet. */
export function getEnv(): Readonly<IslandEnv> {
if (!islandEnv) {
throw new Error(
'island env is not set. The app bootstrap must call setEnv from @lumina/island/env first.',
);
}
return islandEnv;
}

View File

@ -1,2 +0,0 @@
export { getEnv, setEnv } from './env';
export type { IslandEnv } from './types';

View File

@ -1,15 +0,0 @@
/** island's settings: the hashed asset URLs that the asset plugin wrote into the app's `public/`. */
export type IslandEnv = {
/**
* Root-relative URL of the icon sprite (`/icons/symbol-defs.<hash>.svg`). Always same-origin:
* `<use href>` never loads across origins, and CORS can't change that.
*/
iconSpritePath: string;
/** Font URL per font token, from the app's `public/fonts/` or the CDN under the same paths. */
fontUrls: {
/** Yekan Bakh FaNum: every UI text. */
sans: string;
/** Yekan Bakh: only text that must show Latin digits, such as شبا. */
latin: string;
};
};

View File

@ -16,6 +16,13 @@ export type {
CountdownProps, CountdownProps,
CountdownTone, CountdownTone,
} from './atoms/countdown'; } from './atoms/countdown';
export {
Dialog,
DIALOG_CLOSE_EVENT,
DIALOG_OPEN_EVENT,
DIALOG_PANEL_SELECTOR,
} from './atoms/dialog';
export type { DialogProps } from './atoms/dialog';
export { FlexBox } from './atoms/flex-box'; export { FlexBox } from './atoms/flex-box';
export type { export type {
AlignContent, AlignContent,
@ -94,6 +101,8 @@ export { LockedTeaser } from './molecules/locked-teaser';
export type { LockedTeaserProps } from './molecules/locked-teaser'; export type { LockedTeaserProps } from './molecules/locked-teaser';
export { MediaCarousel } from './molecules/media-carousel'; export { MediaCarousel } from './molecules/media-carousel';
export type { MediaCarouselProps, MediaItem } from './molecules/media-carousel'; export type { MediaCarouselProps, MediaItem } from './molecules/media-carousel';
export { Modal } from './molecules/modal';
export type { ModalProps } from './molecules/modal';
export { export {
NetworkStatus, NetworkStatus,
networkStatusVariants, networkStatusVariants,
@ -110,6 +119,8 @@ export type {
ResendCodeProps, ResendCodeProps,
ResendStatus, ResendStatus,
} from './molecules/resend-code'; } from './molecules/resend-code';
export { Sheet } from './molecules/sheet';
export type { SheetPlacement, SheetProps } from './molecules/sheet';
export { StateMessage, stateMessageVariants } from './molecules/state-message'; export { StateMessage, stateMessageVariants } from './molecules/state-message';
export type { export type {
StateMessageProps, StateMessageProps,
@ -145,8 +156,6 @@ export type {
LightboxLabels, LightboxLabels,
LightboxProps, LightboxProps,
} from './organisms/lightbox'; } from './organisms/lightbox';
export { Modal } from './organisms/modal';
export type { ModalProps } from './organisms/modal';
export { PostCard } from './organisms/post-card'; export { PostCard } from './organisms/post-card';
export type { export type {
PostAuthor, PostAuthor,
@ -165,8 +174,6 @@ export type {
PredictionRangeValues, PredictionRangeValues,
PredictionStatus, PredictionStatus,
} from './organisms/prediction-card'; } from './organisms/prediction-card';
export { Sheet } from './organisms/sheet';
export type { SheetPlacement, SheetProps } from './organisms/sheet';
export { SkeletonPreset } from './organisms/skeleton-preset'; export { SkeletonPreset } from './organisms/skeleton-preset';
export type { export type {
SkeletonPresetName, SkeletonPresetName,
@ -190,13 +197,6 @@ export type {
TierOptionLabels, TierOptionLabels,
TierOptionProps, TierOptionProps,
} from './organisms/tier-option'; } from './organisms/tier-option';
export {
Dialog,
DIALOG_CLOSE_EVENT,
DIALOG_OPEN_EVENT,
DIALOG_PANEL_SELECTOR,
} from './primitives/dialog';
export type { DialogProps } from './primitives/dialog';
export { Element } from './primitives/element'; export { Element } from './primitives/element';
export type { export type {
ElementProps, ElementProps,
@ -204,5 +204,9 @@ export type {
ValidTags, ValidTags,
} from './primitives/element'; } from './primitives/element';
export { cn } from './tools/cn'; export { cn } from './tools/cn';
export { getEnv, setEnv } from './env'; export {
export type { IslandEnv } from './env'; CRITICAL_FONT_URL,
ICON_SPRITE_PATH,
ICON_SPRITE_URL,
ICON_SPRITE_VERSION,
} from './constants';

View File

@ -3,7 +3,7 @@ import { useId } from 'react';
import { Button } from '../../atoms/button'; import { Button } from '../../atoms/button';
import { FlexBox } from '../../atoms/flex-box'; import { FlexBox } from '../../atoms/flex-box';
import { Typography } from '../../atoms/typography'; import { Typography } from '../../atoms/typography';
import { Dialog } from '../../primitives/dialog'; import { Dialog } from '../../atoms/dialog';
import { Element } from '../../primitives/element'; import { Element } from '../../primitives/element';
import { cn } from '../../tools/cn'; import { cn } from '../../tools/cn';
import type { ModalProps } from './types'; import type { ModalProps } from './types';

View File

@ -2,7 +2,7 @@ import { useId } from 'react';
import { FlexBox } from '../../atoms/flex-box'; import { FlexBox } from '../../atoms/flex-box';
import { Typography } from '../../atoms/typography'; import { Typography } from '../../atoms/typography';
import { Dialog } from '../../primitives/dialog'; import { Dialog } from '../../atoms/dialog';
import { Element } from '../../primitives/element'; import { Element } from '../../primitives/element';
import { cn } from '../../tools/cn'; import { cn } from '../../tools/cn';
import { SheetHead } from './components/SheetHead'; import { SheetHead } from './components/SheetHead';

View File

@ -5,7 +5,7 @@ import type { CSSProperties } from 'react';
import { createPortal } from 'react-dom'; import { createPortal } from 'react-dom';
import { Toaster as SonnerToaster } from 'sonner'; import { Toaster as SonnerToaster } from 'sonner';
import { DIALOG_CLOSE_EVENT, DIALOG_OPEN_EVENT } from '../../primitives/dialog'; import { DIALOG_CLOSE_EVENT, DIALOG_OPEN_EVENT } from '../../atoms/dialog';
import type { ToasterProps } from './types'; import type { ToasterProps } from './types';
const noSubscription = () => () => {}; const noSubscription = () => () => {};

View File

@ -7,7 +7,7 @@ import type { KeyboardEvent, PointerEvent } from 'react';
import { FlexBox } from '../../atoms/flex-box'; import { FlexBox } from '../../atoms/flex-box';
import { GridBox } from '../../atoms/grid-box'; import { GridBox } from '../../atoms/grid-box';
import { Typography } from '../../atoms/typography'; import { Typography } from '../../atoms/typography';
import { Dialog } from '../../primitives/dialog'; import { Dialog } from '../../atoms/dialog';
import { Element } from '../../primitives/element'; import { Element } from '../../primitives/element';
import { cn } from '../../tools/cn'; import { cn } from '../../tools/cn';
import { LightboxButton } from './components/LightboxButton'; import { LightboxButton } from './components/LightboxButton';

View File

@ -2,8 +2,8 @@ import { FlexBox } from '../../atoms/flex-box';
import { Icon } from '../../atoms/icon'; import { Icon } from '../../atoms/icon';
import { Link } from '../../atoms/link'; import { Link } from '../../atoms/link';
import { Typography } from '../../atoms/typography'; import { Typography } from '../../atoms/typography';
import { Modal } from '../modal'; import { Modal } from '../../molecules/modal';
import { Sheet } from '../sheet'; import { Sheet } from '../../molecules/sheet';
import { SupportRow } from './components/SupportRow'; import { SupportRow } from './components/SupportRow';
import type { SupportSheetProps } from './types'; import type { SupportSheetProps } from './types';

View File

@ -0,0 +1,41 @@
/*
* Yekan Bakh, served from each app's public/fonts/ by font-copy-plugin (0011, 0012).
* Every `src` is a root path to a file under its fixed name. Next.js leaves root paths alone; a
* relative url('../fonts/…') would go through the bundler and get a hash.
* A font file is named only here and in CRITICAL_FONT_URL (constants.ts). A changed font ships
* under a new name, never under its old one.
*
* Both faces are variable: wght 100–950 and wdth 62.5–150%. The ranges must be declared:
* without font-stretch the browser leaves wdth at its default, 62.5%, and text renders condensed.
*/
/* Persian digit shapes for Latin digits: every UI text (`font-sans`). Preloaded. */
@font-face {
font-family: 'Yekan Bakh FaNum';
src: url('/fonts/yekan-bakh-fa-num-vf.woff2') format('woff2');
font-weight: 100 950;
font-stretch: 62.5% 150%;
font-display: swap;
}
/* Latin digits: only شبا and other codes banks print that way (`font-latin`). Not preloaded. */
@font-face {
font-family: 'Yekan Bakh';
src: url('/fonts/yekan-bakh-vf.woff2') format('woff2');
font-weight: 100 950;
font-stretch: 62.5% 150%;
font-display: swap;
}
/*
* Shown until Yekan Bakh loads. Its vertical metrics are the web font's own (hhea: ascent 1000,
* descent 550, line gap 0, per 1000 units), so lines keep their height when the font swaps in.
* size-adjust isn't measured yet; it needs Persian text set in Tahoma against Yekan Bakh.
*/
@font-face {
font-family: 'Yekan Bakh Fallback';
src: local('Tahoma'), local('Arial');
ascent-override: 100%;
descent-override: 55%;
line-gap-override: 0%;
}

View File

@ -1,4 +1,5 @@
/* Entry that apps import after `tailwindcss`. Fonts are loaded by each app with next/font. */ /* Entry that apps import after `tailwindcss`. Never load fonts with next/font: it hashes them (0011). */
@import './fonts.css';
@import './theme.css'; @import './theme.css';
@import './utilities.css'; @import './utilities.css';
@source '../'; @source '../';

View File

@ -13,9 +13,10 @@
--breakpoint-*: initial; --breakpoint-*: initial;
--container-*: initial; --container-*: initial;
--font-sans: var(--font-yekan-bakh), Tahoma, sans-serif; /* Faces and their fallback are declared in fonts.css. */
--font-sans: 'Yekan Bakh FaNum', 'Yekan Bakh Fallback', Tahoma, sans-serif;
/* Latin digits, for شبا and other codes banks print in Latin digits. */ /* Latin digits, for شبا and other codes banks print in Latin digits. */
--font-latin: var(--font-yekan-bakh-latin), Tahoma, sans-serif; --font-latin: 'Yekan Bakh', 'Yekan Bakh Fallback', Tahoma, sans-serif;
/* Sizes are the design system's px values ÷ 16, in rem, so text and spacing follow /* Sizes are the design system's px values ÷ 16, in rem, so text and spacing follow
the reader's browser font size. */ the reader's browser font size. */

View File

@ -1,135 +0,0 @@
import { createHash } from 'node:crypto';
import {
existsSync,
mkdirSync,
readdirSync,
readFileSync,
renameSync,
writeFileSync,
} from 'node:fs';
import { basename, dirname, extname, join } from 'node:path';
import type { NextConfig } from 'next';
import { optimize } from 'svgo';
import {
ASSET_PHASES,
FONTS,
FONTS_DIR,
HASH_LENGTH,
ICONS_DIR,
IMMUTABLE_CACHE_CONTROL,
SPRITE,
} from './constants';
import type { HashedAsset } from './types';
const ROOT_SVG = /^<svg\b([^>]*)>([\s\S]*)<\/svg>$/;
const VIEW_BOX = /viewBox="([^"]+)"/;
/**
* Wraps an app's `next.config`. On `next dev` and `next build` it writes island's fonts and icon
* sprite into the app's `public/` under content-hashed names, puts their paths in `env`
* (`NEXT_PUBLIC_ISLAND_*`), and serves each file with an immutable `Cache-Control`.
* Build-time only: import it from `next.config.ts`, never from app code.
*/
export function withIslandAssets(
config: NextConfig,
): (phase: string) => NextConfig {
return (phase) =>
ASSET_PHASES.has(phase) ? addIslandAssets(config) : config;
}
function addIslandAssets(config: NextConfig): NextConfig {
const assets: HashedAsset[] = [
{ ...SPRITE, content: buildSprite() },
...FONTS.map((font) => ({
...font,
content: readFileSync(join(FONTS_DIR, font.file)),
})),
].map(({ dir, file, envKey, content }) => ({
envKey,
content,
// Header sources match without basePath; Next adds it.
route: `/${dir}/${hashedName(file, content)}`,
}));
const basePath = config.basePath ?? '';
return {
...config,
env: {
...config.env,
...Object.fromEntries(
assets.map(({ envKey, route }) => [envKey, `${basePath}${route}`]),
),
},
// Only Next loads the headers, on `next dev` and `next build`, so the files are written here.
// Others that evaluate the config, such as Nx's project graph, read it without side effects.
async headers() {
writeAssets(assets);
return [
...((await config.headers?.()) ?? []),
...assets.map(({ route }) => ({
source: route,
headers: [{ key: 'Cache-Control', value: IMMUTABLE_CACHE_CONTROL }],
})),
];
},
};
}
/**
* Optimizes every icon with svgo and joins them into one sprite. Stroke and fill are dropped
* from each root, so the `<Icon>` that references a symbol sets them and a caller can change them.
*/
function buildSprite(): string {
const symbols = readdirSync(ICONS_DIR)
.filter((file) => file.endsWith('.svg'))
.sort()
.map((file) => {
const { data } = optimize(readFileSync(join(ICONS_DIR, file), 'utf8'), {
multipass: true,
// svgo 4 keeps the viewBox by default.
plugins: ['preset-default'],
});
const [, attributes, body] = ROOT_SVG.exec(data) ?? [];
const viewBox = VIEW_BOX.exec(attributes ?? '')?.[1];
if (body === undefined || !viewBox) {
throw new Error(`${file}: expected one root <svg> with a viewBox`);
}
return `<symbol id="${basename(file, '.svg')}" viewBox="${viewBox}">${body}</symbol>`;
});
return `<svg xmlns="http://www.w3.org/2000/svg">${symbols.join('')}</svg>\n`;
}
/** `symbol-defs.svg` → `symbol-defs.<hash>.svg`. */
function hashedName(file: string, content: string | Buffer): string {
const hash = createHash('sha256')
.update(content)
.digest('hex')
.slice(0, HASH_LENGTH);
const extension = extname(file);
return `${basename(file, extension)}.${hash}${extension}`;
}
/**
* Next can load the headers more than once per command, in more than one process. A hashed name
* always holds the same bytes, so an existing file is kept, and a new one is written to a temp
* file, then renamed, so no request ever sees half a file.
*/
function writeAssets(assets: readonly HashedAsset[]): void {
// Next runs from the app's folder, as every Nx target does.
const publicDir = join(process.cwd(), 'public');
if (!existsSync(publicDir)) {
throw new Error(
`island asset plugin: ${publicDir} doesn't exist. Run next from the app's folder.`,
);
}
for (const { route, content } of assets) {
const target = join(publicDir, route);
if (existsSync(target)) continue;
mkdirSync(dirname(target), { recursive: true });
const temp = `${target}.${process.pid}.tmp`;
writeFileSync(temp, content);
renameSync(temp, target);
}
}

View File

@ -1,52 +0,0 @@
import { fileURLToPath } from 'node:url';
import {
PHASE_DEVELOPMENT_SERVER,
PHASE_PRODUCTION_BUILD,
} from 'next/constants';
import type { IslandAsset } from './types';
/** island's sources, resolved from this file, so the plugin works from every app. */
export const ICONS_DIR = fileURLToPath(
new URL('../../icons/', import.meta.url),
);
export const FONTS_DIR = fileURLToPath(
new URL('../../fonts/', import.meta.url),
);
/** Built with svgo from every `icons/*.svg`, one `<symbol id="<name>">` per icon. */
export const SPRITE: IslandAsset = {
dir: 'icons',
file: 'symbol-defs.svg',
envKey: 'NEXT_PUBLIC_ISLAND_ICON_SPRITE_PATH',
};
/** Copied as they are from `fonts/`, one per font token. */
export const FONTS: readonly IslandAsset[] = [
{
dir: 'fonts',
file: 'yekan-bakh-fa-num-vf.woff2',
envKey: 'NEXT_PUBLIC_ISLAND_FONT_SANS_PATH',
},
{
dir: 'fonts',
file: 'yekan-bakh-vf.woff2',
envKey: 'NEXT_PUBLIC_ISLAND_FONT_LATIN_PATH',
},
];
/**
* `next dev` and `next build`. Every other phase, `next start` included, gets the config unchanged:
* the build already inlined `env` and wrote the headers into its routes manifest.
*/
export const ASSET_PHASES: ReadonlySet<string> = new Set([
PHASE_DEVELOPMENT_SERVER,
PHASE_PRODUCTION_BUILD,
]);
/** A hashed name never gets new content, so browsers and CDNs keep the file without asking again. */
export const IMMUTABLE_CACHE_CONTROL = 'public, max-age=31536000, immutable';
/** Hex characters of the SHA-256 content hash in each file name. */
export const HASH_LENGTH = 8;

View File

@ -1,2 +0,0 @@
// Build-time only, so island's root index.ts leaves it out (0008).
export { withIslandAssets } from './asset-plugin';

View File

@ -1,16 +0,0 @@
/** One island file the plugin copies into the app's `public/`. */
export type IslandAsset = {
/** Folder under `public/`, which is also the URL path. */
dir: 'icons' | 'fonts';
/** Source file name; the written copy gets its content hash before the extension. */
file: string;
/** The variable that carries the hashed path to the app's `env/`. */
envKey: `NEXT_PUBLIC_ISLAND_${string}`;
};
/** An asset ready to write: its bytes and its hashed path under `public/`. */
export type HashedAsset = Pick<IslandAsset, 'envKey'> & {
content: string | Buffer;
/** `/<dir>/<name>.<hash>.<ext>`, without basePath. */
route: string;
};

View File

@ -0,0 +1,6 @@
import { fileURLToPath } from 'node:url';
/** island's fonts, resolved from this file, so the plugin works from every app. */
export const FONTS_DIR = fileURLToPath(
new URL('../../fonts/', import.meta.url),
);

View File

@ -0,0 +1,63 @@
import {
copyFileSync,
existsSync,
mkdirSync,
readdirSync,
readFileSync,
renameSync,
} from 'node:fs';
import { join } from 'node:path';
import type { NextConfig } from 'next';
import { FONTS_DIR } from './constants';
/**
* Wraps an app's `next.config`. On `next dev` and `next build` it copies island's `fonts/` byte
* for byte into `public/fonts/`, keeping their fixed names with no hash (0011, 0012).
* Build-time only: import it from `next.config.ts`, never from app code.
*/
export function withFontCopy(config: NextConfig): NextConfig {
return {
...config,
// Only Next calls `headers()`, and only on `next dev` and `next build`; `next start` reads the
// build's routes manifest. Others that evaluate the config, such as Nx's project graph, never
// call it, so the files are copied here and nowhere else.
async headers() {
copyFonts();
return (await config.headers?.()) ?? [];
},
};
}
/**
* Next can call `headers()` more than once per command, in more than one process. An unchanged
* file is left alone, and a new one is copied to a temp file, then renamed, so no request ever
* sees half a font.
*/
function copyFonts(): void {
// Next runs from the app's folder, as every Nx target does.
const publicDir = join(process.cwd(), 'public');
if (!existsSync(publicDir)) {
throw new Error(
`font-copy-plugin: ${publicDir} doesn't exist. Run next from the app's folder.`,
);
}
const targetDir = join(publicDir, 'fonts');
mkdirSync(targetDir, { recursive: true });
for (const file of readdirSync(FONTS_DIR)) {
if (!file.endsWith('.woff2')) continue;
const source = join(FONTS_DIR, file);
const target = join(targetDir, file);
if (existsSync(target)) {
if (readFileSync(target).equals(readFileSync(source))) continue;
// Visitors who cached this name keep its old bytes for a year.
console.warn(
`font-copy-plugin: ${file} changed under the same name. Ship the changed font under a new name in fonts/, fonts.css and CRITICAL_FONT_URL before this ships.`,
);
}
const temp = `${target}.${process.pid}.tmp`;
copyFileSync(source, temp);
renameSync(temp, target);
}
}

View File

@ -0,0 +1,2 @@
// Build-time only, so island's root index.ts leaves it out (0012).
export { withFontCopy } from './font-copy-plugin';

View File

@ -5,7 +5,7 @@ import type { IconNameExtractionOptions } from './types';
/** /**
* Writes the `IconName` union from the icon file names, so `<Icon name>` only accepts an icon * Writes the `IconName` union from the icon file names, so `<Icon name>` only accepts an icon
* the sprite has. The sprite itself is built by `tools/asset-plugin` on `next dev` and `next build`. * the sprite has. The sprite itself is built by `tools/icon-sprite-plugin` on `next dev` and `next build`.
*/ */
export function extractIconNames({ export function extractIconNames({
iconsDir, iconsDir,

View File

@ -0,0 +1,6 @@
import { fileURLToPath } from 'node:url';
/** island's icons, resolved from this file, so the plugin works from every app. */
export const ICONS_DIR = fileURLToPath(
new URL('../../icons/', import.meta.url),
);

View File

@ -0,0 +1,94 @@
import {
existsSync,
mkdirSync,
readdirSync,
readFileSync,
renameSync,
writeFileSync,
} from 'node:fs';
import { basename, dirname, join } from 'node:path';
import type { NextConfig } from 'next';
import { ICON_SPRITE_PATH, ICON_SPRITE_VERSION } from '../../constants';
import { ICONS_DIR } from './constants';
const ROOT_SVG = /^<svg\b([^>]*)>([\s\S]*)<\/svg>$/;
const VIEW_BOX = /viewBox="([^"]+)"/;
/** The sprite's first line, so the next run knows which version the file in `public/` was built for. */
const VERSION_STAMP = `<!-- ICON_SPRITE_VERSION ${ICON_SPRITE_VERSION} -->`;
/**
* Wraps an app's `next.config`. On `next dev` and `next build` it builds island's icon sprite
* with svgo and writes it to `public/` at `ICON_SPRITE_PATH`, a fixed name with no hash (0012). The
* version lives only in `ICON_SPRITE_URL`'s query string.
* Build-time only: import it from `next.config.ts`, never from app code.
*/
export function withIconSprite(config: NextConfig): NextConfig {
return {
...config,
// Only Next calls `headers()`, and only on `next dev` and `next build`; `next start` reads the
// build's routes manifest. Others that evaluate the config, such as Nx's project graph, never
// call it, so the file is written here and nowhere else.
async headers() {
writeSprite(await buildSprite());
return (await config.headers?.()) ?? [];
},
};
}
/**
* Optimizes every icon with svgo and joins them into one sprite. Stroke and fill are dropped
* from each root, so the `<Icon>` that references a symbol sets them and a caller can change them.
*/
async function buildSprite(): Promise<string> {
// Loaded here, so `next start` never needs svgo.
const { optimize } = await import('svgo');
const symbols = readdirSync(ICONS_DIR)
.filter((file) => file.endsWith('.svg'))
.sort()
.map((file) => {
const { data } = optimize(readFileSync(join(ICONS_DIR, file), 'utf8'), {
multipass: true,
// svgo 4 keeps the viewBox by default.
plugins: ['preset-default'],
});
const [, attributes, body] = ROOT_SVG.exec(data) ?? [];
const viewBox = VIEW_BOX.exec(attributes ?? '')?.[1];
if (body === undefined || !viewBox) {
throw new Error(`${file}: expected one root <svg> with a viewBox`);
}
return `<symbol id="${basename(file, '.svg')}" viewBox="${viewBox}">${body}</symbol>`;
});
return `${VERSION_STAMP}\n<svg xmlns="http://www.w3.org/2000/svg">${symbols.join('')}</svg>\n`;
}
/**
* Next can call `headers()` more than once per command, in more than one process. An unchanged
* file is left alone, and a new one is written to a temp file, then renamed, so no request ever
* sees half a file.
*/
function writeSprite(sprite: string): void {
// Next runs from the app's folder, as every Nx target does.
const publicDir = join(process.cwd(), 'public');
if (!existsSync(publicDir)) {
throw new Error(
`icon-sprite-plugin: ${publicDir} doesn't exist. Run next from the app's folder.`,
);
}
const target = join(publicDir, ICON_SPRITE_PATH);
if (existsSync(target)) {
const current = readFileSync(target, 'utf8');
if (current === sprite) return;
// Same version, new icons: visitors who cached this version keep the old icons for a year.
if (current.startsWith(VERSION_STAMP)) {
console.warn(
`icon-sprite-plugin: the sprite changed, but ICON_SPRITE_VERSION is still ${ICON_SPRITE_VERSION}. Raise it in island's constants.ts before this ships.`,
);
}
}
mkdirSync(dirname(target), { recursive: true });
const temp = `${target}.${process.pid}.tmp`;
writeFileSync(temp, sprite);
renameSync(temp, target);
}

View File

@ -0,0 +1,2 @@
// Build-time only, so island's root index.ts leaves it out (0012).
export { withIconSprite } from './icon-sprite-plugin';

View File

@ -1,9 +1,9 @@
'use client'; 'use client';
import { Element } from '@lumina/island/primitives/element'; import { Element } from '@lumina/island/primitives/element';
import { ErrorFallback } from '@lumina/market/app/error-boundaries';
import { useQueryErrorResetBoundary } from '@tanstack/react-query'; import { useQueryErrorResetBoundary } from '@tanstack/react-query';
import { ErrorFallback } from '../../../error-boundaries';
import type { PageErrorProps } from './types'; import type { PageErrorProps } from './types';
/** /**

View File

@ -20,6 +20,8 @@ export { AuthGuard } from './app/guards/auth-guard';
export type { AuthGuardProps } from './app/guards/auth-guard'; export type { AuthGuardProps } from './app/guards/auth-guard';
export { GuestGuard } from './app/guards/guest-guard'; export { GuestGuard } from './app/guards/guest-guard';
export type { GuestGuardProps } from './app/guards/guest-guard'; export type { GuestGuardProps } from './app/guards/guest-guard';
export { PageError } from './app/screens/organisms/page-error';
export type { PageErrorProps } from './app/screens/organisms/page-error';
export { export {
CHANNEL_PREFIX, CHANNEL_PREFIX,
loginRoute, loginRoute,