@wocart/theme 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -5,6 +5,52 @@ All notable changes to `@wocart/theme` are recorded here. The package follows
 major version, and an export is marked `@deprecated` for at least one minor
 release before a major removes it.
 
+## 4.0.0 — 2026-11-01
+
+Search and contact are platform pages a theme composes, and the theme
+operations take the theme they check. Requires `@wocart/storefront` 3.0.0.
+
+### Added
+
+- `SurfacePageType` and `PAGE_TYPES` take `search` (`/search`) and `contact`
+  (`/contact`), the storefront's new page types: a theme declares a surface
+  for each, so a merchant composes them like any page.
+
+### Removed
+
+- `removeInstance(page, id)` and `setInstanceHidden(page, id, hidden)`, the
+  forms without the theme: pass the theme first, so a required block is
+  always kept and shown.
+
+### Changed (breaking)
+
+- The peer `@wocart/storefront` is `^3.0.0`.
+
+## 3.1.0 — 2026-10-31
+
+Landing pages are composed pages, each with its own document, and a page can
+leave out the header or the footer.
+
+### Added
+
+- `landingSurface(id)`: a landing page's own document is stored as
+  `lp:<id>`. `templateSurface(surface)` names the surface it follows: the
+  theme's `landing` surface gives every landing page its rules, its sections
+  and its starting document. `resolveSurfaceDocument`, `checkPageData`, the
+  document operations, `isInsertableOn` and `previewTarget` read an `lp:`
+  document by it; `LANDING_TEMPLATE` is its key.
+- `SurfaceSpec.hideableAreas`: the areas a page of that surface may leave
+  out. `PageData.hiddenAreas` lists the ones it does; read it with
+  `isAreaShown(theme, page, key)`, change it with `setAreaHidden`, and list
+  the choices with `hideableAreas(theme, surface)`. The manifest carries it.
+
+### Changed
+
+- A theme's `landing` surface renders the `landing` page type, a landing
+  page type is composed only by the `landing` surface, and, like a product
+  surface, it must always render an order form. A surface key cannot start
+  with `lp:` or `area:`.
+
 ## 3.0.0 — 2026-10-30
 
 A store's images can live on any media host: the image service takes the

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/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

@@ -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 ?? [])],
@@ -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

@@ -51,14 +51,10 @@ export declare function findInstance(page: PageData, id: string): InstanceLocati
  */
 export declare function insertInstance(theme: ThemeDefinition, page: PageData, instance: ComponentInstance, placement?: InstancePlacement): DocumentEdit;
 /**
- * Remove an instance and everything inside it. Refused for a fixed block and,
- * given the theme, for the last required instance of its type in its list.
- * The form without a theme is kept for writers that predate blocks: it still
- * refuses a fixed block, but cannot know a slot's required types.
+ * Remove an instance and everything inside it. Refused for a fixed block and
+ * for the last required instance of its type in its list.
  */
 export declare function removeInstance(theme: ThemeDefinition, page: PageData, id: string): DocumentEdit;
-/** @deprecated Pass the theme first, so required blocks are kept. */
-export declare function removeInstance(page: PageData, id: string): DocumentEdit;
 /**
  * Move an instance (with everything inside it) to a placement. `index` counts
  * positions in the destination after the instance has left its old place.
@@ -81,12 +77,14 @@ export declare function duplicateInstance(theme: ThemeDefinition, page: PageData
 export declare function setInstanceProps(theme: ThemeDefinition, page: PageData, id: string, changes: Readonly<Record<string, JsonValue | undefined>>): DocumentEdit;
 /**
  * Switch an instance off (kept, not rendered) or back on. A fixed block is
- * never hidden and, given the theme, neither is the last required instance of
- * its type. The form without a theme refuses only a fixed block.
+ * never hidden, and neither is the last required instance of its type.
  */
 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";
