fix: clarify response header settings and hosting support

apps/builder/app/shared/project-settings/section-headers.tsx

@@ -72,15 +72,14 @@ export const SectionHeaders = () => {
           {allowDynamicData === false && <ProChip>PRO</ProChip>}
         </Flex>
         <Text color="subtle">
-          Customize HTTP response headers for all pages on Webstudio Cloud.
-          Publish your site to apply changes. Asset files and the Builder are
-          unaffected.
+          Set or remove HTTP response headers for your site. Publish to apply
+          changes.
         </Text>
         {allowDynamicData === false && (
           <>
             <Text color="subtle">
-              Custom headers are a Pro feature. You can publish to staging for
-              free; upgrade to Pro to publish to custom domains.
+              Publishing custom headers to a custom domain requires Pro. Staging
+              is free.
             </Text>
             <LinkButton
               color="primary"
@@ -105,7 +104,7 @@ export const SectionHeaders = () => {
             checked={remove}
             onCheckedChange={(checked) => setRemove(checked === true)}
           />
-          <Label htmlFor={removeId}>Remove this header from responses</Label>
+          <Label htmlFor={removeId}>Remove header</Label>
         </CheckboxAndLabel>
         {!remove && (
           <>
@@ -166,9 +165,7 @@ export const SectionHeaders = () => {
       <Separator />
       <Grid gap={3} css={sectionSpacing}>
         {headers.length === 0 && (
-          <Text color="subtle">
-            No custom headers. Webstudio defaults apply.
-          </Text>
+          <Text color="subtle">No headers configured.</Text>
         )}
         {headers.map((header) => (
           <Grid key={header.name} gap={1}>
@@ -177,9 +174,9 @@ export const SectionHeaders = () => {
             </Text>
             <Text color="subtle" css={{ overflowWrap: "anywhere" }}>
               {header.value === null
-                ? "Remove from responses"
+                ? "Remove header"
                 : header.value === ""
-                  ? "Set to an empty value"
+                  ? "Empty value"
                   : header.value}
             </Text>
             <Flex gap={2}>
@@ -208,15 +205,11 @@ export const SectionHeaders = () => {
                   }
                 }}
               >
-                Delete
+                Delete rule
               </Button>
             </Flex>
           </Grid>
         ))}
-        <Text color="subtle">
-          Deleting a configuration restores the default behavior after
-          publishing.
-        </Text>
       </Grid>
     </Grid>
   );

docs/university/foundations/project-settings.md

@@ -146,15 +146,17 @@ For a single page, you can also configure authentication directly in [Page setti
 
 ## Headers
 
-Use **Project settings > Headers** to customize HTTP response headers for all pages published to Webstudio Cloud.
+Use **Project settings > Headers** to set or remove HTTP response headers for your site.
 
-Custom headers are a Pro feature on custom domains. You can configure and publish them to staging for free. When a Free-plan project uses custom headers, the Publish dialog lists **Custom headers** among its Pro features and requires an upgrade or removal of the configuration before publishing to a custom domain.
+On Webstudio Cloud, publishing custom headers to a custom domain requires Pro. Staging is free.
 
 1. Enter a header name, such as `Content-Security-Policy`.
-2. Enter its value, or select **Remove this header from responses** to omit it entirely.
+2. Enter its value, or select **Remove header** to remove it from the response.
 3. Click **Add header** and publish the site.
 
-Custom values replace Webstudio's defaults. Headers without custom configuration retain their defaults. An empty value sets an empty header; it does not remove the header. Use **Edit** to change an existing configuration, or **Delete** to restore the default behavior after publishing.
+An empty value sends the header with no value. **Remove header** removes the header, while **Delete rule** stops overriding it. Publish again after changing a rule.
+
+These are standard HTTP headers. Webstudio Cloud applies the rules automatically to site responses. On other hosts, your server or hosting adapter must apply the configuration generated by the CLI in `app/__generated__/$resources.headers.server.ts`. Any proxy or CDN must preserve the resulting headers. Other hosting templates and static exports do not apply these rules automatically.
 
 For example, to allow a site to be embedded by `https://example.com`, set `Content-Security-Policy` to `frame-ancestors 'self' https://example.com` and add a removal configuration for `X-Frame-Options`.
 
@@ -162,7 +164,7 @@ Header names are case-insensitive and must be unique. Values cannot contain line
 
 Custom cache directives do not override private/no-store responses, including authenticated pages. Public pages can use custom cache settings.
 
-These settings apply to responses from the published Cloud site, including redirects and site errors. They do not apply to the Builder, static assets served by the CDN, or static exports. Changes require republishing.
+On Webstudio Cloud, the rules also apply to redirects and site errors. Static assets served by the CDN keep their existing headers.
 
 ## Marketplace
 

packages/cli/src/response-headers.ts

@@ -14,7 +14,7 @@ export const generateResponseHeadersModule = (
   const revision = createHash("sha256")
     .update(JSON.stringify([deploymentId, headers]))
     .digest("hex");
-  return `// Generated at publish time. Consumed by the Webstudio Cloud worker.
+  return `// Generated response header configuration for hosting adapters.
 export const customHeaders: Array<{ name: string; value: string | null }> = ${JSON.stringify(headers, null, 2)};
 export const responseHeadersCacheName = "file-cache-headers-${revision}";
 `;

packages/project-build/src/contracts/__generated__/runtime-operation-contracts.ts

@@ -5405,7 +5405,7 @@ export const runtimeOperationContractData = [
             },
             customHeaders: {
               description:
-                "Project-wide response headers for Webstudio Cloud. A null header value removes that header; an empty string sets an empty value. Publish to apply changes.",
+                "Site-wide HTTP response headers. A null value removes the header; an empty string sets an empty value. Apply through the hosting adapter when publishing.",
               maxItems: 50,
               type: "array",
               items: {
@@ -5552,7 +5552,7 @@ export const runtimeOperationContractData = [
               anyOf: [
                 {
                   description:
-                    "Project-wide response headers for Webstudio Cloud. A null header value removes that header; an empty string sets an empty value. Publish to apply changes.",
+                    "Site-wide HTTP response headers. A null value removes the header; an empty string sets an empty value. Apply through the hosting adapter when publishing.",
                   maxItems: 50,
                   type: "array",
                   items: {

packages/sdk/src/schema/pages.ts

@@ -223,7 +223,7 @@ export const projectMeta = z.object({
   customHeaders: customResponseHeaders
     .optional()
     .describe(
-      "Project-wide response headers for Webstudio Cloud. A null header value removes that header; an empty string sets an empty value. Publish to apply changes."
+      "Site-wide HTTP response headers. A null value removes the header; an empty string sets an empty value. Apply through the hosting adapter when publishing."
     ),
 });
 export type ProjectMeta = z.infer<typeof projectMeta>;