@wocart/theme 2.3.0 → 3.1.0

package/dist/blocks.d.ts

@@ -19,12 +19,30 @@ export declare const THEME_LIMITS: {
 };
 export declare const COMPONENT_PLACEMENTS: readonly ["section", "block", "both"];
 export declare const COMPONENT_ROLES: readonly ["order-form"];
+/** The surface every landing page's own document follows: its rules, its shipped document. */
+export declare const LANDING_TEMPLATE = "landing";
 /** The surface an area's document is stored under: `area:<key>`. */
 export declare function areaSurface(key: string): string;
-/** The shipped document for a surface or an area, when the theme declares one. */
+/**
+ * The surface a landing page's own document is stored under: `lp:<id>`, by
+ * the page's id, which stays when its slug changes. A landing page is a
+ * campaign of its own, so each has its own document; the theme's `landing`
+ * surface gives every one of them its rules and its starting document.
+ */
+export declare function landingSurface(id: string): string;
+/** The surface whose rules and shipped document a document follows: `landing` for a landing page's own `lp:<id>`, the surface itself otherwise. */
+export declare function templateSurface(surface: string): string;
+/**
+ * The shipped document for a surface or an area, when the theme declares one.
+ * A landing page's own surface gets the `landing` document, addressed to it.
+ */
 export declare function shippedDocument(theme: ThemeDefinition, surface: string): PageData | undefined;
-/** Whether a theme composes a surface: one it declares, or one of its areas. */
+/** Whether a theme composes a surface: one it declares, a landing page's own when it declares `landing`, or one of its areas. */
 export declare function composesSurface(theme: ThemeDefinition, surface: string): boolean;
+/** The areas a page of this surface may leave out: the surface's `hideableAreas` the theme declares as areas. */
+export declare function hideableAreas(theme: ThemeDefinition, surface: string): string[];
+/** Whether a page shows one of the theme's areas: it does unless its document leaves it out and its surface allows that. */
+export declare function isAreaShown(theme: ThemeDefinition, page: PageData, key: string): boolean;
 /** The id a fixed block renders with while the document does not store it. */
 export declare function fixedBlockId(ownerId: string, name: string): string;
 /** Whether a component may be placed at the top level (`"section"`) or in a slot (`"block"`). */

package/dist/blocks.js

