NODEDC_SITE/docs/refactor-admin-plan.md

# NODE.DC Block Refactor And Admin Plan

## Goal

Turn the current Webflow-exported page into a managed block-based source without changing the visual result.

The first version of the admin should edit only the content layer: text, links, media references, repeated items, and block order. Motion, WebGL, dock behavior, notification behavior, and responsive layout stay in code.

## Non-Negotiables

- Visual parity with the current page on desktop, tablet, and mobile.
- Existing responsive behavior must survive the refactor.
- Existing interactive shell must survive: top bar, dock, floating app windows, WebGL canvas, notifications, sliders, forms.
- Content blocks must be reorderable, duplicatable, and toggleable.
- No direct HTML editing in the admin.
- Optimization must be measured before and after each major step.

## Current Baseline

Measured on June 25, 2026 with Lighthouse against local servers:

| Target | Performance | Accessibility | Best Practices | SEO | FCP | LCP | TBT | Total byte weight |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| `127.0.0.1:8081` working copy | 43 | 91 | 100 | 92 | 2.6s | 14.4s | 1330ms | 24,423 KiB |
| `127.0.0.1:8080` original copy | 60 | 91 | 100 | 92 | 4.3s | 10.1s | 180ms | 17,273 KiB |

Main risk areas:

- `assets/media` is 53 MB.
- Main page has 17 `<video>` tags.
- Largest transferred assets in the working copy are videos.
- `assets/custom/js/app.js` is about 295 KB transferred locally.
- Current local copy loads heavier than the original because CDN compression/range/caching behavior is not equivalent to the local Python server.

Video file compression is outside this refactor scope. The media files can be compressed separately. The refactor is responsible for loading strategy only: offscreen videos should not be eagerly initialized or downloaded when the user does not need them yet.

## Performance Budget

Minimum target after block refactor:

- No regression against the current visual page at desktop/tablet/mobile.
- Lighthouse performance should not drop below the current working baseline during intermediate steps.
- Target after optimization pass: performance 75+ locally, then re-check in production-like hosting.
- LCP target: under 4s in production-like conditions.
- TBT target: under 300ms.
- Initial page must not eagerly initialize every video/module when offscreen.

## Recommended Architecture

Use a two-step migration.

### Phase 1: Static Block Engine

Before connecting a CMS, build a local block renderer:

- `content/pages/home.json` stores page blocks.
- `src/blocks/*` or `templates/blocks/*` render each block type.
- Renderer outputs static HTML or a local app route.
- Current CSS/assets/runtime are reused until visual parity is proven.

Reason: this isolates the risky part. We prove the content model and responsive rendering before adding admin complexity.

### Phase 2: Admin/CMS

Use Payload CMS for the first real admin because its block field maps directly to this requirement:

- one page has an ordered `blocks` array;
- each block has its own fields;
- admin can edit fields without touching markup;
- custom admin controls can later add duplicate/copy/paste affordances.

Admin UX target:

- left sidebar: ordered block list;
- right panel: selected block editor;
- controls: enable/disable, duplicate, copy, paste, move up/down, drag reorder;
- preview link opens the rendered page;
- fields are scoped to content only.

## Block Types

Initial home page block types:

1. `heroWaitlist`
   - headings
   - intro copy
   - side feature cards
   - form labels/placeholders/buttons
   - app card logo/title/release note

2. `featureVideo`
   - heading
   - intro copy
   - feature list
   - video source
   - window title

3. `componentLibrary`
   - heading
   - intro copy
   - slider items
   - media list

4. `featureCluster`
   - heading groups
   - rich text groups
   - optional center 3D/visual target config

5. `modesGallery`
   - heading
   - intro copy
   - slider/gallery items

6. `faq`
   - heading
   - intro copy
   - CTA link
   - questions array

7. `pricingIntro`
   - eyebrow
   - heading lines
   - intro text blocks

8. `pricingTable`
   - plans
   - rows
   - CTA labels/links
   - notes

9. `fileGallery`
   - media cards
   - window titles
   - icon labels

10. `waitlistMessages`
   - message files
   - names
   - text contents

11. `footer`
   - brand
   - copyright
   - navigation links
   - contact links
   - policy links

Global non-block content:

- navigation
- dock
- notification timeline
- WebGL canvas shell
- shared app/window chrome
- forms runtime/API behavior

## Refactor Order

1. Create content model and block schema.
2. Extract current page content into JSON.
3. Render one block at a time from JSON while keeping CSS/classes intact.
4. After each block extraction, compare screenshots at:
   - desktop: 1440x900 or current browser size;
   - tablet: 1024x768;
   - mobile: 390x844.
5. Add Payload CMS only after static JSON rendering is visually stable.
6. Optimize media and runtime after block rendering is stable.

## Optimization Passes

Do after structural parity, not before:

- Make offscreen videos lazy: no eager load for hidden sliders/windows.
- Add posters for videos.
- Keep video source fields editable so compressed replacements can be dropped in without markup changes.
- Prefer CDN/prod-like compression for performance testing.
- Split heavy runtime modules if possible.
- Delay WebGL/model initialization until it is needed.
- Avoid duplicate hidden DOM copies where possible.
- Keep forms and API code out of the first render path when not visible.

## Verification Checklist

For each completed block:

- Desktop screenshot matches current design.
- Tablet screenshot matches current design.
- Mobile screenshot matches current design.
- No text overlap in Russian.
- Block can be disabled without breaking the rest of the page.
- Block can be duplicated and rendered twice.
- Block can move order in the JSON model.
- Lighthouse metrics are recorded after the milestone.