@duffcloudservices/cms 0.13.13 → 0.13.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -492,6 +492,65 @@ describe the served document · `3` a requested rail DID NOT RUN. A rail that
492
492
  could not run is never folded into a pass — the C-338 execution assertion,
493
493
  applied to the served side.
494
494
 
495
+ #### Directory-index twins for VitePress `cleanUrls` (C-1965, since 0.13.14)
496
+
497
+ On a VitePress build with `cleanUrls: true`, `dcsSeoPlugin` writes a
498
+ **byte-identical** `<page>/index.html` next to every flat `<page>.html` (index
499
+ pages matched by `(^|/)index\.md$` and the root `404.md` are excluded; public
500
+ files are never touched). Without it, an Azure Static Web App answers
501
+ `/contact/` with `301 Location: https://<name>.azurestaticapps.net/contact`, an
502
+ off-host redirect. A disposable Free SWA proved that with both files present
503
+ `/contact` serves `contact.html` and `/contact/` serves `contact/index.html`,
504
+ both 200, no redirect (`.workboard/records/2026-10-27-lead-C1965-swa-fixture.md`).
505
+
506
+ - It runs **after** the site's own `buildEnd` (CDN rewrite, site files,
507
+ pre-launch stamps), so the twin copies the final bytes, canonical included.
508
+ The twin gets no canonical of its own: the flat page's slash-less canonical
509
+ consolidates `/contact/` onto `/contact`.
510
+ - An existing `<page>/index.html` with **different** bytes fails the build
511
+ (two different documents would be served on one route). A page VitePress
512
+ lists without a rendered `.html` also fails. Nothing is written on failure.
513
+ - Opt out with `dcsSeoPlugin({ dirIndex: false })`. Sites that compose hooks by
514
+ hand can chain `dcsDirIndexBuildEnd()` into `buildEnd`; it shares the
515
+ `Symbol.for('dcs.cms.dirIndex.installed')` guard with the plugin, so it emits
516
+ once however it is registered.
517
+ - **Twin manifest.** When the `DCS_DIR_INDEX_MANIFEST` environment variable
518
+ names a file, the emitter writes there the twins it validated
519
+ (`{ schema: "dcs.cms.dir-index-manifest/v1", outDir, cleanUrls, twins: [{ twin,
520
+ source, sha256 }] }`). A path inside `outDir` fails the build, because the
521
+ manifest must not ship with the site. With the variable unset (a local build),
522
+ no manifest is written. A `dirIndex: false` build removes any file already at
523
+ that path, so a manifest from an earlier build can never describe its dist. The canonical `site-deploy.yml` sets the variable to a
524
+ run-unique file under `$RUNNER_TEMP` for the build step.
525
+ - The canonical `site-deploy.yml` then re-checks the twins after GA injection
526
+ ("Assert directory-index twin parity"). The deploy fails when a listed twin
527
+ is missing or differs from its source, when the dist holds an
528
+ `X/index.html` + `X.html` pair the manifest does not list (an un-owned twin;
529
+ with no manifest at all, any such pair fails), or when twins ship alongside a
530
+ `trailingSlash` rule.
531
+
532
+ **Who gets twins (the default is on).** Every VitePress build that registers
533
+ `dcsSeoPlugin` with `cleanUrls: true` gets twins on its next cms bump; no site
534
+ code change is needed. That is the right behaviour for an Azure Static Web App,
535
+ and every such consumer DCS runs is one (census 2026-10-28 in
536
+ `.workboard/records/2026-10-28-laneB-C1965-roll-blockers-s1.md`). On other
537
+ hosts the twins are harmless static files, but they change what `/page/`
538
+ serves:
539
+
540
+ - On a host that already serves `/page/` from `page.html` (or redirects it on
541
+ the same host), `/page/` becomes a 200 copy of the page instead of a
542
+ redirect. The copy carries the flat page's slash-less canonical, so search
543
+ engines consolidate on `/page`.
544
+ - On a host that 404s `/page/` today (plain blob or bucket static hosting),
545
+ `/page/` starts answering 200.
546
+ - A build that also ships a hand-written `page/index.html` with different
547
+ content now fails (two documents on one route).
548
+ - The dist gains one file per flat page. Check the host's file-count quota.
549
+
550
+ To keep the pre-0.13.14 output, opt out with `dcsSeoPlugin({ dirIndex: false })`.
551
+ Builds without `cleanUrls: true`, non-VitePress builds and `vitepress dev`
552
+ never get twins.
553
+
495
554
  ## Configuration Files
