# The web app COLLAB's interface is a static site: HTML, CSS and ES modules served as files. There is no bundler, no framework, no compile step and no Node.js anywhere in the toolchain; the release build only versions asset URLs and precompresses files. The browser talks only to the GenesisL1 RPC endpoint the visitor uses, to the visitor's wallet, to the site's own files (`/config.js`, `/data/`, `/og/`) and, when the visitor chooses a display currency, to the price API. This page is for developers who change the app: it is the contract every page and view follows. ## Layout ``` web/ index.html daos.html dao.html votes.html tokens.html create.html descifi.html docs.html admin.html settings.html privacy.html 404.html entries, one page module each (see "URLs"); 404.html runs js/fallback.js. Every entry carries the portal shell's static markup between and markers, written by tools/shell_html.py (see "The portal shell") pools/index.html locks/index.html copies of descifi.html with their own head (python3 tools/prerender.py --static-pages) docs.html docs/ the documentation, generated from docs/*.md by tools/build_docs.py: the home, docs//index.html, docs/.md, index.json, search.json; llms.txt beside them (see "The docs pages") config.js generated per deployment (tools/write_web_config.py); config.local.js for dev BUILD.json in a release tree only: the release and its ?v= (tools/version_assets.py) _headers _redirects headers and rewrites for Netlify and Cloudflare Pages (_redirects also for IPFS gateways; deploy/ has nginx and Caddy) robots.txt sitemap.xml manifest.webmanifest favicon.svg assets/css/app.css the design system, shared components and every area's styles (see "Design system") assets/css/deploy.css the deploy flow (the admin page's Deploy and Check tabs) assets/img/ icons.svg (the sprite, see "Icons"), logo.svg, og.png and the app icons assets/fonts/ Inter, JetBrains Mono, Source Serif 4 (WOFF2) with their OFL texts assets/deploy/collab-protocol.json the deploy bundle (tools/export_deploy_artifacts.py) assets/docs/ the documentation's figures, WebP (tools/docs_figures.py) js/theme.js classic script in : theme before first paint, settings of 1.0 migrated js/consent.js cookie notice, and Google Analytics only after consent where configured js/fallback.js on 404.html: sends a clean path to its entry on hosts without rewrites js/vendor/ ethers 6.17.0 (ESM), libsodium.js 0.8.2 (sodium-0.8.2.js), ML-KEM-768 (mlkem-0.0.7.js), markdown-it 14; each file carries its version in its name, so a new version gets a new name js/core/ shared modules (below). Owned by the core team; do not fork them. js/pages/.js page entry points js/views/dao-.js DAO sections, lazily loaded by js/pages/dao.js js/views/new/.js proposal builders, lazily loaded by js/views/dao-new.js js/views/profile-editors.js the logo and description editors (wizard, profile builders, representatives) js/create/ the creation wizard: its steps, draft, presets and review js/descifi/ DeSciFi and the tokens pages: chain data, the market, swap, pools, locks, token list and page js/sealed/ sealed data: browser cryptography compatible with CIPNFT, keys, the vault's operations js/admin/ /admin: the Admin API client and session (api.js, session.js), sign-in (signin.js), the frame and tabs (app.js, parts.js, status.js, publish.js, site.js with sitecheck.js and lookup.js) js/deploy/ the deploy flow (flow.js) and Check (check.js), loaded by the admin page's Deploy and Check tabs ``` The admin page's API is documented in [Admin API reference](../docs/admin-api.md), and the formats of config.js, site.json and the /data/ files in [Data formats](../docs/data-formats.md). ## Non-negotiable rules Security - Never use `innerHTML`, `outerHTML`, `insertAdjacentHTML`, `document.write` or string HTML. Build DOM with `h()` / `s()` from `core/dom.js`. Every string from the chain (titles, descriptions, token names and symbols, constitutions, links, model metadata) is attacker-controlled. Clean names and symbols with `cleanText()` from `core/tokens.js` (it counts characters as code points, like `clean_text()` in tools/seo/text.py, and removes the same invisible, blank and bidi characters, astral ones included: change both together). Show a DAO by `dao.name`, never `dao.title` (see daodata.js). An element that shows a name or title from the chain gets `dir: "auto"`; inside a sentence, wrap the name in `h("bdi", {}, name)`, so a right-to-left name never reorders the text around it. - Chain strings need not be valid UTF-8 (older contracts, other tokens and NFTs). Every interface from `core/contracts.js` (`iface()`, `contract()`, `read.*`) decodes them with U+FFFD for the bad bytes instead of failing the whole call; an ABI you write yourself goes through `lenientInterface([...])`, not `new ethers.Interface`. - Markdown goes through `renderMarkdown()` (`core/md.js`: markdown-it tokens rendered to DOM nodes, links filtered), inside a `.doc` container. - URLs go through `safeUrl()`; external links get `target="_blank" rel="noopener noreferrer"`. User-supplied links additionally get `nofollow`. - Images from the chain are shown only as `data:` URLs produced by `readImageUrl()` (hash-verified, MIME allowlist) inside ``; SVG never goes into the DOM as markup. - The Content-Security-Policy forbids inline scripts and inline style attributes. Set styles with the `style: {…}` attribute of `h()` (CSSOM, allowed) or with classes. No `eval`, no `new Function`. - No new third-party code. If something is missing, write it. No CDN, no remote fonts. Analytics exist only as `js/consent.js` loads them: in deployments that configure an ID, after Accept. - Amounts are `BigInt` in base units end to end. Parse input with `parseUnits()` / the form fields in `core/forms.js`; format with `units()` / `l1()` / `money()`. Never use floating point for amounts sent on-chain (fiat values from `core/price.js` are for display only). Read `decimals` from token metadata; never assume 18 for ERC-20 tokens. - Addresses are validated and checksummed with `ethers.getAddress()` (`addressField` does it). - Every transaction goes through `send()` / `sendValue()` from `core/wallet.js`: they preflight with `estimateGas` (reverts are explained before the wallet opens), show progress toasts and invalidate caches. Never call `signer.sendTransaction` directly. - Irreversible or dangerous user actions (giving up token powers, deleting a model, revealing data, declassifying, publishing keys) require `confirmDialog()` with plain consequences. - Browser storage only for conveniences, under `collab-*` keys, always wrapped in try/catch (use `readRaw` / `writeRaw` / `readJSON` / `writeJSON` from `core/settings.js`), never trusted without validation. Add every new key to `STORAGE_KEYS` there: /privacy lists them. Secrets (derived encryption keys) live in memory only and are dropped on account change or page unload. Links and paths - Build every link with `url.*` from `core/router.js` (and `ctx.href` inside a DAO). `tools/lint_web.py` refuses hand-written `*.html` page links and `#/` hash routes in modules. - Every path in HTML is root-absolute (`/assets/…`, `/js/…`, `/config.js`) or a clean URL: pages are served at any depth (`/dao/0x…/proposals/3`). The site must be hosted at a domain root. Licence - Every source file we own starts with the licence line: JS and CSS `/* MIT License. Copyright (c) 2026 Decentralized Science Labs LLC. */` as the first line, then the description comment; Python the same text as a `#` comment after the shebang; HTML `` right after ``; Solidity `// SPDX-License-Identifier: MIT` then `// Copyright (c) 2026 Decentralized Science Labs LLC`. Vendored files keep their own headers. `tools/lint_web.py` checks web/ and tools/. Design and copy - Use the design system (see "Design system") and its classes. The look follows genesisl1.com/gov.html: white windows, hairline borders, GenesisL1 blue, status pills. - Feature styles live in their area's section of `app.css`, each marked `/* ---- (merged from parts/.css) ---- */` (portal, dex, dao, governance, models, sealed, create, treasury, tokens, admin, core, landing, settings), before the design system's shared rules; the docs pages have a section of their own. Prefix every new class with your area (`tr-`, `tk-`, `cr-`, `sl-`, `md-`, `dx-`, `gv-`, `dc-`, `dao-`, `ld-`, `st-`, `ad-`) and never restyle shared classes there; add a modifier class instead. Theme colours come from the tokens; check dark mode. - To style areas in parallel, split one out again as a part, `assets/css/parts/.css`, imported at the top of `app.css` with `@import url("/assets/css/parts/.css");`, and edit only your own part. Before a release `python3 tools/merge_css.py` folds every part into `app.css` at its import line (the order stays exactly as tested; a part with `@import` or a relative `url()` must be merged by hand) and deletes the parts; `tools/build_release.py` refuses to pack while imports remain. - Cascade order: the area sections (and imported parts) come first, so a shared rule in `app.css` wins over an area rule of equal specificity. To adjust a shared class inside your area, combine it with your own class (`.kv.tr-kv`, `.item.tr-tok`) rather than repeating the shared selector. - Copy: plain verbs, sentence case, specific. Buttons say what happens ("Submit proposal", "Reclaim deposit"), and the toast and the history use the same words. Errors say what happened and how to fix it. Empty states invite the next action. Do not use: ALL-CAPS labels, eyebrow labels above headings, meta strings joined with middle dots ("a · b"), spaced em-dash fragments ("Label — fragment"), arrows appended to link text. - Responsive down to 360 px wide with no sideways scroll; visible keyboard focus; `prefers-reduced-motion` respected; tables wrapped in `.table-wrap`. Numbers use `.num` (tabular figures). ## URLs Clean paths, each served by one HTML entry (production servers rewrite them; see docs/DEPLOY.md): | path | entry | notes | |---|---|---| | `/` | index.html | the portal's home | | `/daos` | daos.html | directory; `?q=&sort=members\|treasury\|newest&mine=1` | | `/dao/[/
/…]` | dao.html | sections below; `/dao/
` also works and leads to the slug URL; prerendered copies serve `/dao/` | | `/votes` | votes.html | open proposals across DAOs; `?state=voting\|deposit\|waiting&dao=` | | `/tokens[/
]` | tokens.html | every token on DeSciFi, one token (W-DEX) | | `/admin[/]` | admin.html | the operator's admin: deploy, publish, check, site settings, status (W-ADMIN) | | `/create` | create.html | wizard; the step as `?step=identity\|constitution\|members\|governance\|people\|review` | | `/swap[//]` | descifi.html | the zero address is native L1 | | `/pools`, `/pools/`, `/pools/add[///]` | descifi.html | pool list, one pool, add liquidity | | `/locks[/]` | descifi.html | lock boxes | | `/docs`, `/docs/`, `/docs/.md` | docs.html, `docs//index.html` | the docs home, one page, its Markdown; generated by tools/build_docs.py | | `/deploy` | (301) | moved to `/admin/deploy` in 2.2 | | `/settings` | settings.html | `#network #explorer #currency #appearance #privacy` | | `/privacy` | privacy.html | cookie and privacy policy, `#storage` lists every key | DAO sections: (overview) `proposals`, `proposals/`, `propose`, `propose/`, `propose//` with `?preset=`, `treasury`, `members`, `tokens`, `liquidity`, `sealed`, `sealed/`, `models`, `models/`, `constitution`, `constitution/v`, `constitution/compare//`, `settings`. Addresses in paths are lowercase; the router accepts any case and fixes it with `history.replaceState`. `core/router.js` - `url` builders, the only way to write a link: `url.home()`, `url.daos({q, sort, mine})`, `url.dao(dao, ...parts)` where `dao` is a DAO object (its slug wins), a slug or a treasury address (`url.dao(d, "proposals", 12)` or `url.dao(d, "proposals/12")`; pass the object so the link is the canonical slug URL), `daoKey(dao)` (the path segment: slug, else lowercase address), `url.votes({state, dao})`, `url.tokens(address?)`, `url.admin(tab?)`, `url.propose(treasury, kind, builder, preset)`, `url.create(step)`, `url.swap(a, b)`, `url.pool(pair)` (no pair: the list), `url.pools()`, `url.addLiquidity(a, b, feeBps)`, `url.locks(owner)`, `url.docs(ref)` (`""` the docs home, `"proposals"` a page, `"proposals#delegation"` a section; an anchor of 2.2.0's single docs page, such as `"holding-period"`, leads to where that section is now through `DOC_MOVED`, which `tools/build_docs.py --check` verifies), `url.settings(anchor)`, `url.deploy()` (= `/admin/deploy`), `url.privacy(anchor)`. - `route()` → `{entry, parts, query (URLSearchParams), hash, path}` for the current location; `parts` are the path segments inside the entry (`/dao/0x…/proposals/12` → `["0x…", "proposals", "12"]`, `/pools/add/a/b/30` → `["pools", "add", "a", "b", "30"]`). `ENTRY` is this page's entry. - `onRoute(fn)` registers the page's router; `fn(route, {action: "push"|"pop"|"replace"})`. Once one is registered, same-origin links to this entry are handled without a reload (modifier keys, other buttons, `target` and `download` links behave as usual; in-page `#anchors` scroll natively). - `navigate(path, {replace})`: within this entry `pushState` (or `replaceState`) and the page's router renders; any other path is a full load. `replaceQuietly(path)` / `pushQuietly(path)` change the address bar without rendering (a filter, a wizard step the page already shows). - `encodePreset(obj)` / `decodePreset(str)` (base64url UTF-8 JSON, plain objects only, 64 KB at most), `daoHref(treasury, path)`, `siteUrl(path)` (CFG.siteUrl + path, for canonical links). - Version 1 URLs redirect on load: `dao.html?dao=X#/proposal/3` and `dao.html#/X/new///` to `/dao/x/proposals/3` and `/dao/x/propose//?preset=…`, `descifi.html#/pool/P` to `/pools/p`, `docs.html#x` to `/docs#x`, `index.html?mine=1` to `/daos?mine=1`. - Hosts without rewrites answer clean paths with 404.html, whose `/js/fallback.js` sends them to `/.html?route=`; the router then puts the clean path back with `replaceState`. ## Settings, prices and consent `core/settings.js` typed settings over localStorage (memory when storage is blocked): `get(name)`, `set(name, value)` (invalid values throw; the default removes the key), `onChange(name, fn)` (this tab and others) for `theme` ("system" | "light" | "dark"), `rpc` ("" = automatic, or an endpoint URL), `explorer` ("" = the default, or an https URL) and `currency` (`CURRENCIES`: l1 usd eur gbp chf jpy cny krw inr rub uah try pln aed cad aud brl sgd hkd btc eth; `CURRENCY_NAMES`). `setTheme(pref)`, `applyTheme()`, `effectiveTheme()`, `isEndpointUrl(url)`; raw access `readRaw`, `writeRaw`, `readJSON`, `writeJSON`; `STORAGE_KEYS` ([{key, what}], shown on /privacy). | key | holds | |---|---| | `collab-theme` | System, Light or Dark | | `collab-rpc` | the chosen endpoint (absent: automatic) | | `collab-explorer` | the chosen explorer (absent: the default) | | `collab-currency` | the currency the visitor chose (absent: US dollars from the site's price) | | `collab-price` | the last L1 price the site published, or fetched for the chosen currency, and its time (reused for 5 minutes) | | `collab-cookie-info` | when the cookie notice was closed | | `collab-consent` | `{v: 1, analytics, at}` where analytics are configured | | `collab-wallet` | the last wallet's EIP-6963 rdns | | `collab-tokens` | tokens the visitor added | | `collab-descifi` | slippage and deadline | | `collab-create-draft` | the creation wizard's draft | | `collab-sealed-key-version:::` | the registered sealed-data key version | | `collab-deploy::` | progress of a deployment from /admin/deploy: external addresses, tx hash, nonce and address of each contract | `js/theme.js` moves the `collab.*` keys of version 1.0 to these names on the first visit. `core/price.js` the L1 price. By default amounts show in US dollars from the site's own `/data/price.json` (`{usd, usd24hChange, at, source}`, at most 10 KB, written by the server's prerender; used within 24 hours, and only on the configured site, `onSite()`), so no visitor's browser contacts a price service by itself. Only when the visitor chooses a currency (settings, the top bar's chip) does the browser fetch it live from `CFG.priceApi` (CoinGecko simple price), cached 5 minutes; L1 needs no price, and a failure shows no fiat value. `money(l1Wei, {maxFrac})` → `1,234 L1 ≈ $217` that updates itself when the price arrives or the currency changes; `fiatOf(l1Wei)` → "≈ $217" or null; `formatFiat(value, vs)`, `unitPrice()` ("1 L1 = $0.0042"), `price()` (`{vs, price, change, at}`), `sitePrice()`, `priceSource(q)` ("CoinGecko, 14:05"), `loadPrice()`, `onPrice(fn)`, `currency()`. `chosen("currency")` in settings.js tells a chosen US dollar from the default. `core/capped.js` bodies of bounded size: `readCapped(res, max)` (bytes), `textCapped`, `jsonCapped` (null when larger) and `discard(res)`. The body is streamed and the read stops at the cap, because Content-Length is the compressed size under gzip_static and absent on a chunked answer. Read every /data/ file and any other bounded answer through it. `js/consent.js` (an ES module the shell imports) A compact card at the bottom left of the content column, over nothing that matters and with no overlay or focus trap. Without analytics: a one-time note ("COLLAB keeps your settings in this browser. No tracking or ad cookies.", Cookie policy, OK). With `CFG.analytics.googleMeasurementId`: the same card asks ("May COLLAB count visits with Google Analytics? …"), "Accept" and "Decline" the same size, nothing requested from Google before Accept, asked again after 6 months (Decline) or 12 (Accept); a browser that sends Global Privacy Control gets a note instead and counts as a Decline. `openConsent()` (the footer's Cookie settings), `consentState()` → `{enabled, decided, analytics, loaded}`. Network: the settings page offers the `CFG.rpcs` presets, Automatic (every preset, with failover) and, with `CFG.allowCustomRpc`, a custom https URL (http only on localhost) that must answer `eth_chainId` with `CFG.chainId` and a recent block before it is saved (latency and head block are shown). `tools/write_web_config.py --patch-csp` writes the CSP that matches: `connect-src` lists the presets and the price API, plus `https:` when custom RPCs are allowed; Google's origins appear only with `--ga-id`. Every entry carries the same CSP. ## The portal shell Every page sits in one frame, after gl1x.com: a slim alpha strip across the top (text from the site settings), a sidebar (brand with the Alpha badge, the live network card with chain, latest block, L1 price and this site's deployment, then the navigation in three groups: Discover, DeSciFi, Build), a top bar over the content (global search, currency, theme, wallet), an announcement slot under it, and the ecosystem footer. Below 1024px the sidebar is a drawer opened from the top bar's menu button (it also holds currency and theme there); below 768px the search folds into a button. The markup is static in every entry (no layout shift when the module runs; links crawlable), written between the `` and `` markers by `python3 tools/shell_html.py --write`; `tools/lint_web.py` fails on an entry whose shell is missing or stale. Never edit those blocks by hand: change tools/shell_html.py and run it. A new entry gets the shell by running the tool once. The prerender writes copies with the site settings baked in. `shell()` in ui.js only fills in what is live. The body is a grid: `alpha-strip` spans the top row; `.side` and `.topbar` span every row below it (that is what lets both stick without a wrapper); `
` and `.site-foot` sit in the content column. Pages keep `
` as before and lay out inside it: `.bands`, `.band`, `.frame` work as they did. A page never adds a second rail: section navigation inside a page is a bar (`.tabs`, or `.ws-nav`, which is a sticky bar under the top bar at every width), and contents of a long document go on the right. Global search (core/search.js): DAOs by title, slug, share symbol or address, tokens by symbol, name or address (`/data/tokens.json` on the site, plus wL1), proposals as a DAO and a number ("opc 3"), and the site's pages; "/" or Ctrl/Cmd K focuses it. Hidden DAOs and tokens are left out. Undeployed mode: `CFG.deployed` is false until the operator deploys from /admin. The shell shows "Not deployed" in the network card; every page calls `deployedOrNotice()` and shows its notice instead of reading the chain. ## Design system Tokens are CSS variables on `:root`, redefined under `:root[data-theme="dark"]` (the GenesisL1 zinc theme). Use them; never hard-code colours. - Surfaces: `--bg` (page), `--bg-2` (bands, table heads, sunken areas), `--bg-3` (hover, bar tracks), `--surface` (windows), `--surface-2` (rows nested in windows). - Text: `--ink`, `--ink-2` (secondary), `--muted` (labels, captions), `--faint` (placeholders, ticks). - Lines: `--ring` (every 1px hairline), `--ring-2` (stronger: inputs, hover borders). - Blue: `--primary`, `--primary-hover`, `--primary-soft` (selected rows, info notices), `--primary-line`, `--on-primary` (text on filled blue). Wallet: `--wallet`, `--wallet-ring`, `--wallet-ink`. - Portal: `--chrome` (sidebar and top bar), `--band` and `--band-line` (genesisl1.com's soft blue band: page mastheads, `.band-head`), `--strip-bg` `--strip-ink` `--strip-em` `--strip-link` (the alpha strip), `--live` (a live status dot). - Market (DeSciFi): `--buy`, `--buy-soft`, `--buy-line` and `--sell`, `--sell-soft`, `--sell-line`: buying and selling, gains and losses. W-DEX owns their use. - DeSci accent: `--science`, `--science-soft`, `--science-line` (data, models, sealed assets, figures). - Feedback: `--ok`, `--warn`, `--danger` with `-soft` and `-line`. States: `--st-` with `-ink` and `-line` (the gov.html pairs). Votes: `--yes`, `--no`, `--veto`, `--abstain`. Data palette, in order: `--d1` … `--d6`. - Shapes: `--r-window` 14px (windows, popovers, modals), `--r-row` 12px (rows in windows, notices), `--r-ctl` 10px (buttons, inputs, selects), `--r-chip` 6px (code), `--r-pill` (pills, badges). Windows have no shadow; popovers, menus and modals use `--shadow-pop`. - Type: `--sans` Inter (interface), `--serif` Source Serif 4 (documents), `--mono` JetBrains Mono (addresses, hashes, block numbers, numeric table cells). Sizes `--fs-12` `--fs-13` `--fs-14` `--fs-15` (base) `--fs-17` `--fs-20` `--fs-24` `--fs-30` `--fs-38` `--fs-48`, and `--fs-display` (`clamp(40px, 4.2vw, 64px)`, page heroes; class `.display`). Headings 600–650, tight tracking. - Layout: `--max` 1600px (the content frame, inside the content column), `--gutter` `clamp(16px, 2.6vw, 40px)`, `--topbar` 64px, `--side` 256px (the sidebar; 0 below 1024px, where it is a drawer), `--aside` 360px. Sticky things inside a page stick at `top: var(--topbar)`. Which class for which purpose: | purpose | classes | |---|---| | page frame | `.frame` (alias `.shell`): `--max` wide with gutters; `.page` adds vertical padding | | full-width sections | `
` with `
` (`.alt` on `--bg-2`, `.band-head` for a page masthead) each holding a `.frame` | | page header | `.crumbs` (breadcrumb `