@@ -29,7 +29,6 @@ export function newInstanceId() {
     return `cmp_${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
 }
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const isTheme = (value) => isRecord(value) && isRecord(value.components);
 const definitionOf = (theme, type) => Object.hasOwn(theme.components, type) ? theme.components[type] : undefined;
 const refuse = (code, message, path = "") => ({
     ok: false,
@@ -347,8 +346,11 @@ export function insertInstance(theme, page, instance, placement = {}) {
     list.splice(placement.index ?? list.length, 0, tree);
     return { ok: true, page: next };
 }
-export function removeInstance(...args) {
-    const [theme, page, id] = isTheme(args[0]) ? args : [null, args[0], args[1]];
+/**
+ * Remove an instance and everything inside it. Refused for a fixed block and
+ * for the last required instance of its type in its list.
+ */
+export function removeInstance(theme, page, id) {
     const next = structuredClone(page);
     const location = findInstance(next, id);
     if (location === null)
@@ -360,11 +362,9 @@ export function removeInstance(...args) {
         : targetList(next, { parent: location.parent, slot: location.slot ?? "default" });
     if (list === null)
         return refuse("unknown-instance", `no instance "${location.parent}" in the document`);
-    if (theme !== null) {
-        const short = leavesRequiredShort(listRules(theme, next, location.parent, location.slot), list, location.instance);
-        if (short !== null)
-            return refuse("required-block", `"${location.instance.type}" is required here (at least ${short.min ?? 1})`);
-    }
+    const short = leavesRequiredShort(listRules(theme, next, location.parent, location.slot), list, location.instance);
+    if (short !== null)
+        return refuse("required-block", `"${location.instance.type}" is required here (at least ${short.min ?? 1})`);
     list.splice(list.findIndex((candidate) => candidate.id === id), 1);
     return { ok: true, page: next };
 }
@@ -496,17 +496,18 @@ export function setInstanceProps(theme, page, id, changes) {
         delete instance.props;
     return { ok: true, page: next };
 }
-export function setInstanceHidden(...args) {
-    const [theme, page, id, hidden] = isTheme(args[0])
-        ? args
-        : [null, args[0], args[1], args[2]];
+/**
+ * Switch an instance off (kept, not rendered) or back on. A fixed block is
+ * never hidden, and neither is the last required instance of its type.
+ */
+export function setInstanceHidden(theme, page, id, hidden) {
     const next = structuredClone(page);
     const location = findInstance(next, id);
     if (location === null)
         return refuse("unknown-instance", `no instance "${id}" in the document`);
     if (hidden && location.fixed !== undefined)
         return refuse("fixed-block", `"${id}" is placed by its component's code and cannot be hidden`);
-    if (hidden && theme !== null) {
+    if (hidden) {
         const list = location.parent === null ? next.sections : (slotLists(findInstance(next, location.parent).instance).find(([name]) => name === (location.slot ?? "default"))?.[1] ?? []);
         const short = leavesRequiredShort(listRules(theme, next, location.parent, location.slot), list, location.instance);
         if (short !== null)
@@ -518,6 +519,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 +557,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/patterns.d.ts

@@ -17,7 +17,7 @@ export declare const TYPE_KEY_PATTERN: RegExp;
  */
 export declare const SURFACE_KEY_PATTERN: RegExp;
 /** The platform page types a surface can render (`SurfacePageType`), mirrored from the storefront's page types. */
-export declare const PAGE_TYPES: readonly ["home", "catalog", "category", "collection", "product", "page", "landing", "checkout", "thankYou", "trackOrder"];
+export declare const PAGE_TYPES: readonly ["home", "catalog", "category", "collection", "product", "page", "landing", "checkout", "thankYou", "trackOrder", "search", "contact"];
 /** A `color` field's value: a hex color, `#rgb` or `#rrggbb`. */
 export declare const COLOR_PATTERN: RegExp;
 /**

package/dist/patterns.js

@@ -28,6 +28,8 @@ export const PAGE_TYPES = [
     "checkout",
     "thankYou",
     "trackOrder",
+    "search",
+    "contact",
 ];
 /** A `color` field's value: a hex color, `#rgb` or `#rrggbb`. */
 export const COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;

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
@@ -749,7 +756,7 @@ export interface AreaSpec {
  * The storefront's page types — what a URL means, with the paths the platform
  * owns. The same names as `StorefrontPageType` in `@wocart/storefront`.
  */
-export type SurfacePageType = "home" | "catalog" | "category" | "collection" | "product" | "page" | "landing" | "checkout" | "thankYou" | "trackOrder";
+export type SurfacePageType = "home" | "catalog" | "category" | "collection" | "product" | "page" | "landing" | "checkout" | "thankYou" | "trackOrder" | "search" | "contact";
 /**
  * One component as data: a `ComponentDefinition` minus its runtime-only
  * implementation. `component` (the live component reference) and `load` (the
@@ -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 = "3.0.0";
+export declare const THEME_SDK_VERSION = "4.0.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 = "3.0.0";
+export const THEME_SDK_VERSION = "4.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/theme",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "The Wocart theme contract: code-owned component definitions, JSON page documents, validation and resolution, and a reference Astro renderer.",
   "keywords": [
     "wocart",
@@ -82,7 +82,7 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@wocart/storefront": "^2.0.0",
+    "@wocart/storefront": "^3.0.0",
     "astro": "^7.0.0"
   },
   "peerDependenciesMeta": {
@@ -92,7 +92,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
-    "@wocart/storefront": "^2.0.0",
+    "@wocart/storefront": "^3.0.0",
     "astro": "^7.3.2",
     "fast-check": "^4.6.0",
     "happy-dom": "^20.11.6",