SILVER
/
NODEDC_SITE
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
NODEDC_SITE/docs/refactor-admin-plan.md

7.3 KiB
Raw Blame History

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
  1. 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.
  • heroWaitlist and featureVideo expose typed content fields in JSON and the local admin.
  • Block templates support {{text:path}}, {{html:path}}, and {{attr:path}} tokens rendered by tools/render-home.mjs.

Current guarantee:

  • Rendering through npm run render:home has byte-for-byte parity with the pre-refactor index.html.

Current limitation:

  • Only the first two home blocks have typed fields so far. The remaining blocks are still HTML-template blocks. The admin can manage order, enabled state, duplication, copy/paste, IDs, labels, anchors, typed fields where available, and raw block JSON.
  • 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.