496
555
 
497
556
  ### .dcs/content.yaml
@@ -219,4 +219,4 @@ declare function assertHeadHonesty(observations: HeadObservation[], options: Hea
219
219
  debug?: boolean;
220
220
  }): HeadHonestyViolation[];
221
221
 
222
- export { type BakedHead as B, type HonestyMode as H, type HeadObservation as a, assertHeadHonesty as b, formatHeadHonestyReport as c, decodeHtmlEntities as d, extractBakedHead as e, findHeadHonestyViolations as f, HeadHonestyError as g, assertHeadHonestyExecuted as h, findHeadHonestyExecutionFaults as i, formatHeadHonestyExecutionReport as j, HeadHonestyNotRunError as k, type HeadHonestyExecution as l, type HonestyModeInput as m, normalizeHeadText as n, type HeadHonestyViolation as o, type HeadHonestyOptions as p, resolveHonestyMode as r };
222
+ export { type BakedHead as B, type HonestyMode as H, type HeadObservation as a, HeadHonestyError as b, type HeadHonestyExecution as c, HeadHonestyNotRunError as d, type HeadHonestyOptions as e, type HeadHonestyViolation as f, type HonestyModeInput as g, assertHeadHonesty as h, assertHeadHonestyExecuted as i, decodeHtmlEntities as j, extractBakedHead as k, findHeadHonestyExecutionFaults as l, findHeadHonestyViolations as m, formatHeadHonestyExecutionReport as n, formatHeadHonestyReport as o, normalizeHeadText as p, resolveHonestyMode as r };
package/dist/index.d.ts CHANGED
@@ -1,8 +1,8 @@
1
1
  import * as vue from 'vue';