@@ -12,19 +12,52 @@ export const THEME_LIMITS = {
 export const COMPONENT_PLACEMENTS = ["section", "block", "both"];
 export const COMPONENT_ROLES = ["order-form"];
 const AREA_PREFIX = "area:";
+const LANDING_PREFIX = "lp:";
+/** The surface every landing page's own document follows: its rules, its shipped document. */
+export const LANDING_TEMPLATE = "landing";
 /** The surface an area's document is stored under: `area:<key>`. */
 export function areaSurface(key) {
     return `${AREA_PREFIX}${key}`;
 }
-/** The shipped document for a surface or an area, when the theme declares one. */
+/**
+ * The surface a landing page's own document is stored under: `lp:<id>`, by
+ * the page's id, which stays when its slug changes. A landing page is a
+ * campaign of its own, so each has its own document; the theme's `landing`
+ * surface gives every one of them its rules and its starting document.
+ */
+export function landingSurface(id) {
+    return `${LANDING_PREFIX}${id}`;
+}
+/** The surface whose rules and shipped document a document follows: `landing` for a landing page's own `lp:<id>`, the surface itself otherwise. */
+export function templateSurface(surface) {
+    return surface.startsWith(LANDING_PREFIX) ? LANDING_TEMPLATE : surface;
+}
+/**
+ * The shipped document for a surface or an area, when the theme declares one.
+ * A landing page's own surface gets the `landing` document, addressed to it.
+ */
 export function shippedDocument(theme, surface) {
     if (surface.startsWith(AREA_PREFIX))
         return (theme.areas ?? []).find((area) => areaSurface(area.key) === surface)?.document;
-    return (theme.surfaces ?? []).find((spec) => spec.key === surface)?.document;
+    const template = templateSurface(surface);
+    const document = (theme.surfaces ?? []).find((spec) => spec.key === template)?.document;
+    return document === undefined || template === surface ? document : { ...document, surface };
 }
-/** Whether a theme composes a surface: one it declares, or one of its areas. */
+/** Whether a theme composes a surface: one it declares, a landing page's own when it declares `landing`, or one of its areas. */
 export function composesSurface(theme, surface) {
-    return (theme.surfaces ?? []).some((spec) => spec.key === surface) || (theme.areas ?? []).some((area) => areaSurface(area.key) === surface);
+    const template = templateSurface(surface);
+    return (theme.surfaces ?? []).some((spec) => spec.key === template) || (theme.areas ?? []).some((area) => areaSurface(area.key) === surface);
+}
+/** The areas a page of this surface may leave out: the surface's `hideableAreas` the theme declares as areas. */
+export function hideableAreas(theme, surface) {
+    const template = templateSurface(surface);
+    const spec = (theme.surfaces ?? []).find((candidate) => candidate.key === template);
+    const declared = new Set((theme.areas ?? []).map((area) => area.key));
+    return (spec?.hideableAreas ?? []).filter((key) => declared.has(key));
+}
+/** Whether a page shows one of the theme's areas: it does unless its document leaves it out and its surface allows that. */
+export function isAreaShown(theme, page, key) {
+    return !(page.hiddenAreas ?? []).includes(key) || !hideableAreas(theme, page.surface).includes(key);
 }
 /** The id a fixed block renders with while the document does not store it. */
 export function fixedBlockId(ownerId, name) {
@@ -46,9 +79,10 @@ export function surfaceRules(theme, surface) {
         return { ...(area?.required === undefined ? {} : { required: area.required }), ...(area?.max === undefined ? {} : { max: area.max }) };
     }
     const surfaces = theme.surfaces ?? [];
-    const own = surfaces.find((spec) => spec.key === surface);
-    const dot = surface.indexOf(".");
-    const base = dot > 0 ? surfaces.find((spec) => spec.key === surface.slice(0, dot)) : undefined;
+    const key = templateSurface(surface);
+    const own = surfaces.find((spec) => spec.key === key);
+    const dot = key.indexOf(".");
+    const base = dot > 0 ? surfaces.find((spec) => spec.key === key.slice(0, dot)) : undefined;
     const required = own?.required ?? base?.required;
     const max = own?.max ?? base?.max;
     return { ...(required === undefined ? {} : { required }), ...(max === undefined ? {} : { max }) };

package/dist/composition.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentDefinition, ComponentInstance, ComponentSpec, ThemeDefinition } from "./types.js";
-/** Whether a surface key is `entry` itself or one of its alternates (`product.compact` for `product`). */
+/** Whether a surface key is `entry` itself or one of its alternates (`product.compact` for `product`); a landing page's own `lp:<id>` is covered by `landing`. */
 export declare function surfaceCovers(entry: string, surface: string): boolean;
 /**
  * Whether an editor may insert this component on `surface`: it is not marked

package/dist/composition.js

@@ -3,10 +3,12 @@
  * where a component may go, and how a preset becomes instances. Pure: no
  * I/O, no randomness — ids come from the caller.
  */
+import { templateSurface } from "./blocks.js";
 import { createInstance } from "./instances.js";
-/** Whether a surface key is `entry` itself or one of its alternates (`product.compact` for `product`). */
+/** Whether a surface key is `entry` itself or one of its alternates (`product.compact` for `product`); a landing page's own `lp:<id>` is covered by `landing`. */
 export function surfaceCovers(entry, surface) {
-    return surface === entry || surface.startsWith(`${entry}.`);
+    const key = templateSurface(surface);
+    return key === entry || key.startsWith(`${entry}.`);
 }
 /**
  * Whether an editor may insert this component on `surface`: it is not marked

package/dist/definitions.js

@@ -4,7 +4,7 @@
  * data — the validator exists so a theme's test suite fails loudly on catalog
  * bugs when the catalog is assembled.
  */
-import { COMPONENT_PLACEMENTS, COMPONENT_ROLES, THEME_LIMITS, areaSurface, guaranteedRole, innerGuarantees, placementAllows, surfaceRules, } from "./blocks.js";
+import { COMPONENT_PLACEMENTS, COMPONENT_ROLES, THEME_LIMITS, areaSurface, LANDING_TEMPLATE, guaranteedRole, innerGuarantees, placementAllows, surfaceRules, } from "./blocks.js";
 import { instantiatePreset, surfaceCovers } from "./composition.js";
 import { conditionProblem } from "./conditions.js";
 import { COLOR_SCHEME_ID_PATTERN, STYLE_PANELS, STYLE_STEPS, STYLE_WIDTHS, colorSchemesProblem, styleSizeProblem, styleValueProblem, } from "./style.js";
@@ -117,7 +117,8 @@ export function validateThemeDefinition(theme, options = {}) {
             addIssue(issues, "surfaces", "invalid-theme", "`surfaces` must be an array of surface declarations");
         }
         else {
-            inspectSurfaces(theme.surfaces, issues, locales, new Set(Object.keys(theme.components)));
+            const areaKeys = new Set((Array.isArray(theme.areas) ? theme.areas : []).map((area) => (isRecord(area) ? area.key : undefined)).filter((key) => typeof key === "string"));
+            inspectSurfaces(theme.surfaces, issues, locales, new Set(Object.keys(theme.components)), areaKeys);
         }
     }
     if (theme.areas !== undefined)
