# Shared concept contract

For concepts 11–20, [ROUND_THREE.md](ROUND_THREE.md) adds distinct dialog composition and design directions. For concepts 06–10, [ROUND_TWO.md](ROUND_TWO.md) overrides the layout constraints below and documents the optional shell, action and motion hooks. All twenty concepts share this same runtime and API.

Root owns shared/ completely. Each designer owns only their numbered concept folder. Static ES modules, no build step. One origin, one persisted world and one API for all twenty concepts. Never create local mock data or financial logic.

## Entry
`index.html`: UTF-8, viewport width=device-width, initial-scale=1, viewport-fit=cover; title; favicon ../shared/assets/favicon.svg; stylesheet ../shared/base.css then ./style.css; `<div id="app"></div>`; external module script ./app.js. Optional Telegram script https://telegram.org/js/telegram-web-app.js. No inline scripts or event handlers.

`app.js`: `import {mount} from '../shared/app.js'; mount({id:'01-tide',name:'Tide', renderHeader(ctx),renderHome(ctx),renderNav(ctx), renderWallet(ctx),renderShop(ctx)});`
Only first three render functions needed. Optional wallet/shop receive ctx.defaultContent (fully functional common markup), and should return custom composition around it; style all shared components to fit your direction. Return HTML strings, safely escaping user values.

## Context
- `t(english,persian)` current language string; `esc(value)` HTML escapes; `icon(name,size=20)` inline stroked SVG; `fmt(number)` Latin digits/thousands; `money(number)` with Toman unit; `data(number,remaining=false)` localized GB/MB; `days(sub)` localized remaining time; `percent(sub)` number or null; `status(sub)` localized state; `tone(sub)` 'good'|'warning'|'critical'|'muted'; `date(value)` local date string.
- `lang` fa/en; `page` subscriptions/wallet/shop; `brand` localized runtime brand; `config`; `user` {id,username,first_name,is_partner,acting_as}; `account` normal/partner/newcomer/staff-as-partner.
- `subscriptions`: whole fetched set, `visible`: filtered/sorted/paged subset; `total` whole count, `filteredCount`; `query`, `sort` name/usage/time; `filter` all/active/attention; `loading`, `usageLoading`, `error`; `wallet` {wallets,balance,transactions,...} or null; `categories` array; `defaultContent` for wallet/shop only.
- `controls()` common labeled search, filters and sort markup; `more()` paging/empty-state markup; `card(sub)` optional common card (prefer bespoke). `nav()` default three-tab nav if desired.
- subscriptions fields exactly REDESIGN_BRIEF §7.5. Initially usage_gb=null, usage_loaded=false. Never hardcode usage; ensure loading, Error, N/A, unlimited work. Names/technical strings must be LTR. Data should be primary on active card with copy as quick action, expiry/renew on expired, support on not-found.

## Delegated DOM actions (automatic, no handlers needed)
Set `data-action="..."`; when subscription-specific add `data-id="${sub.id}"`.
- `nav` + data-page subscriptions/wallet/shop
- `detail`, `copy`, `qr`, `configs`, `import`, `rename`, `renew`, `auto`, `revoke`, `delete`, `send`, `support`
- `language`, `settings`, `refresh`, `more`
- `filter` + data-value all/active/attention; `sort` + data-value name/usage/time
- search input `data-input="search"`; sort select `data-input="sort"`; both preserve focus.
- `wallet-select` + data-id wallet id; `category` + data-id category id; `export`
- Root implements all mutations/confirmations/forms. Use real buttons with type=button. Nav aria-current=page. Shared settings includes account switch, theme, demo scenarios, reset and concept links.

## Shared styling contract
Define CSS vars on :root: --bg,--surface,--surface-2,--text,--muted,--line,--accent,--accent-ink,--good,--warning,--danger,--radius,--font (font-family). Local shared assets include Vazirmatn. Shared base defines box sizing, icons .icon, .ltr, buttons .btn/.primary/.secondary/.danger/.icon-btn, .muted, .badge/.good/.warning/.critical, .panel, .stack, .row, .between, .grid-2, .field, .notice, .empty, .search-box, .segmented, .page-title, .section-title, .wallet-card, .wallet-tabs, .transaction-list/.transaction/.tx-icon/.tx-amount, .category-list/.category-card, .plan-list/.plan-card, .sheet-backdrop, dialog.sheet, .sheet-header/.sheet-body/.sheet-actions, .fact-list, .progress, .toast. Customize these in concept style.css.

Engine skeleton: #app > .app-shell > header.app-header + main.app-main + nav.app-nav. Your renderHeader returns header CONTENT, renderNav returns nav CONTENT. Engine handles modal separately as dialog.sheet. Mobile-first 360-480px, max shell width 560-640 okay for desktop; do NOT build marketing/landing page, fake phone frame or phone status bar. Fill mobile screen, safe-area top/bottom, fixed bottom tab bar. Avoid fake online/connected claims (VPN app handles connection). All labels bilingual t(). Theme default can match concept; host light/dark honored through [data-theme="light|dark"] on documentElement.

Exactly concepts 01 and 02 use Refero skill fallback craft references + provided screenshots. Other three use creative direct design without Refero. User expressly approves direct build of all directions, no approval pause needed.