216 lines
7.1 KiB
Markdown
216 lines
7.1 KiB
Markdown
# 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.
|
|
|
|
## Phase 1 Implementation Status
|
|
|
|
Started on June 25, 2026.
|
|
|
|
Implemented:
|
|
|
|
- `content/pages/home.json` contains the first ordered block model for the home page.
|
|
- `templates/pages/home/shell.html` contains the current Webflow shell with two render slots.
|
|
- `templates/pages/home/blocks/` contains exact HTML block chunks extracted from the current localized page.
|
|
- `tools/render-home.mjs` renders `index.html` from the JSON model and templates.
|
|
- `tools/extract-home-blocks.mjs` can regenerate the first template split from the current `index.html`.
|
|
- `tools/admin-server.mjs` and `admin/` provide a local block editor.
|
|
|
|
Current guarantee:
|
|
|
|
- Rendering through `npm run render:home` has byte-for-byte parity with the pre-refactor `index.html`.
|
|
|
|
Current limitation:
|
|
|
|
- Blocks are still HTML-template blocks. The admin can manage order, enabled state, duplication, copy/paste, IDs, labels, anchors, and raw block JSON. The next pass must extract text/media fields from each block template into typed JSON fields.
|
|
- The `c-viz` wrapper is preserved as a region boundary because it is coupled to WebGL/color-flip behavior. Blocks inside that region should stay inside it until the runtime is better understood.
|
|
|
|
## 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.
|