@v-office/website-headless 0.0.1

package/dist/manifest/index.d.mts

@@ -0,0 +1,118 @@
+//#region src/manifest/surfaces.d.ts
+/**
+ * The FIVE platform UI surfaces — each a component that carries real logic —
+ * and the two deterministic signals that tell how a site consumes each one:
+ *
+ *   - `component`: the named export of @v-office/website-components. A site
+ *     that imports it renders the surface as IMPORTED (updates are pin bumps).
+ *   - `hooks`: named exports of @v-office/website-headless that only a UI for
+ *     this surface would import. A site that imports one of them WITHOUT
+ *     importing the component has rendered its own UI — the surface is CUSTOM
+ *     (behavior arrives by pin bump; a new capability is offered, never forced).
+ *   - `bindings`: framework bindings of that behavior exported by
+ *     @v-office/website-components next to the component (e.g. the React hook
+ *     over the flow). Importing one without the component is CUSTOM as well.
+ *
+ * Surfaces with no hooks yet (the search trio) can only be detected as imported
+ * or absent. That is fine: a custom surface without a headless hook never
+ * receives a platform-initiated change, so the distinction has no consumer.
+ * The moment headless gains behavior for one (e.g. a search hook), its name is
+ * added here in the same release and every adopting site reports `custom`.
+ *
+ * Everything else a site renders (rental detail, FAQ, consent, brand pages) is
+ * the site's own markup and is not a platform surface. Decided 2026-09-03.
+ */
+declare const PLATFORM_SURFACES: {
+  /** Entry to search: dates + guests → the search page. */
+  readonly searchBar: {
+    readonly component: "SearchBar";
+    readonly hooks: readonly [];
+    readonly bindings: readonly [];
+  };
+  /** Curated rentals on brand pages, driven by the search logic. */
+  readonly showcase: {
+    readonly component: "Showcase";
+    readonly hooks: readonly [];
+    readonly bindings: readonly [];
+  };
+  /** The search page's results, including the map. */
+  readonly searchResults: {
+    readonly component: "SearchResults";
+    readonly hooks: readonly [];
+    readonly bindings: readonly [];
+  };
+  /** Calendar + price quote + cancellation-policy choice on the rental page; entry to the booking flow. */
+  readonly quote: {
+    readonly component: "Quote";
+    readonly hooks: readonly ["fetchQuote", "pricePolicyBranches", "policyFreeCancellationUntil"];
+    readonly bindings: readonly [];
+  };
+  /** The booking flow (checkout): stay → quote → selections → § 7 gate → book → pay. Its data-part vocabulary is `checkout-*`. */
+  readonly booking: {
+    readonly component: "Booking";
+    readonly hooks: readonly ["createCheckoutFlow"];
+    readonly bindings: readonly ["useCheckoutFlow"];
+  };
+};
+type PlatformSurface = keyof typeof PLATFORM_SURFACES;
+//#endregion
+//#region src/manifest/index.d.ts
+type ComponentState = "imported" | "custom";
+interface SiteManifest {
+  manifestVersion: 3;
+  builtAt: string;
+  /** Installed versions of the tracked packages. */
+  packages: Record<string, string>;
+  /** Per platform surface the site renders: imported from the package, or the site's own UI over the hook. */
+  components: Record<string, ComponentState>;
+}
+interface ImportSets {
+  components: Set<string>;
+  headless: Set<string>;
+}
+/** Add every platform import found in `code` to `into`. Shared by the source scan and the bundler plugin. */
+declare function collectImportsFromCode(code: string, into: ImportSets): void;
+declare const emptyImports: () => ImportSets;
+/** Signal 1: what the source under src/ contains. */
+declare function collectImports(root: string): ImportSets;
+declare function deriveComponentStates(imports: ImportSets): Record<string, ComponentState>;
+/** Which marked surfaces the built output ships. */
+declare function renderedSurfaces(distDir: string): Set<string>;
+interface CrossCheck {
+  /** The manifest's states: derived from what the bundler reached. */
+  states: Record<string, ComponentState>;
+  warnings: string[];
+  /** Non-empty = the build must fail. */
+  errors: string[];
+}
+declare function crossCheck(source: ImportSets, bundled: ImportSets | null, rendered: Set<string>): CrossCheck;
+/** Everything without the bundler signal — used by tests and by anything that runs outside a build. */
+declare function buildSiteManifest(root: string): SiteManifest;
+/**
+ * The Astro integration:
+ *
+ *   import { siteManifest } from "@v-office/website-headless/manifest";
+ *   integrations: [react(), siteManifest()]
+ *
+ * Typed structurally so this package needs no astro or vite dependency.
+ */
+declare function siteManifest(): {
+  name: string;
+  hooks: {
+    "astro:config:setup": (ctx: {
+      config: {
+        root: URL;
+      };
+      updateConfig: (cfg: {
+        vite: {
+          plugins: unknown[];
+        };
+      }) => void;
+    }) => void;
+    "astro:build:done": (ctx: {
+      dir: URL;
+    }) => void;
+  };
+};
+//#endregion
+export { ComponentState, CrossCheck, ImportSets, PLATFORM_SURFACES, type PlatformSurface, SiteManifest, buildSiteManifest, collectImports, collectImportsFromCode, crossCheck, deriveComponentStates, emptyImports, renderedSurfaces, siteManifest };

