feat(marketing): phase 4 — the marketing pages
All checks were successful
PR checks / checks (pull_request) Successful in 9m9s

PLAN.md §13 phase 4: /features/, /architecture/, /modules/, /integrations/, and
/community/ — plus the two scope items the phase table never assigned to anyone.

Six decisions taken by the org lead before coding, recorded in PLAN.md §10 as
D20-D25:

- D20 /features/ is the homepage's list with a `detail` line, not a second list.
  One data file, two renderings, so they cannot disagree about what exists.
- D21 /architecture/ draws reasons, not reference: three new inline SVGs, one per
  boundary. No endpoint tables, no config keys — those are phase 8's and stay
  canonical in docs/.
- D22 The deliberate absences of §2 become one tagged data file, rendered on the
  three pages that promise them.
- D23 Phase 4 absorbs /community/ (specified in §10 and §14 N3, linked from the
  header since phase 1, built by no phase) and checkLinks.mjs.
- D24 `needsModule`: writing the Teams detail exposed a false claim phase 3
  shipped. Teams are module-sourced only — teams.module_id is NOT NULL, there is
  no create route, sync is gated on providerModuleId() — so the Community group
  no longer says a bare core does all of it.
- D25 The per-capability demo affordance brand.json had promised since phase 2 is
  a deep link, filled at boot from data-demo-path.

checkLinks.mjs reads the built HTML rather than src/, because half these links
are assembled from data files and template literals. Its PLANNED_ROUTES list is
checked in both directions, so it cannot rot into a permanent exemption.

applyBrand.mjs gained a pass that recomputes deep links from their immutable
path, making it idempotent and reversible; checkBrand.mjs lifts that pattern out
and runs it against the stock markup so the two cannot drift. Both proved
against a real mount, in both directions.

Fixes a cascade bug the checks could not see: [data-demo-url=''] and a scoped
component class are both specificity 0,1,0, so .demo-link's `display` beat the
hide rule and twelve links to a nonexistent demo rendered, each resolving to the
current page. The rule is now !important.

The four diagrams' shared SVG vocabulary moved to src/styles/diagram.css.

Verified from a clean checkout: npm ci, all five checks, astro check (0 errors),
production build, and a live browser pass at desktop and 390px.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2026-08-24 01:53:11 -05:00
parent d9d7a8d47f
commit 2d19ee4220
21 changed files with 3332 additions and 119 deletions

View File

@@ -290,6 +290,87 @@ if (!attrTemplate) {
}
}
/* =======================================================================================
5. The demo DEEP-link contract (§15 / D25)
=======================================================================================
`/features/` links individual capabilities into the demo, which the slot in §4 cannot
express — it swaps a whole URL, so it can only ever produce the demo's root. Those links
carry a third attribute and `applyBrand.mjs` recomputes all three from it.
Same failure mode as §4 and the same reason to check it: a template and a script with no
shared code, agreeing on an exact byte sequence, where disagreement is silent. This one
is worse in one respect — a broken deep link is INVISIBLE in a stock build, because the
stock build hides every demo link. It would first appear on the day the org lead sets
`demoUrl` and finds the new links pointing at the demo's front page, or at nothing.
The regex is not retyped here either: it is lifted out of `applyBrand.mjs` and run
against the stock literal, so this fails if the script's pattern stops matching what the
templates write — whichever side moved. */
const deepPattern = applyForCheck.match(/const DEEP_LINK = \/(.*)\/g;/);
const EMPTY_DEEP_PREFIX = 'href="" data-demo-url="" ';
let deepLinkCount = 0;
if (!deepPattern) {
fail(
'applyBrand.mjs no longer defines DEEP_LINK as a single /…/g literal.\n' +
' §15/D25 relies on it to fill the per-capability demo links. Update this check to\n' +
' match the new shape rather than deleting it.'
);
} else {
// Does the script's own pattern still match what a template writes in a stock build?
const sample = `${EMPTY_DEEP_PREFIX}data-demo-path="/example"`;
let matches = false;
try {
matches = new RegExp(deepPattern[1]).test(sample);
} catch (error) {
fail(`applyBrand.mjs's DEEP_LINK is not a usable pattern: ${error.message}`);
}
if (!matches) {
fail(
`applyBrand.mjs's DEEP_LINK no longer matches the stock markup \`${sample}\`.\n` +
' Every per-capability demo link would be left empty and hidden, on a deployment\n' +
' that has a demo configured — which is the one place nobody would look.'
);
}
const deepStrays = [];
let deepLinks = 0;
for await (const file of walk(path.join(ROOT, 'src'))) {
if (path.extname(file) !== '.astro') continue;
// Blanked, not stripped — same reason as §4: the line numbers reported have to be the
// ones in the file.
const blank = (match) => match.replace(/[^\n]/g, ' ');
const source = readFileSync(file, 'utf8')
.replace(/\/\*[\s\S]*?\*\//g, blank)
.replace(/<!--[\s\S]*?-->/g, blank);
const relative = path.relative(ROOT, file);
for (const match of source.matchAll(/data-demo-path/g)) {
deepLinks++;
const start = match.index - EMPTY_DEEP_PREFIX.length;
if (start < 0 || source.slice(start, match.index) !== EMPTY_DEEP_PREFIX) {
deepStrays.push(`${relative}:${source.slice(0, match.index).split('\n').length}`);
}
}
}
for (const site of deepStrays) {
fail(
`${site} writes data-demo-path without the exact prefix \`${EMPTY_DEEP_PREFIX}\`.\n` +
' applyBrand.mjs matches all three attributes together and in that order; anything\n' +
' else is invisible to it and the link will never point anywhere.'
);
}
deepLinkCount = deepLinks;
}
/* ======================================================================================= */
if (failures.length) {
@@ -301,5 +382,6 @@ if (failures.length) {
console.log(
`checkBrand: brand-default is complete, ${referenced.size} /brand/ URL(s) resolve, ` +
`every rewritable string is safe to replace, and the demo slot matches its contract.`
`every rewritable string is safe to replace, and the demo slot plus ${deepLinkCount} ` +
`deep link(s) match their contracts.`
);