Design Log #28 — Static Filename Validation for CDN

Written for AI agents. See Log Methodology Note below for details.

Background

When wix-deploy uploads frontend files to Wix CDN, filenames with spaces break. The CDN redirects spaces to hyphens — so a file uploaded as /Jay Logo 2.png becomes /Jay-Logo-2.png, but the HTML still references /Jay Logo 2.png. Result: broken images on the deployed site.

The same issue manifests locally when using the generated serve.mjs (the server resolves paths correctly, but it indicates the site won't work once deployed).

Wix DL#19 — Wix Media Plugin
Wix DL#22 — Wix Deploy Pipeline

Problem

No validation catches this before deploy. The user deploys, sees broken images, and has to debug the CDN path mismatch manually.

When wix-media is installed, images get uploaded to Wix Media Manager and served from wixstatic.com with proper optimization — the CDN filename issue doesn't apply. But for projects without wix-media, local images go straight to CDN as static files.

Design

Add a jay-html validator to wix-deploy that flags local image paths containing spaces.

Validator behavior

Walk <img>, <video>, <source> elements for src attributes, and <link> elements for href
For fully static values (no bindings): check if it's a local path (not http://, https://, or a data URL)
If the path contains a space → report an error
No special check for wix-media needed — images uploaded to Wix Media Manager have wixstatic.com URLs (not local paths) and naturally won't be flagged

Error message

Static file path '/Jay Logo 2.png' contains spaces — Wix CDN replaces spaces with
hyphens, breaking the reference. Rename the file to '/Jay-Logo-2.png' and update all
references in jay-html files.

Scope

Only checks local paths. Bindings ({product.image}) are skipped — they resolve at runtime and typically come from Wix APIs (already on wixstatic.com).

Also checks <link href="..."> for favicons and other static assets with spaces.

Implementation Plan

Phase 1: Create the validator

Create packages/wix-deploy/lib/validators/static-filename-validator.ts
Follow the pattern from packages/wix-media/lib/validators/media-validator.ts
Export as validate: JayHtmlValidatorFn

Phase 2: Wire it up

Add validator declaration to packages/wix-deploy/plugin.yaml
Export from packages/wix-deploy/lib/index.ts
Add @jay-framework/compiler-shared and @jay-framework/compiler-jay-html as dependencies

Verification Criteria

npm run validate flags local image paths with spaces
Images without spaces are not flagged
Dynamic bindings are not flagged
External URLs (https://...) are not flagged

Log Methodology Note

Note: These design logs are written primarily for AI agents as part of the Design Log methodology and made accessible here for human readers. The language and structure are optimized for machine consumption — expect precise, specification-style prose rather than narrative documentation.

Static-Filename-Validation-For-Cdn