package/dist/manifest/index.mjs

@@ -0,0 +1,264 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/manifest/surfaces.ts
+/**
+* The FIVE platform UI surfaces — each a component that carries real logic —
+* and the two deterministic signals that tell how a site consumes each one:
+*
+*   - `component`: the named export of @v-office/website-components. A site
+*     that imports it renders the surface as IMPORTED (updates are pin bumps).
+*   - `hooks`: named exports of @v-office/website-headless that only a UI for
+*     this surface would import. A site that imports one of them WITHOUT
+*     importing the component has rendered its own UI — the surface is CUSTOM
+*     (behavior arrives by pin bump; a new capability is offered, never forced).
+*   - `bindings`: framework bindings of that behavior exported by
+*     @v-office/website-components next to the component (e.g. the React hook
+*     over the flow). Importing one without the component is CUSTOM as well.
+*
+* Surfaces with no hooks yet (the search trio) can only be detected as imported
+* or absent. That is fine: a custom surface without a headless hook never
+* receives a platform-initiated change, so the distinction has no consumer.
+* The moment headless gains behavior for one (e.g. a search hook), its name is
+* added here in the same release and every adopting site reports `custom`.
+*
+* Everything else a site renders (rental detail, FAQ, consent, brand pages) is
+* the site's own markup and is not a platform surface. Decided 2026-09-03.
+*/
+const PLATFORM_SURFACES = {
+	/** Entry to search: dates + guests → the search page. */
+	searchBar: {
+		component: "SearchBar",
+		hooks: [],
+		bindings: []
+	},
+	/** Curated rentals on brand pages, driven by the search logic. */
+	showcase: {
+		component: "Showcase",
+		hooks: [],
+		bindings: []
+	},
+	/** The search page's results, including the map. */
+	searchResults: {
+		component: "SearchResults",
+		hooks: [],
+		bindings: []
+	},
+	/** Calendar + price quote + cancellation-policy choice on the rental page; entry to the booking flow. */
+	quote: {
+		component: "Quote",
+		hooks: [
+			"fetchQuote",
+			"pricePolicyBranches",
+			"policyFreeCancellationUntil"
+		],
+		bindings: []
+	},
+	/** The booking flow (checkout): stay → quote → selections → § 7 gate → book → pay. Its data-part vocabulary is `checkout-*`. */
+	booking: {
+		component: "Booking",
+		hooks: ["createCheckoutFlow"],
+		bindings: ["useCheckoutFlow"]
+	}
+};
+//#endregion
+//#region src/manifest/index.ts
+/**
+* The site manifest — the machine-readable answer to "what IS this site",
+* written by every build as `dist/site-manifest.json` and reported by the
+* build worker to the controller with the build's finalize call (process/05).
+*
+* EVERYTHING IN IT IS DERIVED, nothing is declared: package versions come
+* from the installed packages, component states from the site's imports (see
+* ./surfaces.ts). An AI never writes the manifest, so it cannot be wrong in
+* the ways a declaration can.
+*
+* THREE INDEPENDENT SIGNALS, cross-checked on every build:
+*   1. a text scan of the imports under src/         — what the code contains
+*   2. the imports the bundler actually resolved      — what the build reaches
+*      (a Vite plugin the integration registers; dead files never enter it,
+*      re-exports are followed)
+*   3. the `data-part` markers in the built output     — what a guest gets
+*      (HTML and client chunks; the booking flow is an island)
+* The manifest states what the build reached (2). Disagreements with (1) are
+* printed. A booking flow rendered without the platform's booking behavior
+* (3 without 2) FAILS the build: behavior is never forked per site.
+*
+* This module is an ASTRO INTEGRATION and uses node:fs — it is exported ONLY
+* through the "./manifest" subpath so client bundles never touch it.
+*/
+const TRACKED_PACKAGES = [
+	"@v-office/website-sdk",
+	"@v-office/website-headless",
+	"@v-office/website-components",
+	"astro",
+	"react",
+	"tailwindcss"
+];
+const COMPONENTS_PACKAGE = "@v-office/website-components";
+const HEADLESS_PACKAGE = "@v-office/website-headless";
+const SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".mjs",
+	".astro"
+]);
+function installedVersion(root, name) {
+	const file = path.join(root, "node_modules", ...name.split("/"), "package.json");
+	if (!fs.existsSync(file)) return void 0;
+	return JSON.parse(fs.readFileSync(file, "utf8")).version;
+}
+function* filesUnder(dir, extensions) {
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (entry.name !== "node_modules") yield* filesUnder(full, extensions);
+		} else if (extensions.has(path.extname(entry.name))) yield full;
+	}
+}
+/** `import { a, b as c } from "pkg"` and `export { a } from "pkg"` (a local barrel) →
+*  named imports per package. Type-only forms render nothing and are skipped.
+*  Namespace imports carry no names and are not detected — the cross-check reports
+*  them as a source/bundler disagreement. */
+const IMPORT_RE = /(?:import|export)\s+(type\s+)?(?:[\w$]+\s*,\s*)?\{([^}]*)\}\s*from\s*["']([^"']+)["']/g;
+const packageOf = (specifier) => specifier === COMPONENTS_PACKAGE || specifier.startsWith(`${COMPONENTS_PACKAGE}/`) ? "components" : specifier === HEADLESS_PACKAGE || specifier.startsWith(`${HEADLESS_PACKAGE}/`) ? "headless" : null;
+/** Add every platform import found in `code` to `into`. Shared by the source scan and the bundler plugin. */
+function collectImportsFromCode(code, into) {
+	for (const m of code.matchAll(IMPORT_RE)) {
+		const [, typeOnly, names, specifier] = m;
+		if (typeOnly) continue;
+		const target = packageOf(specifier);
+		if (!target) continue;
+		for (const part of names.split(",")) {
+			const name = part.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0].trim();
+			if (name) into[target].add(name);
+		}
+	}
+}
+const emptyImports = () => ({
+	components: /* @__PURE__ */ new Set(),
+	headless: /* @__PURE__ */ new Set()
+});
+/** Signal 1: what the source under src/ contains. */
+function collectImports(root) {
+	const sets = emptyImports();
+	const src = path.join(root, "src");
+	if (!fs.existsSync(src)) return sets;
+	for (const file of filesUnder(src, SOURCE_EXTENSIONS)) collectImportsFromCode(fs.readFileSync(file, "utf8"), sets);
+	return sets;
+}
+function deriveComponentStates(imports) {
+	const states = {};
+	for (const [surface, { component, hooks, bindings }] of Object.entries(PLATFORM_SURFACES)) if (imports.components.has(component)) states[surface] = "imported";
+	else if (hooks.some((h) => imports.headless.has(h)) || bindings.some((b) => imports.components.has(b))) states[surface] = "custom";
+	return states;
+}
+/**
+* Surfaces whose markup carries a `data-part` vocabulary, and the one marker
+* every rendering of the surface must contain. Looked for in the built output —
+* HTML for server-rendered markup, client JS chunks for islands whose shell is
+* a loading state (Krentz's booking flow is `client:load` and fetches the quote live).
+*/
+const OUTPUT_MARKERS = { booking: "checkout-submit" };
+const OUTPUT_EXTENSIONS = /* @__PURE__ */ new Set([
+	".html",
+	".js",
+	".mjs"
+]);
+/** Which marked surfaces the built output ships. */
+function renderedSurfaces(distDir) {
+	const found = /* @__PURE__ */ new Set();
+	if (!fs.existsSync(distDir)) return found;
+	for (const file of filesUnder(distDir, OUTPUT_EXTENSIONS)) {
+		const text = fs.readFileSync(file, "utf8");
+		for (const [surface, marker] of Object.entries(OUTPUT_MARKERS)) if (text.includes(marker)) found.add(surface);
+	}
+	return found;
+}
+function crossCheck(source, bundled, rendered) {
+	const fromSource = deriveComponentStates(source);
+	const states = bundled ? deriveComponentStates(bundled) : fromSource;
+	const warnings = [];
+	const errors = [];
+	if (bundled) for (const surface of /* @__PURE__ */ new Set([...Object.keys(fromSource), ...Object.keys(states)])) {
+		const a = fromSource[surface];
+		const b = states[surface];
+		if (a && !b) warnings.push(`${surface}: the source imports it (${a}) but no page reaches that code — dead file? The manifest reports the build, not the file.`);
+		else if (!a && b) warnings.push(`${surface}: the build resolves it (${b}) but the source scan did not see a named import — namespace import or re-export; the build wins.`);
+		else if (a && b && a !== b) warnings.push(`${surface}: source says ${a}, build says ${b}; the build wins.`);
+	}
+	for (const surface of rendered) if (!states[surface]) {
+		const { hooks, bindings, component } = PLATFORM_SURFACES[surface];
+		errors.push(`${surface}: the built output ships its data-part markers, but the build imports neither the ${component} component nor its behavior (${[...hooks, ...bindings].join(", ")}) from the platform packages. A ${surface} without the platform's behavior is not allowed — behavior is never forked per site.`);
+	}
+	for (const surface of Object.keys(OUTPUT_MARKERS)) if (states[surface] && !rendered.has(surface)) warnings.push(`${surface}: the code has it (${states[surface]}) but the built output ships no ${OUTPUT_MARKERS[surface]} marker — nothing renders it.`);
+	return {
+		states,
+		warnings,
+		errors
+	};
+}
+function packagesOf(root) {
+	const packages = {};
+	for (const name of TRACKED_PACKAGES) {
+		const version = installedVersion(root, name);
+		if (version) packages[name] = version;
+	}
+	return packages;
+}
+/** Everything without the bundler signal — used by tests and by anything that runs outside a build. */
+function buildSiteManifest(root) {
+	return {
+		manifestVersion: 3,
+		builtAt: (/* @__PURE__ */ new Date()).toISOString(),
+		packages: packagesOf(root),
+		components: deriveComponentStates(collectImports(root))
+	};
+}
+/**
+* The Astro integration:
+*
+*   import { siteManifest } from "@v-office/website-headless/manifest";
+*   integrations: [react(), siteManifest()]
+*
+* Typed structurally so this package needs no astro or vite dependency.
+*/
+function siteManifest() {
+	let root = process.cwd();
+	const bundled = emptyImports();
+	return {
+		name: "@v-office/website-headless/manifest",
+		hooks: {
+			"astro:config:setup": ({ config, updateConfig }) => {
+				root = fileURLToPath(config.root);
+				const src = path.join(root, "src") + path.sep;
+				updateConfig({ vite: { plugins: [{
+					name: "voffice-manifest-imports",
+					transform(code, id) {
+						if (id.startsWith(src) && !id.includes("/node_modules/")) collectImportsFromCode(code, bundled);
+						return null;
+					}
+				}] } });
+			},
+			"astro:build:done": ({ dir }) => {
+				const dist = fileURLToPath(dir);
+				const check = crossCheck(collectImports(root), bundled, renderedSurfaces(dist));
+				for (const w of check.warnings) console.warn(`[site-manifest] ${w}`);
+				if (check.errors.length) throw new Error(`[site-manifest] build refused:\n  - ${check.errors.join("\n  - ")}`);
+				const manifest = {
+					manifestVersion: 3,
+					builtAt: (/* @__PURE__ */ new Date()).toISOString(),
+					packages: packagesOf(root),
+					components: check.states
+				};
+				fs.writeFileSync(path.join(dist, "site-manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+				const states = Object.values(manifest.components);
+				console.log(`[site-manifest] ${Object.keys(manifest.packages).length} packages, ${states.length} surfaces (${states.filter((s) => s === "imported").length} imported, ${states.filter((s) => s === "custom").length} custom); source scan, bundler and built output agree${check.warnings.length ? ` with ${check.warnings.length} warning(s)` : ""}`);
+			}
+		}
+	};
+}
+//#endregion
+export { PLATFORM_SURFACES, buildSiteManifest, collectImports, collectImportsFromCode, crossCheck, deriveComponentStates, emptyImports, renderedSurfaces, siteManifest };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@v-office/website-headless",
+  "version": "0.0.1",
+  "description": "Framework-free behavior layer for v-office websites, never UI: the checkout flow as a subscribable store (createCheckoutFlow), validation and insurance rules, the checkout's structural requirements, the derived site-manifest Astro integration and progressive-enhancement engines for server-rendered markup",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./manifest": "./dist/manifest/index.mjs",
+    "./enhance": "./dist/enhance/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.2",
+    "@v-office/website-sdk": "2.17.1",
+    "jsdom": "^30.0.1",
+    "oxfmt": "0.62.0",
+    "oxlint": "1.77.0",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "peerDependencies": {
+    "@v-office/website-sdk": ">=2.13.0 <3"
+  },
+  "engines": {
+    "node": "^22.0.0 || ^24.0.0 || ^25.0.0 || >=26.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "check": "pnpm run typecheck && pnpm run lint && pnpm run fmt:check",
+    "test": "vitest run"
+  }
+}