2
2
  import { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
3
- import { U as UseSeoReturn, G as GlobalSeoConfig } from './vitepressTransform-CZ_IB3dq.js';
4
- export { A as AI_BOTS, y as BlogMeta, x as BreadcrumbCrumb, v as BuildLlmsParams, u as BuildRobotsParams, B as BuildSitemapParams, E as ContentConfig, C as CreateSeoTransformPageDataOptions, D as DcsRobotsOptions, F as FaqSource, X as HeadOverrides, P as PageSeoConfig, R as ResolvedPageOverrides, T as ResolvedPageSeo, z as ReviewSource, w as SchemaObject, O as SeoAlternateConfig, I as SeoAuthorConfig, H as SeoConfiguration, K as SeoImagesConfig, L as SeoOpenGraphConfig, S as SeoPageContext, r as SeoPageTypeRule, N as SeoSchemaConfig, J as SeoSocialConfig, M as SeoTwitterConfig, Q as SeoVerificationConfig, W as UseSeoConfig, t as VitePressHeadConfig, V as VitePressPageData, q as absolutizeUrl, j as breadcrumbTrailFromRoute, k as buildBlogPosting, h as buildBreadcrumbList, l as buildFaqPage, g as buildGlobalGraph, f as buildLlmsTxt, m as buildReviewSchemaParts, e as buildRobotsTxt, a as buildSitemapXml, b as buildVitePressSeoHead, c as createSeoTransformPageData, d as defaultRelativePathToRoute, o as filterRealFaq, n as filterRealReviews, p as findReviewItemsForPage, i as isRouteIndexable, s as slugToTitle } from './vitepressTransform-CZ_IB3dq.js';
5
- export { l as HeadLinkTag, H as HeadMetaTag, m as HeadScriptTag, o as HeadTagOverrides, I as InstallSeoHeadOptions, R as ResolvedHeadTags, q as SeoHeadClientLike, t as SeoHeadEntryLike, u as SeoHeadInput, v as SeoHeadPageRoute, w as SeoHeadPagesManifest, x as SeoHeadResolution, y as SeoHeadResolutionReason, p as SeoHeadRouteLike, S as SeoHeadRouterLike, b as buildHeadTags, k as buildSeoHeadRouteMap, f as escapeJsonLd, g as generateJsonLd, a as generateOpenGraphMeta, c as generateTwitterMeta, j as installSeoHead, h as isManagedLinkRel, i as isManagedMetaTag, n as normalizeSeoHeadPath, d as renderHeadTags, r as resolvePageSeo, s as spliceHeadHtml, e as stripManagedHeadTags } from './installSeoHead-CuVdVCis.js';
3
+ import { G as GlobalSeoConfig, U as UseSeoReturn } from './vitepressTransform-BJrpGbVT.js';
4
+ export { A as AI_BOTS, B as BlogMeta, a as BreadcrumbCrumb, b as BuildLlmsParams, c as BuildRobotsParams, d as BuildSitemapParams, C as ContentConfig, e as CreateSeoTransformPageDataOptions, D as DcsRobotsOptions, F as FaqSource, H as HeadOverrides, P as PageSeoConfig, R as ResolvedPageOverrides, f as ResolvedPageSeo, g as ReviewSource, S as SchemaObject, h as SeoAlternateConfig, i as SeoAuthorConfig, j as SeoConfiguration, k as SeoImagesConfig, l as SeoOpenGraphConfig, m as SeoPageContext, n as SeoPageTypeRule, o as SeoSchemaConfig, p as SeoSocialConfig, q as SeoTwitterConfig, r as SeoVerificationConfig, s as UseSeoConfig, V as VitePressHeadConfig, t as VitePressPageData, u as absolutizeUrl, v as breadcrumbTrailFromRoute, w as buildBlogPosting, x as buildBreadcrumbList, y as buildFaqPage, z as buildGlobalGraph, E as buildLlmsTxt, I as buildReviewSchemaParts, J as buildRobotsTxt, K as buildSitemapXml, L as buildVitePressSeoHead, M as createSeoTransformPageData, N as defaultRelativePathToRoute, O as filterRealFaq, Q as filterRealReviews, T as findReviewItemsForPage, W as isRouteIndexable, X as slugToTitle } from './vitepressTransform-BJrpGbVT.js';
5
+ export { H as HeadLinkTag, a as HeadMetaTag, b as HeadScriptTag, c as HeadTagOverrides, I as InstallSeoHeadOptions, R as ResolvedHeadTags, S as SeoHeadClientLike, d as SeoHeadEntryLike, e as SeoHeadInput, f as SeoHeadPageRoute, g as SeoHeadPagesManifest, h as SeoHeadResolution, i as SeoHeadResolutionReason, j as SeoHeadRouteLike, k as SeoHeadRouterLike, l as buildHeadTags, m as buildSeoHeadRouteMap, n as escapeJsonLd, o as generateJsonLd, p as generateOpenGraphMeta, q as generateTwitterMeta, r as installSeoHead, s as isManagedLinkRel, t as isManagedMetaTag, u as normalizeSeoHeadPath, v as renderHeadTags, w as resolvePageSeo, x as spliceHeadHtml, y as stripManagedHeadTags } from './installSeoHead-DPVmX-eY.js';
6
6
  import { ImageContext, ResponsiveImageResult } from '@duffcloudservices/cms-core';
7
7
  export { ImageContext, ResponsiveImageOptions, ResponsiveImageResult, ResponsiveSource, isCdnAssetUrl, resolveResponsiveImage } from '@duffcloudservices/cms-core';
8
8
 
@@ -1,4 +1,4 @@
1
- import { H as SeoConfiguration, x as BreadcrumbCrumb, z as ReviewSource, F as FaqSource, y as BlogMeta, T as ResolvedPageSeo, N as SeoSchemaConfig, G as GlobalSeoConfig, L as SeoOpenGraphConfig, M as SeoTwitterConfig } from './vitepressTransform-CZ_IB3dq.js';
1
+ import { a as BreadcrumbCrumb, g as ReviewSource, F as FaqSource, B as BlogMeta, f as ResolvedPageSeo, j as SeoConfiguration, o as SeoSchemaConfig, G as GlobalSeoConfig, l as SeoOpenGraphConfig, q as SeoTwitterConfig } from './vitepressTransform-BJrpGbVT.js';
2
2
 
3
3
  /**
4
4
  * Framework-agnostic SEO head-tag resolution.
@@ -675,4 +675,4 @@ declare function buildSeoHeadRouteMap(routes: readonly SeoHeadPageRoute[]): Map<
675
675
  */
676
676
  declare function installSeoHead(router: SeoHeadRouterLike, options: InstallSeoHeadOptions): unknown;
677
677
 
678
- export { formatDuplicateNormalizedPaths as A, SEO_HEAD_ROUTE_HAS_NO_META as B, type SeoHeadRouteHasNoMeta as C, type HeadMetaTag as H, type InstallSeoHeadOptions as I, type ResolvedHeadTags as R, type SeoHeadRouterLike as S, generateOpenGraphMeta as a, buildHeadTags as b, generateTwitterMeta as c, renderHeadTags as d, stripManagedHeadTags as e, escapeJsonLd as f, generateJsonLd as g, isManagedLinkRel as h, isManagedMetaTag as i, installSeoHead as j, buildSeoHeadRouteMap as k, type HeadLinkTag as l, type HeadScriptTag as m, normalizeSeoHeadPath as n, type HeadTagOverrides as o, type SeoHeadRouteLike as p, type SeoHeadClientLike as q, resolvePageSeo as r, spliceHeadHtml as s, type SeoHeadEntryLike as t, type SeoHeadInput as u, type SeoHeadPageRoute as v, type SeoHeadPagesManifest as w, type SeoHeadResolution as x, type SeoHeadResolutionReason as y, findDuplicateNormalizedPaths as z };
678
+ export { type SeoHeadRouteHasNoMeta as A, findDuplicateNormalizedPaths as B, formatDuplicateNormalizedPaths as C, type HeadLinkTag as H, type InstallSeoHeadOptions as I, type ResolvedHeadTags as R, type SeoHeadClientLike as S, type HeadMetaTag as a, type HeadScriptTag as b, type HeadTagOverrides as c, type SeoHeadEntryLike as d, type SeoHeadInput as e, type SeoHeadPageRoute as f, type SeoHeadPagesManifest as g, type SeoHeadResolution as h, type SeoHeadResolutionReason as i, type SeoHeadRouteLike as j, type SeoHeadRouterLike as k, buildHeadTags as l, buildSeoHeadRouteMap as m, escapeJsonLd as n, generateJsonLd as o, generateOpenGraphMeta as p, generateTwitterMeta as q, installSeoHead as r, isManagedLinkRel as s, isManagedMetaTag as t, normalizeSeoHeadPath as u, renderHeadTags as v, resolvePageSeo as w, spliceHeadHtml as x, stripManagedHeadTags as y, SEO_HEAD_ROUTE_HAS_NO_META as z };
@@ -1,7 +1,7 @@
1
1
  import { Plugin, HtmlTagDescriptor } from 'vite';
2
- import { D as DcsRobotsOptions, Y as SeoHonestyBlock, Z as PageRouteEntry, H as SeoConfiguration, E as ContentConfig } from '../vitepressTransform-CZ_IB3dq.js';
3
- export { C as CreateSeoTransformPageDataOptions, R as ResolvedPageOverrides, S as SeoPageContext, r as SeoPageTypeRule, t as VitePressHeadConfig, V as VitePressPageData, b as buildVitePressSeoHead, c as createSeoTransformPageData, d as defaultRelativePathToRoute } from '../vitepressTransform-CZ_IB3dq.js';
4
- import { H as HonestyMode } from '../headHonesty-OzxvLuwd.js';
2
+ import { D as DcsRobotsOptions, Y as SeoHonestyBlock, Z as PageRouteEntry, j as SeoConfiguration, C as ContentConfig } from '../vitepressTransform-BJrpGbVT.js';
3
+ export { e as CreateSeoTransformPageDataOptions, R as ResolvedPageOverrides, m as SeoPageContext, n as SeoPageTypeRule, V as VitePressHeadConfig, t as VitePressPageData, L as buildVitePressSeoHead, M as createSeoTransformPageData, N as defaultRelativePathToRoute } from '../vitepressTransform-BJrpGbVT.js';
4
+ import { H as HonestyMode } from '../headHonesty-k1IhGblP.js';
5
5
  import { Component, Plugin as Plugin$1 } from 'vue';
6
6
  import MarkdownIt from 'markdown-it';
7
7
 
@@ -213,6 +213,19 @@ interface DcsSeoPluginOptions {
213
213
  * Env override: `DCS_SEO_CHARSET_BUDGET=error|warn|off`.
214
214
  */
215
215
  charsetBudget?: boolean | HonestyMode | SeoHonestyBlock;
216
+ /**
217
+ * C-1965: on a VitePress `cleanUrls` BUILD, write a byte-identical
218
+ * `<page>/index.html` twin of every flat `<page>.html` (index pages and the
219
+ * root `404.md` excluded) after the site's own `buildEnd`, so `/page/`
220
+ * answers 200 on an Azure Static Web App instead of 301-ing to the
221
+ * `*.azurestaticapps.net` default host. Default `true`; non-VitePress builds
222
+ * and `vitepress dev` are never touched. An existing `<page>/index.html` with
223
+ * different bytes FAILS the build. See `dcsDirIndex.ts`. On by default
224
+ * because every DCS cleanUrls consumer is an Azure SWA; on another host the
225
+ * twins change what `/page/` serves (README, "Directory-index twins"), and
226
+ * `false` keeps the pre-0.13.14 output.
227
+ */
228
+ dirIndex?: boolean;
216
229
  }
217
230
  /**
218
231
  * Every key a `noindex` entry can legitimately match.
@@ -549,6 +562,187 @@ declare function dcsCdnBuildEnd(options?: DcsCdnBuildEndOptions): (siteConfig: {
549
562
 
550
563
  declare function responsiveImagePlugin(md: MarkdownIt): void;
551
564
 
565
+ /**
566
+ * DCS directory-index twins for VitePress `cleanUrls` builds (C-1965).
567
+ *
568
+ * THE DEFECT. A VitePress site built with `cleanUrls: true` emits every
569
+ * non-index page flat: `contact.md` -> `dist/contact.html`. On an Azure Static
570
+ * Web App with no `trailingSlash` rule, `/contact` answers 200 but `/contact/`
571
+ * answers `301 Location: https://<swa-default-host>/contact` - an ABSOLUTE
572
+ * redirect to the `*.azurestaticapps.net` host, because Front Door sends that
573
+ * host as the origin Host and a Free SWA ignores `X-Forwarded-Host`. Measured
574
+ * live on kimduffhomes.com, nateduff.com, bryanduffhomes.com and bryanduff.com
575
+ * (.workboard/records/2026-10-27-lead-C1965-swa-fixture.md section 1).
576
+ *
577
+ * THE FIX, PROVEN ON A DISPOSABLE FREE SWA (same record, section 3f): when both
578
+ * `x.html` and `x/index.html` exist, SWA serves `x.html` for `/x` and
579
+ * `x/index.html` for `/x/`, both 200, no `Location`, in either direction. So for
580
+ * every flat page this writes `<page>/index.html` as a BYTE-IDENTICAL twin of
581
+ * `<page>.html`.
582
+ *
583
+ * WHY STRICT. The two URLs are served by two different files, so a twin that
584
+ * differs from its flat page shows visitors and crawlers two different
585
+ * documents on `/x` and `/x/`. An existing `<page>/index.html` with different
586
+ * bytes is therefore a BUILD FAILURE, never a skip. A page VitePress says it
587
+ * rendered whose `.html` is missing is also fatal: the emitter's model of the
588
+ * build would be wrong.
589
+ *
590
+ * NO CANONICAL OF ITS OWN. The flat page already carries the cms factory's
591
+ * absolute, slash-less canonical (`vitepressTransform.ts`), and a byte copy
592
+ * carries it too, so `/contact/` consolidates onto `/contact`. A self-canonical
593
+ * `/contact/` would split the signal.
594
+ *
595
+ * ORDER. The twin must copy the FINAL bytes. VitePress applies `transformHtml`
596
+ * before it writes each page, and the site's own `buildEnd` (CDN rewrite,
597
+ * site files, pre-launch stamps) runs next; the emitter is chained AFTER that
598
+ * hook. The canonical deploy workflow then injects GA into every `*.html` and
599
+ * re-checks the pairs (site-deploy.yml, "Assert directory-index twin parity").
600
+ *
601
+ * THE MANIFEST (C-1965 roll-blocker N2). When `DCS_DIR_INDEX_MANIFEST` names a
602
+ * file, every emitter run writes there the list of twins it validated (twin
603
+ * path, source path, sha256 of the bytes it copied), so the deploy workflow
604
+ * checks the pairs the cms OWNS instead of inferring pairs from the dist. The
605
+ * canonical workflow points it at a run-unique file under `$RUNNER_TEMP`:
606
+ * outside the SWA upload directory (nothing new is served) and outside the
607
+ * site repo (nothing new to ignore or commit). Unset (a local build), nothing
608
+ * is written.
609
+ *
610
+ * TWO ENTRY POINTS, ONE GUARD. `dcsSeoPlugin` installs the emitter
611
+ * automatically on a VitePress build (`dirIndex: false` opts out). A site that
612
+ * wants explicit composition can chain `dcsDirIndexBuildEnd()` into its own
613
+ * `buildEnd`. Both go through the registry symbol
614
+ * `Symbol.for('dcs.cms.dirIndex.installed')` on VitePress's `siteConfig`, which
615
+ * is the same object for the client and the SSR config resolution, so the
616
+ * emitter runs exactly once however many times it is registered.
617
+ *
618
+ * @example Explicit composition (optional - dcsSeoPlugin already installs it)
619
+ * ```ts
620
+ * // .vitepress/config.ts
621
+ * import { chainBuildEnd, dcsCdnBuildEnd, dcsDirIndexBuildEnd } from '@duffcloudservices/cms/plugins'
622
+ *
623
+ * export default defineConfig({
624
+ * cleanUrls: true,
625
+ * buildEnd: chainBuildEnd(dcsCdnBuildEnd(), dcsDirIndexBuildEnd()),
626
+ * })
627
+ * ```
628
+ */
629
+ /**
630
+ * The idempotency guard. A REGISTRY symbol (`Symbol.for`), not `Symbol()`: it
631
+ * must be the same key across module instances (the plugin barrel and a
632
+ * site-local import can be two copies) and across the client and SSR config
633
+ * resolutions.
634
+ */
635
+ declare const DIR_INDEX_INSTALLED: unique symbol;
636
+ /**
637
+ * The environment variable that names the twin manifest file. Read at emit
638
+ * time; an empty or unset value writes no manifest.
639
+ */
640
+ declare const DIR_INDEX_MANIFEST_ENV = "DCS_DIR_INDEX_MANIFEST";
641
+ /** The manifest's `schema` value; the workflow step refuses any other. */
642
+ declare const DIR_INDEX_MANIFEST_SCHEMA = "dcs.cms.dir-index-manifest/v1";
643
+ /** One twin the emitter validated (written, or already present and identical). */
644
+ interface DirIndexManifestEntry {
645
+ /** `<page>/index.html`, relative to `outDir`, forward slashes. */
646
+ twin: string;
647
+ /** `<page>.html`, relative to `outDir`, forward slashes. */
648
+ source: string;
649
+ /** sha256 (hex) of the bytes copied, i.e. the source as the emitter read it. */
650
+ sha256: string;
651
+ }
652
+ /** The file `DCS_DIR_INDEX_MANIFEST` names, written on every emitter run. */
653
+ interface DirIndexManifest {
654
+ schema: typeof DIR_INDEX_MANIFEST_SCHEMA;
655
+ /** Absolute build output directory the twins live in. */
656
+ outDir: string;
657
+ /** Whether the build had `cleanUrls` on (off: `twins` is empty). */
658
+ cleanUrls: boolean;
659
+ /** Sorted by `twin`. */
660
+ twins: DirIndexManifestEntry[];
661
+ }
662
+ interface EmitDirectoryIndexesOptions {
663
+ /**
664
+ * Where to write the twin manifest. Defaults to
665
+ * `process.env.DCS_DIR_INDEX_MANIFEST`; when neither is set, nothing is
666
+ * written. Relative paths resolve against `process.cwd()`.
667
+ */
668
+ manifestPath?: string;
669
+ }
670
+ /** The subset of VitePress's resolved `SiteConfig` the emitter reads. */
671
+ interface DirIndexSiteConfig {
672
+ /** Absolute build output directory. */
673
+ outDir: string;
674
+ /** Source pages relative to `srcDir`, e.g. `contact.md`, `blogs/post.md`. */
675
+ pages: string[];
676
+ /** VitePress rewrites; a page renders at `rewrites.map[page] ?? page`. */
677
+ rewrites?: {
678
+ map?: Record<string, string | undefined>;
679
+ };
680
+ /** Twins are emitted only when `cleanUrls` is on. */
681
+ cleanUrls?: boolean;
682
+ /** VitePress's single `buildEnd` hook. */
683
+ buildEnd?: (siteConfig: never) => unknown;
684
+ }
685
+ interface DirIndexResult {
686
+ /** Twins written by this run. */
687
+ written: number;
688
+ /** Twins already present with identical bytes (left untouched). */
689
+ identical: number;
690
+ /** The twin paths (relative to `outDir`, forward slashes) written or found identical. */
691
+ twins: string[];
692
+ /** Absolute path of the manifest written by this run, when one was requested. */
693
+ manifestPath?: string;
694
+ }
695
+ /** Thrown for a missing source page or an unequal `<page>/index.html` collision. */
696
+ declare class DirIndexError extends Error {
697
+ constructor(message: string);
698
+ }
699
+ /**
700
+ * The flat pages that get a twin: every mapped page except index pages
701
+ * (`(^|/)index\.md$`) and the root `404.md`. Returned as mapped `.md` paths.
702
+ */
703
+ declare function dirIndexCandidates(siteConfig: Pick<DirIndexSiteConfig, 'pages' | 'rewrites'>): string[];
704
+ /**
705
+ * Remove a manifest left at `DCS_DIR_INDEX_MANIFEST` by an earlier build, for a
706
+ * build whose emitter is DISABLED (`dirIndex: false`). Removal, not an empty
707
+ * manifest: a disabled emitter owns nothing and validated nothing, and "no
708
+ * manifest" is exactly how the deploy step reads that (no pairs passes, any
709
+ * pair is un-owned and fails), so a stale list from another build can never
710
+ * vouch for this dist. A regular file or a symlink (unlinked, never followed)
711
+ * is removed; a directory is not. Returns the path removed.
712
+ */
713
+ declare function clearDirIndexManifest(manifestPath?: string | undefined): string | undefined;
714
+ /**
715
+ * Write a byte-identical `<page>/index.html` for every flat page of a
716
+ * `cleanUrls` VitePress build. Validates every pair BEFORE writing anything,
717
+ * so a failing build leaves `outDir` exactly as VitePress produced it.
718
+ *
719
+ * When a manifest path is set (option or `DCS_DIR_INDEX_MANIFEST`), any file
720
+ * already there is removed first and a fresh manifest is written on success,
721
+ * including the `cleanUrls: false` no-op (an empty list). A refused build
722
+ * leaves no manifest. A manifest path inside `outDir` is refused: it would
723
+ * ship with the site.
724
+ */
725
+ declare function emitDirectoryIndexes(siteConfig: DirIndexSiteConfig, options?: EmitDirectoryIndexesOptions): DirIndexResult;
726
+ /**
727
+ * The AUTOMATIC entry point (called by `dcsSeoPlugin` on a VitePress build).
728
+ * Wraps `siteConfig.buildEnd` so the site's own hook runs FIRST and the
729
+ * emitter copies its final output. Returns `false` when already installed
730
+ * (the client and SSR builds both resolve config; a second plugin instance
731
+ * may also call this).
732
+ */
733
+ declare function installDirIndex(siteConfig: DirIndexSiteConfig): boolean;
734
+ /**
735
+ * The MANUAL entry point: a VitePress `buildEnd` hook for sites that compose
736
+ * their hooks explicitly. It shares the automatic guard:
737
+ *
738
+ * - If `dcsSeoPlugin` already installed the emitter, this DEFERS to it (the
739
+ * automatic wrapper runs after the site's whole `buildEnd`, so it copies the
740
+ * final bytes) and does nothing itself.
741
+ * - Otherwise it claims the guard and emits, once, however many times it is
742
+ * chained.
743
+ */
744
+ declare function dcsDirIndexBuildEnd(): (siteConfig: DirIndexSiteConfig) => Promise<void>;
745
+
552
746
  /**
553
747
  * Build-time responsive-variant lint for DCS customer sites.
554
748
  *
@@ -770,4 +964,4 @@ interface DcsAgentWidgetTagOptions {
770
964
  */
771
965
  declare function dcsAgentWidgetLoaderTag(options: DcsAgentWidgetTagOptions): HtmlTagDescriptor | null;
772
966
 
773
- export { AGENT_CONFIG_ORIGINS, type AgentConfigOrigin, DCS_MOTION_TOKENS_CSS, DEFAULT_AGENT_API_BASE_URL, DEFAULT_AGENT_WIDGET_SCRIPT_URL, type DcsAgentWidgetLoaderOptions, type DcsAgentWidgetTagOptions, type DcsCdnBuildEndOptions, type DcsCdnImagePluginOptions, type DcsContentPluginOptions, type DcsEditorPluginOptions, type DcsPreviewPluginOptions, type DcsResponsiveImageLintOptions, type DcsSeoPluginOptions, NoindexOrphanError, type ResponsiveImageLintReport, type ResponsiveImageViolation, buildAgentWidgetLoaderScript, chainBuildEnd, collectNoindexMatchKeys, dcsAgentWidgetLoaderTag, dcsCdnBuildEnd, dcsCdnImagePlugin, dcsContentPlugin, dcsEditorPlugin, dcsMotionTokensStyleTag, dcsPreviewPlugin, dcsResponsiveImageLint, dcsSeoPlugin, emitSiteFiles, emitStaticSeoHtml, findFullSizeCdnImages, findOrphanNoindexEntries, isFullSizeCdnUrl, readAgentConfigOrigin, readSiteSlug, responsiveImagePlugin };
967
+ export { AGENT_CONFIG_ORIGINS, type AgentConfigOrigin, DCS_MOTION_TOKENS_CSS, DEFAULT_AGENT_API_BASE_URL, DEFAULT_AGENT_WIDGET_SCRIPT_URL, DIR_INDEX_INSTALLED, DIR_INDEX_MANIFEST_ENV, DIR_INDEX_MANIFEST_SCHEMA, type DcsAgentWidgetLoaderOptions, type DcsAgentWidgetTagOptions, type DcsCdnBuildEndOptions, type DcsCdnImagePluginOptions, type DcsContentPluginOptions, type DcsEditorPluginOptions, type DcsPreviewPluginOptions, type DcsResponsiveImageLintOptions, type DcsSeoPluginOptions, DirIndexError, type DirIndexManifest, type DirIndexManifestEntry, type DirIndexResult, type DirIndexSiteConfig, type EmitDirectoryIndexesOptions, NoindexOrphanError, type ResponsiveImageLintReport, type ResponsiveImageViolation, buildAgentWidgetLoaderScript, chainBuildEnd, clearDirIndexManifest, collectNoindexMatchKeys, dcsAgentWidgetLoaderTag, dcsCdnBuildEnd, dcsCdnImagePlugin, dcsContentPlugin, dcsDirIndexBuildEnd, dcsEditorPlugin, dcsMotionTokensStyleTag, dcsPreviewPlugin, dcsResponsiveImageLint, dcsSeoPlugin, dirIndexCandidates, emitDirectoryIndexes, emitSiteFiles, emitStaticSeoHtml, findFullSizeCdnImages, findOrphanNoindexEntries, installDirIndex, isFullSizeCdnUrl, readAgentConfigOrigin, readSiteSlug, responsiveImagePlugin };