@@ -324,7 +325,7 @@ function inspectAreas(areas, issues, locales, catalogKeys) {
         inspectBlockBounds(area, path, issues, catalogKeys, THEME_LIMITS.sections, "invalid-theme");
     });
 }
-function inspectSurfaces(surfaces, issues, locales, catalogKeys) {
+function inspectSurfaces(surfaces, issues, locales, catalogKeys, areaKeys) {
     const seenKeys = new Set();
     surfaces.forEach((surface, index) => {
         const surfacePath = `surfaces[${index}]`;
@@ -349,6 +350,28 @@ function inspectSurfaces(surfaces, issues, locales, catalogKeys) {
         if (surface.pageType !== undefined && !PAGE_TYPES.includes(surface.pageType)) {
             addIssue(issues, `${surfacePath}.pageType`, "invalid-theme", `\`pageType\` must be one of ${PAGE_TYPES.join(", ")}`);
         }
+        if (typeof surface.key === "string" && (surface.key.startsWith("lp:") || surface.key.startsWith("area:"))) {
+            addIssue(issues, `${surfacePath}.key`, "invalid-theme", `"${surface.key}" uses a prefix the platform keeps for a landing page's or an area's own document`);
+        }
+        if (surface.key === LANDING_TEMPLATE && surface.pageType !== "landing") {
+            addIssue(issues, `${surfacePath}.pageType`, "invalid-theme", `the "${LANDING_TEMPLATE}" surface renders landing pages: its \`pageType\` is "landing"`);
+        }
+        if (surface.pageType === "landing" && typeof surface.key === "string" && surface.key !== LANDING_TEMPLATE) {
+            addIssue(issues, `${surfacePath}.key`, "invalid-theme", `landing pages are composed by the "${LANDING_TEMPLATE}" surface; each page's own document follows it`);
+        }
+        if (surface.hideableAreas !== undefined) {
+            const listed = surface.hideableAreas;
+            if (!Array.isArray(listed) || new Set(listed).size !== listed.length) {
+                addIssue(issues, `${surfacePath}.hideableAreas`, "invalid-theme", "`hideableAreas` must be a list of distinct area keys");
+            }
+            else {
+                listed.forEach((key, position) => {
+                    if (typeof key !== "string" || !areaKeys.has(key)) {
+                        addIssue(issues, `${surfacePath}.hideableAreas[${position}]`, "invalid-theme", `${JSON.stringify(key)} is not an area this theme declares`);
+                    }
+                });
+            }
+        }
         if (surface.document !== undefined && !isRecord(surface.document)) {
             addIssue(issues, `${surfacePath}.document`, "invalid-document", "`document` must be a page document");
         }
@@ -603,12 +626,12 @@ function inspectBlockRules(theme, issues) {
     if (issues.length > 0)
         return;
     (theme.surfaces ?? []).forEach((surface, index) => {
-        if (surface.pageType !== "product")
+        if (surface.pageType !== "product" && surface.pageType !== "landing")
             return;
         const rules = surfaceRules(theme, surface.key);
         const guaranteed = (rules.required ?? []).reduce((count, entry) => count + (entry.min ?? 1) * guaranteedRole(theme, entry.type, "order-form"), 0);
         if (guaranteed === 0) {
-            addIssue(issues, `surfaces[${index}]`, "order-form-not-guaranteed", `product surface "${surface.key}" must always render an order form: require a section that places a component with role "order-form" through fixed or required blocks`);
+            addIssue(issues, `surfaces[${index}]`, "order-form-not-guaranteed", `${surface.pageType} surface "${surface.key}" must always render an order form: require a section that places a component with role "order-form" through fixed or required blocks`);
         }
     });
 }

package/dist/image-service.d.ts

@@ -1,23 +1,20 @@
 /**
  * An Astro image service for Wocart storefronts: every `<Image>` and
- * `getImage()` of a media-domain image is resized by Cloudflare Image Resizing
- * on the media domain itself (`https://<media>/cdn-cgi/image/…/<path>`).
+ * `getImage()` of a store image is resized by the store's own media delivery
+ * — ImageKit or Cloudflare — so a storefront on any host gets the same URLs
+ * and no second image bill. Any other image (another host, a file imported
+ * into the theme) is served as it is, and so is every image of a `direct`
+ * delivery, which does not resize.
  *
- * The media domain is always a Cloudflare zone, wherever the storefront runs,
- * so a storefront on Cloudflare and one on Vercel get the same URLs, the same
- * edge cache and no second image bill. Any other image — another host, a file
- * imported into the theme — is served as it is. Without a media domain (local
- * development, a store without one) every image passes through unchanged.
- *
- * The domain is read per call, not at build: one theme build serves every
- * store. Bind it once, in the theme, to wherever the store's media domain
- * lives:
+ * The delivery is the store config's `media`, read per image, not at build:
+ * one theme build serves every store. Bind it once, in the theme, to where
+ * the theme keeps the store's config:
  *
  * ```ts
  * // src/image-service.ts
- * import { MEDIA_DOMAIN } from "astro:env/server";
  * import { mediaImageService } from "@wocart/theme/image-service";
- * export default mediaImageService(() => MEDIA_DOMAIN);
+ * import { storeMedia } from "./store-media";
+ * export default mediaImageService(storeMedia);
  * ```
  *
  * ```js
@@ -27,13 +24,13 @@
  * ```
  */
 import type { ExternalImageService, ImageTransform } from "astro";
-import { type MediaImageParams } from "@wocart/storefront";
-/** The Cloudflare resizing options an Astro image transform asks for. */
+import { type MediaDelivery, type MediaImageParams } from "@wocart/storefront";
+/** The resizing options an Astro image transform asks for. */
 export declare function mediaImageParams(options: ImageTransform): MediaImageParams;
 /**
- * The image service, bound to the store's media domain.
+ * The image service, bound to the store's media delivery.
  *
- * @param mediaDomain - Read on every image (e.g. `() => MEDIA_DOMAIN`): the
- *   store's media domain, or `undefined` to pass every image through.
+ * @param delivery - Read on every image (e.g. `() => config.media`): the
+ *   store's `MediaDelivery`, or `null` / `undefined` to pass every image through.
  */
-export declare function mediaImageService(mediaDomain: () => string | undefined): ExternalImageService;
+export declare function mediaImageService(delivery: () => MediaDelivery | null | undefined | Promise<MediaDelivery | null | undefined>): ExternalImageService;

package/dist/image-service.js

@@ -1,23 +1,20 @@
 /**
  * An Astro image service for Wocart storefronts: every `<Image>` and
- * `getImage()` of a media-domain image is resized by Cloudflare Image Resizing
- * on the media domain itself (`https://<media>/cdn-cgi/image/…/<path>`).
+ * `getImage()` of a store image is resized by the store's own media delivery
+ * — ImageKit or Cloudflare — so a storefront on any host gets the same URLs
+ * and no second image bill. Any other image (another host, a file imported
+ * into the theme) is served as it is, and so is every image of a `direct`
+ * delivery, which does not resize.
  *
- * The media domain is always a Cloudflare zone, wherever the storefront runs,
- * so a storefront on Cloudflare and one on Vercel get the same URLs, the same
- * edge cache and no second image bill. Any other image — another host, a file
- * imported into the theme — is served as it is. Without a media domain (local
- * development, a store without one) every image passes through unchanged.
- *
- * The domain is read per call, not at build: one theme build serves every
- * store. Bind it once, in the theme, to wherever the store's media domain
- * lives:
+ * The delivery is the store config's `media`, read per image, not at build:
+ * one theme build serves every store. Bind it once, in the theme, to where
+ * the theme keeps the store's config:
  *
  * ```ts
  * // src/image-service.ts
- * import { MEDIA_DOMAIN } from "astro:env/server";
  * import { mediaImageService } from "@wocart/theme/image-service";
- * export default mediaImageService(() => MEDIA_DOMAIN);
+ * import { storeMedia } from "./store-media";
+ * export default mediaImageService(storeMedia);
  * ```
  *
  * ```js
@@ -28,8 +25,8 @@
  */
 import { baseService } from "astro/assets";
 import { mediaImageUrl } from "@wocart/storefront";
-/** Astro's `fit` (CSS object-fit) in Cloudflare's words; a value Cloudflare also knows passes as it is. */
-const CLOUDFLARE_FIT = {
+/** Astro's `fit` (CSS object-fit) in the words `mediaImageUrl` takes; a value it also knows passes as it is. */
+const FIT = {
     cover: "cover",
     contain: "contain",
     fill: "squeeze",
@@ -38,7 +35,7 @@ const CLOUDFLARE_FIT = {
     pad: "pad",
     squeeze: "squeeze",
 };
-/** The Cloudflare resizing options an Astro image transform asks for. */
+/** The resizing options an Astro image transform asks for. */
 export function mediaImageParams(options) {
     const params = {};
     if (options.width)
@@ -49,25 +46,25 @@ export function mediaImageParams(options) {
         params.format = options.format;
     if (typeof options.quality === "number")
         params.quality = options.quality;
-    const fit = options.fit ? CLOUDFLARE_FIT[options.fit] : undefined;
+    const fit = options.fit ? FIT[options.fit] : undefined;
     if (fit)
         params.fit = fit;
     return params;
 }
 /**
- * The image service, bound to the store's media domain.
+ * The image service, bound to the store's media delivery.
  *
- * @param mediaDomain - Read on every image (e.g. `() => MEDIA_DOMAIN`): the
- *   store's media domain, or `undefined` to pass every image through.
+ * @param delivery - Read on every image (e.g. `() => config.media`): the
+ *   store's `MediaDelivery`, or `null` / `undefined` to pass every image through.
  */
-export function mediaImageService(mediaDomain) {
+export function mediaImageService(delivery) {
     return {
         ...baseService,
-        getURL(options) {
+        async getURL(options) {
             const src = options.src;
             if (typeof src !== "string")
                 return src.src;
-            return mediaImageUrl(src, mediaImageParams(options), mediaDomain()) ?? src;
+            return mediaImageUrl(src, mediaImageParams(options), await delivery()) ?? src;
         },
     };
 }

package/dist/index.d.ts

@@ -17,12 +17,12 @@ export { resolveInstance, createInstance, checkStoredValue as checkFieldValue }
 export type { CheckedValue as FieldValueCheck } from "./instances.js";
 export { RICH_TEXT_FORMATS, richTextToHtml, richTextToPlainText } from "./rich-text.js";
 export { instantiatePreset, isInsertableOn } from "./composition.js";
-export { COMPONENT_PLACEMENTS, COMPONENT_ROLES, THEME_LIMITS, areaSurface, fixedBlockId } from "./blocks.js";
+export { COMPONENT_PLACEMENTS, COMPONENT_ROLES, LANDING_TEMPLATE, THEME_LIMITS, areaSurface, fixedBlockId, hideableAreas, isAreaShown, landingSurface, templateSurface, } from "./blocks.js";
 export { completePage, resolveSurfaceDocument } from "./surface-document.js";
 export { CONDITION_DEPTH, isFieldVisible } from "./conditions.js";
 export { COLOR_ROLES, COLOR_SCHEMES_MAX, STYLE_BREAKPOINTS, STYLE_PANELS, STYLE_STEPS, STYLE_WIDTHS, THEME_STYLES_PATH, SCHEME_MARKER_CLASS, colorSchemeCss, contrastRatio, schemeClass, styleClasses, themeStyleSheet, } from "./style.js";
 export type { SurfaceDocument, SurfaceDocumentReason } from "./surface-document.js";
-export { checkPageData, duplicateInstance, findInstance, insertInstance, moveInstance, newInstanceId, removeInstance, setInstanceHidden, setInstanceProps, } from "./operations.js";
+export { checkPageData, duplicateInstance, findInstance, insertInstance, moveInstance, newInstanceId, removeInstance, setAreaHidden, setInstanceHidden, setInstanceProps, } from "./operations.js";
 export type { DocumentEdit, DocumentIssue, DocumentIssueCode, InstanceLocation, InstancePlacement, } from "./operations.js";
 export { THEME_SDK_VERSION } from "./version.js";
 export type { RichTextHtmlOptions } from "./rich-text.js";

package/dist/index.js

@@ -16,11 +16,11 @@ export { parsePageData, validatePageData } from "./page-data.js";
 export { resolveInstance, createInstance, checkStoredValue as checkFieldValue } from "./instances.js";
 export { RICH_TEXT_FORMATS, richTextToHtml, richTextToPlainText } from "./rich-text.js";
 export { instantiatePreset, isInsertableOn } from "./composition.js";
-export { COMPONENT_PLACEMENTS, COMPONENT_ROLES, THEME_LIMITS, areaSurface, fixedBlockId } from "./blocks.js";
+export { COMPONENT_PLACEMENTS, COMPONENT_ROLES, LANDING_TEMPLATE, THEME_LIMITS, areaSurface, fixedBlockId, hideableAreas, isAreaShown, landingSurface, templateSurface, } from "./blocks.js";
 export { completePage, resolveSurfaceDocument } from "./surface-document.js";
 export { CONDITION_DEPTH, isFieldVisible } from "./conditions.js";
 export { COLOR_ROLES, COLOR_SCHEMES_MAX, STYLE_BREAKPOINTS, STYLE_PANELS, STYLE_STEPS, STYLE_WIDTHS, THEME_STYLES_PATH, SCHEME_MARKER_CLASS, colorSchemeCss, contrastRatio, schemeClass, styleClasses, themeStyleSheet, } from "./style.js";
-export { checkPageData, duplicateInstance, findInstance, insertInstance, moveInstance, newInstanceId, removeInstance, setInstanceHidden, setInstanceProps, } from "./operations.js";
+export { checkPageData, duplicateInstance, findInstance, insertInstance, moveInstance, newInstanceId, removeInstance, setAreaHidden, setInstanceHidden, setInstanceProps, } from "./operations.js";
 export { THEME_SDK_VERSION } from "./version.js";
 export { resolveThemeSettings, checkThemeSettings } from "./settings.js";
 export { localize } from "./locales.js";

package/dist/manifest.d.ts

@@ -21,8 +21,8 @@ export declare const THEME_MANIFEST_PATH = "/wocart-theme.json";
 /** Derive the data-only manifest from a theme. `component` and `load` are dropped. */
 export declare function themeManifest(theme: ThemeDefinition): ThemeManifest;
 /**
- * The manifest's structural shape. Unknown keys are stripped (the forward-compat
- * tradeoff documented in the README); absent `fields`/`slots` normalize to `[]`.
+ * The manifest's structural shape. Unknown keys are stripped, so a manifest
+ * from a newer theme still reads; absent `fields`/`slots` normalize to `[]`.
  * Rules that span fields are not here — `validateThemeManifest` applies them.
  */
 export declare const ThemeManifestSchema: z.ZodObject<{
@@ -41,6 +41,7 @@ export declare const ThemeManifestSchema: z.ZodObject<{
             max: z.ZodExactOptional<z.ZodNumber>;
         }, z.core.$strip>>>;
         max: z.ZodExactOptional<z.ZodNumber>;
+        hideableAreas: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>>;
     areas: z.ZodDefault<z.ZodArray<z.ZodObject<{
         key: z.ZodString;

package/dist/manifest.js

@@ -37,6 +37,7 @@ export function themeManifest(theme) {
             ...(surface.document === undefined ? {} : { document: copyData(surface.document) }),
             ...(surface.required === undefined ? {} : { required: copyData(surface.required) }),
             ...(surface.max === undefined ? {} : { max: surface.max }),
+            ...(surface.hideableAreas === undefined ? {} : { hideableAreas: [...surface.hideableAreas] }),
         })),
         areas: (theme.areas ?? []).map((area) => copyData(area)),
         locales: [...(theme.locales ?? [])],
@@ -214,8 +215,8 @@ const ComponentSpecSchema = z.object({
         .default([]),
 });
 /**
- * The manifest's structural shape. Unknown keys are stripped (the forward-compat
- * tradeoff documented in the README); absent `fields`/`slots` normalize to `[]`.
+ * The manifest's structural shape. Unknown keys are stripped, so a manifest
+ * from a newer theme still reads; absent `fields`/`slots` normalize to `[]`.
  * Rules that span fields are not here — `validateThemeManifest` applies them.
  */
 export const ThemeManifestSchema = z.object({
@@ -232,6 +233,7 @@ export const ThemeManifestSchema = z.object({
         document: z.exactOptional(z.custom((value) => isRecord(value))),
         required: z.exactOptional(z.array(RequiredBlockSchema)),
         max: z.exactOptional(z.number()),
+        hideableAreas: z.exactOptional(z.array(z.string())),
     }))
         .default([]),
     areas: z

package/dist/operations.d.ts

@@ -87,6 +87,11 @@ export declare function setInstanceProps(theme: ThemeDefinition, page: PageData,
 export declare function setInstanceHidden(theme: ThemeDefinition, page: PageData, id: string, hidden: boolean): DocumentEdit;
 /** @deprecated Pass the theme first, so required blocks stay shown. */
 export declare function setInstanceHidden(page: PageData, id: string, hidden: boolean): DocumentEdit;
+/**
+ * Show or leave out one of the theme's areas on this page — the header, the
+ * footer — when its surface lets a page leave it out (`hideableAreas`).
+ */
+export declare function setAreaHidden(theme: ThemeDefinition, page: PageData, key: string, hidden: boolean): DocumentEdit;
 /**
  * Everything a writer must fix before saving a document for this theme —
  * the strict counterpart of `validatePageData`: an envelope for one of the

package/dist/operations.js

@@ -14,7 +14,7 @@
  * nesting stay within their caps. Operations on a document assume it was
  * completed (`completePage`) when it was opened.
  */
-import { THEME_LIMITS, composesSurface, placementAllows, slotCap, surfaceRules } from "./blocks.js";
+import { THEME_LIMITS, composesSurface, hideableAreas, placementAllows, slotCap, surfaceRules } from "./blocks.js";
 import { surfaceCovers } from "./composition.js";
 import { checkStoredValue, hasFallback, ownValue } from "./instances.js";
 import { ComponentInstanceSchema } from "./schemas.js";
@@ -518,6 +518,24 @@ export function setInstanceHidden(...args) {
         delete location.instance.hidden;
     return { ok: true, page: next };
 }
+/**
+ * Show or leave out one of the theme's areas on this page — the header, the
+ * footer — when its surface lets a page leave it out (`hideableAreas`).
+ */
+export function setAreaHidden(theme, page, key, hidden) {
+    if (!hideableAreas(theme, page.surface).includes(key)) {
+        return refuse("not-allowed", `a page of "${page.surface}" cannot leave out the area "${key}"`);
+    }
+    const next = structuredClone(page);
+    const rest = (next.hiddenAreas ?? []).filter((candidate) => candidate !== key);
+    const order = (theme.areas ?? []).map((area) => area.key);
+    const hiddenAreas = hidden ? [...rest, key].sort((a, b) => order.indexOf(a) - order.indexOf(b)) : rest;
+    if (hiddenAreas.length > 0)
+        next.hiddenAreas = hiddenAreas;
+    else
+        delete next.hiddenAreas;
+    return { ok: true, page: next };
+}
 /**
  * Everything a writer must fix before saving a document for this theme —
  * the strict counterpart of `validatePageData`: an envelope for one of the
@@ -538,6 +556,13 @@ export function checkPageData(theme, input) {
     if (input.theme !== undefined && !(isRecord(input.theme) && input.theme.key === theme.key && typeof input.theme.version === "string" && input.theme.version.length > 0)) {
         issues.push({ path: "theme", code: "invalid-document", message: `\`theme\` must name this theme: { key: "${theme.key}", version }` });
     }
+    if (input.hiddenAreas !== undefined) {
+        const hideable = hideableAreas(theme, surface);
+        const hidden = input.hiddenAreas;
+        if (!Array.isArray(hidden) || new Set(hidden).size !== hidden.length || !hidden.every((key) => typeof key === "string" && hideable.includes(key))) {
+            issues.push({ path: "hiddenAreas", code: "invalid-document", message: `\`hiddenAreas\` lists distinct areas this page may leave out: ${hideable.length > 0 ? hideable.join(", ") : "none"}` });
+        }
+    }
     const rules = surfaceRules(theme, surface);
     const cap = slotCap(rules, THEME_LIMITS.sections);
     if (input.sections.length > cap) {

package/dist/page-data.js

@@ -7,10 +7,12 @@
  * failed; a structurally invalid section is dropped with an issue; the
  * document itself is not rewritten by `validatePageData`.
  */
-import { THEME_LIMITS, completeRequired, slotCap, surfaceRules } from "./blocks.js";
+import { THEME_LIMITS, completeRequired, hideableAreas, slotCap, surfaceRules } from "./blocks.js";
 import { resolveInstance } from "./instances.js";
-import { ComponentInstanceSchema, SURFACE_KEY_PATTERN, THEME_KEY_PATTERN } from "./schemas.js";
+import { ComponentInstanceSchema, SURFACE_KEY_PATTERN, THEME_KEY_PATTERN, TYPE_KEY_PATTERN } from "./schemas.js";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** At most this many areas a document leaves out: a theme declares a handful. */
+const MAX_HIDDEN_AREAS = 8;
 const envelopeFailure = (message) => ({
     page: null,
     issues: [{ path: "", code: "envelope-invalid", message }],
@@ -53,12 +55,25 @@ export function parsePageData(input) {
     // name a prototype.
     const page = { version: 1, surface, sections };
     for (const key of Object.keys(input)) {
-        if (key === "version" || key === "surface" || key === "sections" || key === "theme")
+        if (key === "version" || key === "surface" || key === "sections" || key === "theme" || key === "hiddenAreas")
             continue;
         if (key === "__proto__")
             continue;
         page[key] = input[key];
     }
+    if (input.hiddenAreas !== undefined) {
+        const hidden = input.hiddenAreas;
+        if (Array.isArray(hidden) && hidden.length <= MAX_HIDDEN_AREAS && hidden.every((key) => typeof key === "string" && TYPE_KEY_PATTERN.test(key)) && new Set(hidden).size === hidden.length) {
+            page.hiddenAreas = [...hidden];
+        }
+        else {
+            issues.push({
+                path: "hiddenAreas",
+                code: "invalid-prop",
+                message: `\`hiddenAreas\` must list at most ${MAX_HIDDEN_AREAS} distinct area keys; ignored, every area shows`,
+            });
+        }
+    }
     if (input.theme !== undefined) {
         const theme = input.theme;
         if (isRecord(theme) &&
@@ -124,6 +139,12 @@ export function validatePageData(theme, input, scope = {}) {
             walk(block, `${path}.fixed.${name}`);
         }
     };
+    const hideable = hideableAreas(theme, parsed.page.surface);
+    (parsed.page.hiddenAreas ?? []).forEach((key, index) => {
+        if (!hideable.includes(key)) {
+            issues.push({ path: `hiddenAreas[${index}]`, code: "invalid-prop", message: `"${key}" is not an area this page may leave out; it shows` });
+        }
+    });
     const spec = surfaceRules(theme, parsed.page.surface);
     const cap = slotCap(spec, THEME_LIMITS.sections);
     if (parsed.page.sections.length > cap) {

package/dist/preview-target.d.ts

@@ -29,6 +29,9 @@ export interface PreviewTarget {
  *   when the theme composes that page, else on the home page.
  * - The resource is chosen by the surface's `pageType`, never its key, so an
  *   alternate (`product.compact`) previews like its base.
+ * - A landing page's own document (`lp:<id>`) previews with the theme's
+ *   `landing` surface on the page its `path` names (`/lp/<slug>`), and the
+ *   target keeps its own surface, so the sections render that page's document.
  *
  * ```astro
  * ---

package/dist/preview-target.js

@@ -4,7 +4,7 @@
  * document it renders.
  */
 import { DEFAULT_COLLECTION_HANDLES, matchStorefrontPath } from "@wocart/storefront";
-import { areaSurface } from "./blocks.js";
+import { areaSurface, templateSurface } from "./blocks.js";
 /** The surface a page type is shown with: the one keyed by the type itself, else the first declaring it. */
 function surfaceFor(surfaces, pageType) {
     return surfaces.find((surface) => surface.key === pageType) ?? surfaces.find((surface) => surface.pageType === pageType);
@@ -45,6 +45,9 @@ async function resourceParams(pageType, named, client) {
  *   when the theme composes that page, else on the home page.
  * - The resource is chosen by the surface's `pageType`, never its key, so an
  *   alternate (`product.compact`) previews like its base.
+ * - A landing page's own document (`lp:<id>`) previews with the theme's
+ *   `landing` surface on the page its `path` names (`/lp/<slug>`), and the
+ *   target keeps its own surface, so the sections render that page's document.
  *
  * ```astro
  * ---
@@ -58,14 +61,16 @@ export async function previewTarget(theme, draft, client) {
     const surfaces = theme.surfaces ?? [];
     const match = draft.path ? matchStorefrontPath(draft.path) : null;
     const area = (theme.areas ?? []).some((candidate) => areaSurface(candidate.key) === draft.surface) ? draft.surface : null;
-    const shown = area === null ? surfaces.find((surface) => surface.key === draft.surface) : (match ? surfaceFor(surfaces, match.type) : undefined) ?? surfaceFor(surfaces, "home");
+    const template = templateSurface(draft.surface);
+    const shown = area === null ? surfaces.find((surface) => surface.key === template) : (match ? surfaceFor(surfaces, match.type) : undefined) ?? surfaceFor(surfaces, "home");
     if (shown === undefined)
         return null;
+    const surface = area === null ? draft.surface : shown.key;
     const pageType = shown.pageType;
     const named = match !== null && match.type === pageType ? { ...match.params } : {};
     const [params, document] = await Promise.all([
         resourceParams(pageType, named, client),
-        area === null && draft.document !== undefined ? draft.document : client.pageData.get(shown.key),
+        area === null && draft.document !== undefined ? draft.document : client.pageData.get(surface),
     ]);
-    return { surface: shown.key, pageType, area, params, document };
+    return { surface, pageType, area, params, document };
 }

package/dist/types.d.ts

@@ -728,6 +728,13 @@ export interface SurfaceSpec {
     required?: readonly RequiredBlock[];
     /** At most this many top-level sections (1–50). Absent: `THEME_LIMITS.sections`. */
     max?: number;
+    /**
+     * The theme's areas a page of this surface may leave out (`["header",
+     * "footer"]`): its document lists the ones it hides in `hiddenAreas`. A
+     * landing page that sends an ad's visitor straight to its order form is
+     * the case. Absent: every page shows every area.
+     */
+    hideableAreas?: readonly string[];
 }
 /**
  * A part every page shares — a header, a footer — composed of sections like a
@@ -868,6 +875,11 @@ export interface PageData {
     version: 1;
     surface: string;
     sections: ComponentInstance[];
+    /**
+     * The keys of the theme's areas this page leaves out. Only the areas its
+     * surface lists in `hideableAreas` are left out; read it with `isAreaShown`.
+     */
+    hiddenAreas?: string[];
     /**
      * The theme and theme version that wrote the document. A document that
      * names another theme is reported (`theme-mismatch`): its sections were

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * reads. Always equal to `package.json`'s version; the package check refuses
  * a release where they differ.
  */
-export declare const THEME_SDK_VERSION = "2.3.0";
+export declare const THEME_SDK_VERSION = "3.1.0";

package/dist/version.js

@@ -4,4 +4,4 @@
  * reads. Always equal to `package.json`'s version; the package check refuses
  * a release where they differ.
  */
-export const THEME_SDK_VERSION = "2.3.0";
+export const THEME_SDK_VERSION = "3.1.0";