Christmas Lights Test App

The Christmas Lights Test App is a standalone pilot for building holiday-light designs before the new workflow moves into Clean Estimate Pro. It replaces the legacy drawing approach with an editor built around individual, verifiable roof sections. The current CE Pro Holiday Lights module remains the production workflow until this pilot and its data migration are approved.

Google Maps and Apify lookup are test-only provider options. Use them only in an explicitly approved test environment with the required provider access. Their inclusion in this pilot does not grant production usage rights.

Start from a property

Enter the property address to begin. In approved test mode, the app can use Google address and Street View services or Apify listing results to locate reference images. The app uses those images to prepare an initial trace and display concept.

An exact-address test request fails closed. If Apify cannot resolve that house, the quote runner stops for manual review instead of silently selecting a random listing. Operator-supplied imagery must still match the requested street and ZIP before analysis or email delivery can continue.

Use the fallback workflow when imagery is missing, blocked, out of date, or too unclear to support a reliable design:

1. Upload a current front-facing property photo.
2. Draw or correct the roof sections manually.
3. Mark uncertain sections for review before sending the proposal.

Low-confidence properties stay in manual review. A design should not advance automatically when the app cannot build a reliable Good package.

Verify the roof-line drawing

The editor separates the drawing into two roof-line groups:

Every section has its own measurement. Select a section to adjust its endpoints, change its type, edit its measured length, verify it, or delete it. Add missing sections directly on the property image. The target is measurement accuracy within 10 percent; uncertain or uncalibrated measurements require manual review.

A main-ridge selection is normalized to the full installable span of the main roof. A short center-only fragment, such as only the section between dormers, is rejected or expanded instead of being treated as the complete ridge. Use separate ridge segments on each side of a chimney, dormer, or other real obstruction that prevents one continuous installation run.

Roof-line C9 bulbs use 15-inch spacing by default. Contractors can change that setting. Large evergreen outside wraps can use wider C9 spacing, commonly 24 to 36 inches, without changing the roof-line default.

Build Good, Better, and Best

The app prices designs from the contractor's price book and prepares three starting packages:

These ranges guide the automatic package builder; they are not fixed prices. If the available primary roof line cannot create a credible Good package in its target range, the project is flagged for manual review instead of forcing extra scope into the design.

The pilot price book currently starts C9 roof lines at $9 per foot and mini lights at $50 per strand. Wreath defaults are $50 for 24 inches, $225 for 36 inches, $485 for 48 inches, and $900 for 60 inches. Contractors can change these values in Contractor settings.

The operator-only random quote test selects one live Lancaster-area listing through Apify, analyzes its exterior, applies the contractor price book, and emails all three packages only to the configured test recipient. It does not contact the listing agent or change outreach records. Designs with uncalibrated measurements remain flagged for contractor review. The Apify adapter expands the listing gallery template so front, side, and detail photos remain available when the provider returns them.

Each emailed package includes its own labeled lighting mockup. The Good, Better, and Best images show only the roof sections and decorative zones included in that option, so the customer can see what changes with the price.

Add wreaths and landscape lighting

Available design elements include:

• Wreaths in 24, 36, 48, and 60 inches. The 60-inch option is generally used on

commercial properties.

• Mini-light wraps for bushes, trees, and columns.
• Garland priced and placed by strand.
• Pathway lights and other contractor-approved display items.

Suggested starting quantities are 1 to 2 strands for a small bush, 3 strands for a larger bush, 2 strands for a skinny column, and 3 strands for a larger column. A tree outside wrap commonly starts with 4 to 6 strands around the canopy plus a tighter trunk wrap. These are design defaults, not customer-facing material commitments, and the contractor can change them.

Warm white is the default color. Red and green are standard stock choices. Each contractor controls the approved color list, and the designer can use another color when the contractor allows it.

Use Contractor settings to maintain the business name, approved colors, roof-line and evergreen spacing, deposit percentage, lease or sale model, and every customer-facing price-book rate. Saved defaults seed each new design; changing one project does not rewrite the contractor's price book.

Prepare the customer proposal

The test app opens with the Hillcrest property as its default demo. The app keeps all three package designs and finished images saved.

Use Edit mode to verify or change the design. Measurements, tracing lines, control handles, and guide bulbs appear only in Edit mode. Use Finished mode to review the saved photorealistic Good, Better, and Best images without drawing tools or design guides over the home.

The finish workflow creates one winter background from the clean property photo, then gives each package a strict masked gpt-image-2 finish. The edit mask is limited to that package's allowed lighting scope, and the client clips the result to the same allowed area before saving it. This keeps the facade, roof geometry, framing, and excluded decor unchanged.

Final package images are saved as PNG files in R2 when object storage is configured. A data fallback is used only for local development or environments without storage. The customer proposal displays the saved Finished image for the package the customer selects.

Lighting render fidelity

Roof-line C9 bulbs render as small white-hot cores with restrained bloom and light spill, so each bulb stays distinct instead of becoming a thick glowing line. Mini lights use dense, slightly irregular placement based on the saved strand count; adding strands increases visible coverage without changing the decor boundary.

The renderer applies those effects to the exact saved package scope. It does not add roof sections, decor, or bulbs that are absent from the selected Good, Better, or Best design, so every customer image remains deterministic and can be checked against Edit mode.

Customer proposals show the package name, package description, line items, and price. They do not promise exact footage or strand counts because installation conditions can change on site. The service price includes design, installation, in-season maintenance, takedown, and storage unless the contractor changes the offer.

Customers can choose a package, request a color change, sign, and pay the required deposit. The default deposit is 50 percent and can be changed in the contractor's settings. Contractors can use a lease or sale model and define the next-season price rule; a lease can keep the same price when the design does not change.

Clean Estimate Pro bridge status

The pilot owns its drawing, measurements, package logic, saved designs, and test proposal workflow. It does not replace the production CE Pro Holiday Lights module yet. A future bridge must map approved projects, price-book items, proposal status, signatures, and deposits into CE Pro before the legacy holiday light workflow can be removed safely.

Until that bridge is enabled, treat the pilot and the existing CE Pro module as separate systems. Verify any customer or payment record that must appear in both.