# Zeyad's Stuff

Apps, games and utilities with a private website relay. This branch contains UI version **2.2.0**. Production remains at the existing Worker deployment until these changes are reviewed and deployed.

The hub includes searchable cards, a selected-item panel, favorites, editable HTTPS shortcuts, HTML-game imports, Snake, Memory Match, notes, a focus timer and a calculator. Settings save in browser storage: theme, any hex accent, icon set, loading, motion, compact layout and launch behavior. Backups include local games and notes. Imported games run in a sandbox.

## Develop

Use Node.js 22 or newer:

```sh
npm ci
npm run types
npm run dev
```

The default origin is http://127.0.0.1:8787. Loopback development does not require the online relay passphrase. A separate checkout can run `npx wrangler dev --ip 127.0.0.1 --port 8788` after `npm run prepare:assets`; the Wisp lab's origin restrictions still apply.

## Relay architecture

Scramjet rewrites pages in the browser. A same-origin Bare v3 transport connects to the Cloudflare Worker. The Worker validates destinations and requires a signed user session online. WebSockets use Cloudflare. Discord-family HTTP requests can use Render, or opt-in Jimmy with read-only fallback to Render. Other permitted hosts use the Worker directly. Transport support does not prove that sign-in or every website feature works.

The hub loads the browser engine only when a relay is opened. Cards can use direct mode instead, and the relay toolbar offers Retry, Open direct and Open in a tab. Fullscreen and top-bar hide/restore remain available.

See [RENDER_INTEGRATION.md](RENDER_INTEGRATION.md), [JIMMY_INTEGRATION.md](JIMMY_INTEGRATION.md), and [UI_REVIEW.md](UI_REVIEW.md) for configuration and verification boundaries. Backend tokens stay in server secrets. Never commit `.dev.vars` or send account credentials in configuration.

## Local Wisp experiment

The independent [local Wisp lab](experiments/local-wisp/README.md) listens on 127.0.0.1:3100 and accepts only its documented localhost:8787 origins. It has destination and stream restrictions and is not a production relay. Its diagnostics live at `/transport-lab.html`. Tests of public pages do not establish account-login compatibility.

```sh
npm --prefix experiments/local-wisp install
npm --prefix experiments/local-wisp test
npm --prefix experiments/local-wisp start
```

## Single HTML file

Download HTML under Settings or use `public/ZeyadsStuffV2.html`. The builder embeds the font, icons, images, hub JavaScript and styles; games and tools run locally. Relay mode embeds the hosted `/embed` view and needs internet and the relay passphrase. Browsers that block embedded sessions need Open in a tab. Local-file storage varies, so export a backup before moving or renaming the file. Single-file games must embed their own assets.

```sh
npm run prepare:assets
node scripts/check-single.mjs
```

## Verify

```sh
npm run types
npm run check
npm test
npm --prefix experiments/local-wisp test
npm run build
```

`npm run build` is a Worker dry run; it does not publish. Browser verification and remaining limits are in [UI_REVIEW.md](UI_REVIEW.md). The stream timeout correction from PR #10 is included in this branch; avoid duplicating it during integration.

## Deploy

```sh
npx wrangler login
npx wrangler secret put PROXY_PASSWORD
npm run deploy
```

Set backend secrets privately if using Render or Jimmy. Deploy a preview first. Do not merge this branch into main or replace production before reviewing it.

## Source

- `public/hub.js`, `public/hub-model.js`: hub behavior, validation, library views and tools.
- `public/index.html`, `public/style.css`, `public/personality.css`, `public/ui-refinement.css`: UI.
- `public/app.js`, `public/sw.js`: browser engine, relay launch and recovery.
- `src/index.ts`, `src/policy.ts`, `src/session.ts`: routes, destination policy, authentication.
- `src/relay.ts`, `src/render.ts`, `src/jimmy.ts`: transports and safe backend selection.
- `scripts/prepare-assets.mjs`, `scripts/build-single.mjs`: reproducible assets and standalone build.

Engine versions are pinned. See [THIRD_PARTY.md](THIRD_PARTY.md) for Scramjet, Bare transport, icon and asset credits. The build exposes an explicit source whitelist under `/source/`; credentials and local environment files are excluded.