From 8a64f1d7d456136a6a48b4377cd40bed8921d667 Mon Sep 17 00:00:00 2001 From: stan nesi Date: Sun, 7 Jun 2026 09:41:51 -0500 Subject: [PATCH] feat: add public docs and hosting path --- .github/workflows/viewer-demo-pages.yml | 3 + BUILD_STATUS.md | 14 +- NEXT_STEPS.md | 8 +- README.md | 12 +- apps/prd-viewer-web/public/_redirects | 1 + apps/prd-viewer-web/src/App.tsx | 183 ++++++++++++++++-- apps/prd-viewer-web/src/styles.css | 142 +++++++++++++- .../src/viewerDemoContent.test.ts | 48 ++++- apps/prd-viewer-web/src/viewerDemoContent.ts | 155 ++++++++++++++- apps/prd-viewer-web/src/viewerRoutes.test.ts | 25 ++- apps/prd-viewer-web/src/viewerRoutes.ts | 29 ++- codex/SESSION_HANDOFF.md | 178 +++++++---------- docs/README.md | 10 +- docs/foundation/04_PRD/PRD_ROADMAP.md | 7 +- docs/governance/PRD_HOSTING_RUNBOOK.md | 82 ++++++++ docs/product/PRD_AUTHORING_WORKFLOW.md | 2 +- docs/product/PRD_IMPORT_EXPORT_MATRIX.md | 6 +- docs/product/PRD_PRODUCT_BOUNDARIES.md | 6 +- 18 files changed, 748 insertions(+), 163 deletions(-) create mode 100644 apps/prd-viewer-web/public/_redirects create mode 100644 docs/governance/PRD_HOSTING_RUNBOOK.md diff --git a/.github/workflows/viewer-demo-pages.yml b/.github/workflows/viewer-demo-pages.yml index 3192c1e..6205b9f 100644 --- a/.github/workflows/viewer-demo-pages.yml +++ b/.github/workflows/viewer-demo-pages.yml @@ -54,6 +54,9 @@ jobs: env: PRD_VIEWER_BASE_PATH: /prd/ + - name: Add GitHub Pages SPA fallback + run: cp apps/prd-viewer-web/dist/index.html apps/prd-viewer-web/dist/404.html + - name: Upload Pages artifact uses: actions/upload-pages-artifact@v3 with: diff --git a/BUILD_STATUS.md b/BUILD_STATUS.md index 5803e86..3620ba8 100644 --- a/BUILD_STATUS.md +++ b/BUILD_STATUS.md @@ -1,10 +1,20 @@ # BUILD STATUS +## 2026-06-07 + +- Merged PR `#46` (`[stannesi] separate hosted landing and viewer routes`) into `main` before starting the public site/docs/hosting polish slice. +- Renamed user-facing hosted-app language from “Landing” to “Home” while keeping the route `/`. +- Added `/docs/` as a public docs index inside `apps/prd-viewer-web`, giving users a clean navigation layer for Home, Getting Started, CLI, Format, Profiles, Examples, Viewer, Conformance, and Release/Operator Notes without linking internal `codex/` workflow docs. +- Documented Cloudflare Pages as the intended production host for `prd.eonhive.com` and kept GitHub Pages as temporary staging/fallback under `/prd/`. +- Added `docs/governance/PRD_HOSTING_RUNBOOK.md` for the public hosting path, custom-domain launch checklist, and route expectations. +- Added Cloudflare Pages SPA fallback configuration through `apps/prd-viewer-web/public/_redirects` and GitHub Pages `404.html` fallback generation in the viewer demo workflow. +- This slice did not change manifest shape, schemas, validator behavior, CLI commands, npm exports, Studio, Cloud, PRDc, AI, account/library, payment, crypto, rights, or broad conversion behavior. + ## 2026-06-05 - Synced local `main` after PR `#43` (`[stannesi] add public viewer demo ux`) merged, then created `thehive/prd-landing-viewer-dashboard` for the hosted landing/viewer refresh. -- Refreshed `apps/prd-viewer-web` into one deployable PRD landing page plus reference web viewer workspace with premium dark mode by default, first-class light mode, persistent theme selection, and a dashboard-style viewer surface inspired by the provided references. -- Revised the hosted app route structure so `/` is the product landing page and `/viewer/` is the actual PRD Web Viewer workspace, including base-path support for GitHub Pages at `/prd/`. +- Refreshed `apps/prd-viewer-web` into one deployable PRD Home page plus reference web viewer workspace with premium dark mode by default, first-class light mode, persistent theme selection, and a dashboard-style viewer surface inspired by the provided references. +- Revised the hosted app route structure so `/` is the Home page and `/viewer/` is the actual PRD Web Viewer workspace, including base-path support for GitHub Pages at `/prd/`. - Added real package-derived outline panels for structured `general-document`, `comic`, and `storyboard` content rather than static/fake dashboard navigation. - Added hosted sample archive support through generated demo assets under the ignored `apps/prd-viewer-web/public/examples/` path. Hosted samples load through the same eager whole-package in-memory open path as user-selected archives and do not change PRD format loading semantics. - Added `scripts/prepare-viewer-demo-assets.mjs`, root `pnpm viewer:demo:assets`, `pnpm viewer:demo:build`, and `pnpm viewer:demo:dev` so canonical examples can be packed and copied into the web viewer demo surface without committing `.prd` binaries. diff --git a/NEXT_STEPS.md b/NEXT_STEPS.md index 2c9c2b2..bd5c20c 100644 --- a/NEXT_STEPS.md +++ b/NEXT_STEPS.md @@ -47,6 +47,8 @@ 38. [x] After the scaffold slice is real, draft the Phase 5 authoring workflow and import/export matrix so Markdown, HTML, DOCX, EPUB, and PDF conversion work is sequenced intentionally rather than bundled into the first authoring command. 39. [x] Implement the first real import lane: `prd import markdown ./source.md --out ./my-document`, targeting structured `general-document` package directories with deterministic validation-friendly output. 40. [x] Implemented the next small visual-profile import lane: `prd import images ./pages --profile --out ./package`, producing validator-valid ordered image packages without broad conversion, Studio, Cloud, PRDc, payment, crypto, rights, or visual-editor scope. -41. [x] Implemented a public demo/viewer/landing UX slice inside `apps/prd-viewer-web` that demonstrates the real `prd init/import -> validate -> inspect -> pack -> open` flow now that text and visual import lanes exist. -42. [x] Chose and implemented a public hosted demo/deployment path for the reference viewer using a single `apps/prd-viewer-web` app with separate `/` landing and `/viewer/` workspace routes, generated hosted sample archives, light/dark theme support, and a GitHub Pages workflow. -43. [ ] After the hosted demo PR lands, run launch QA against the live GitHub Pages URL, verify `/prd/`, `/prd/viewer/`, hosted samples, theme persistence, and manual `.prd` upload, then choose the next focused viewer/product polish step. +41. [x] Implemented a public Home/viewer demo UX slice inside `apps/prd-viewer-web` that demonstrates the real `prd init/import -> validate -> inspect -> pack -> open` flow now that text and visual import lanes exist. +42. [x] Chose and implemented a public hosted demo/deployment path for the reference viewer using a single `apps/prd-viewer-web` app with separate `/` Home and `/viewer/` workspace routes, generated hosted sample archives, light/dark theme support, and a GitHub Pages workflow. +43. [x] Merged PR `#46`, renamed user-facing “Landing” language to Home, added `/docs/` as the public docs index inside the hosted app, and documented Cloudflare Pages as the intended production host for `prd.eonhive.com` with GitHub Pages retained as staging/fallback. +44. [ ] Run public launch QA for the Cloudflare production path: verify `https://prd.eonhive.com/`, `/viewer/`, `/docs/`, hosted sample archives, route refresh behavior, theme persistence, mobile layout, and manual `.prd` upload. Keep GitHub Pages as fallback until this passes. +45. [ ] After Cloudflare launch QA passes, choose the next focused product polish slice: likely Home/Web Viewer UI cleanup toward a more Adobe-style document product page, while still avoiding accounts, pricing, AI assistant, Studio, Cloud, PRDc, payments, crypto, rights, and broad conversion scope. diff --git a/README.md b/README.md index cb7ba8d..7f4e342 100644 --- a/README.md +++ b/README.md @@ -76,6 +76,7 @@ Use these focused paths from there: * `docs/decisions/PRD_DECISIONS.md` * `docs/governance/PRD_PROFILE_REGISTRY.md` * `docs/governance/PRD_RELEASE_POLICY.md` + * `docs/governance/PRD_HOSTING_RUNBOOK.md` * product boundaries * `docs/product/PRD_PRODUCT_BOUNDARIES.md` * `docs/product/PRD_AUTHORING_WORKFLOW.md` @@ -317,7 +318,9 @@ pnpm viewer:demo:dev `viewer:demo:assets` packs canonical examples and copies selected `.prd` archives into the web viewer's ignored `public/examples/` directory for the hosted demo. Those hosted samples are demo assets only; they do not change PRD's packaged-first loading contract. -The hosted app has two public routes in one deployable Vite build: `/` is the PRD landing page and `/viewer/` is the reference Web Viewer workspace. Under GitHub Pages those routes are served beneath the configured `/prd/` base path. +The hosted app has three public routes in one deployable Vite build: `/` is Home, `/viewer/` is the reference Web Viewer workspace, and `/docs/` is the public docs index. The intended production host is Cloudflare Pages at `prd.eonhive.com`; GitHub Pages remains the temporary staging/fallback path served beneath the configured `/prd/` base path. Hosting operations are tracked in `docs/governance/PRD_HOSTING_RUNBOOK.md`. + +The public `/docs/` route is a user-friendly navigation layer over canonical repo docs. It does not replace `docs/`, and it intentionally does not link the tracked `codex/` operational planning files. ## Contributor MVP gate (no npm credentials required) @@ -484,7 +487,7 @@ The repo also now includes [`.github/workflows/codex-ci.yml`](/Users/nappy.cat/L For release automation, the repo also includes [`.github/workflows/release.yml`](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/.github/workflows/release.yml), which gates npm publication through Changesets and CI on `main`. -The hosted PRD Web Viewer demo is built and deployed by [`.github/workflows/viewer-demo-pages.yml`](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/.github/workflows/viewer-demo-pages.yml) using GitHub Pages. The workflow builds with `PRD_VIEWER_BASE_PATH=/prd/` and deploys `apps/prd-viewer-web/dist`, with `/prd/` as the landing route and `/prd/viewer/` as the viewer workspace route. +The hosted PRD Web Viewer demo is currently built and deployed by [`.github/workflows/viewer-demo-pages.yml`](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/.github/workflows/viewer-demo-pages.yml) using GitHub Pages as staging/fallback. The workflow builds with `PRD_VIEWER_BASE_PATH=/prd/` and deploys `apps/prd-viewer-web/dist`, with `/prd/` as Home, `/prd/viewer/` as the viewer workspace route, and `/prd/docs/` as the public docs index. Production is intended to move to Cloudflare Pages at `prd.eonhive.com` after launch QA. The app includes a Cloudflare Pages `_redirects` fallback, and the GitHub Pages workflow copies `index.html` to `404.html` for SPA route refresh support. --- @@ -492,9 +495,10 @@ The hosted PRD Web Viewer demo is built and deployed by [`.github/workflows/view 1. Run `pnpm codex:check` 2. Run `pnpm viewer:demo:dev` -3. Open the PRD landing page at `/` and use either light or premium dark mode +3. Open PRD Home at `/` and use either light or premium dark mode 4. Open the viewer workspace at `/viewer/`, then load a hosted sample archive or choose/drag a `.prd` archive into the viewer drop zone -5. Confirm package status, package facts, manifest metadata, localization/attachments, and rendered content in the reference viewer +5. Open the public docs index at `/docs/` +6. Confirm package status, package facts, manifest metadata, localization/attachments, and rendered content in the reference viewer Current example behavior: diff --git a/apps/prd-viewer-web/public/_redirects b/apps/prd-viewer-web/public/_redirects new file mode 100644 index 0000000..7797f7c --- /dev/null +++ b/apps/prd-viewer-web/public/_redirects @@ -0,0 +1 @@ +/* /index.html 200 diff --git a/apps/prd-viewer-web/src/App.tsx b/apps/prd-viewer-web/src/App.tsx index 4ef4893..fd59785 100644 --- a/apps/prd-viewer-web/src/App.tsx +++ b/apps/prd-viewer-web/src/App.tsx @@ -51,7 +51,10 @@ import { viewerFutureLanes, viewerLandingCapabilities, viewerLandingHero, - viewerLandingProfiles + viewerLandingProfiles, + viewerPublicDocsIntro, + viewerPublicDocsSections, + viewerPublicHostingNotes } from "./viewerDemoContent.js"; import { findFirstPrdArchive, @@ -121,6 +124,7 @@ const viewerThemeStorageKey = "prd-viewer-theme"; const viewerAppBasePath = ((import.meta as ImportMeta & { env?: { BASE_URL?: string } }).env?.BASE_URL ?? "/"); +const canonicalDocsRepositoryUrl = "https://github.com/eonhive/prd/blob/main/"; function formatReferenceLoadMode(loadMode: PrdReferenceLoadMode): string { if (loadMode === "eager-whole-package") { @@ -144,6 +148,22 @@ function formatReferenceViewerSupportStateSummary(): string { return referenceViewerRuntimeDescriptor.supportStates.join(", "); } +function getPublicDocsLinkHref(href: string): string { + if (href === "/" || href === "/viewer/") { + return href; + } + + if (href === "examples/") { + return "https://github.com/eonhive/prd/tree/main/examples"; + } + + if (href.startsWith("http://") || href.startsWith("https://")) { + return href; + } + + return `${canonicalDocsRepositoryUrl}${href}`; +} + function createPackageReader(files: PrdFileMap): PrdPackageReader { return { has(path) { @@ -2158,8 +2178,8 @@ function AppNavigation({ - + - Docs
@@ -2197,7 +2223,7 @@ function AppNavigation({ ); } -function LandingSurface({ +function HomeSurface({ onOpenViewer, onLoadSample, sampleLoadingId, @@ -2209,7 +2235,7 @@ function LandingSurface({ onLoadArchive: (example: ViewerDemoExampleArchive) => void; }) { return ( -
+
0.1.1 public preview @@ -2395,6 +2421,137 @@ function ViewerExampleGuideView({ ); } +function PublicDocsSurface({ + onNavigate +}: { + onNavigate: (route: ViewerAppRoute, hash?: string) => void; +}) { + return ( +
+
+
+

{viewerPublicDocsIntro.eyebrow}

+

{viewerPublicDocsIntro.title}

+

{viewerPublicDocsIntro.description}

+
+ + +
+
+ +
+ +
+ {viewerPublicDocsSections.map((section) => ( +
+

{section.id}

+

{section.title}

+

{section.summary}

+ +
    + {section.links.map((link) => ( +
  • + +
    • + ))} +
+
+ ))} +
+ +
+

+ Canonical docs remain in the repository under docs/. This + page is the public docs index for users and implementers; Codex + planning and session handoff files stay tracked for workflow + continuity, but they are not linked from public navigation. +

+
+
+ ); +} + +function DocsLink({ + link, + className, + onNavigate +}: { + link: { label: string; href: string }; + className?: string; + onNavigate: (route: ViewerAppRoute, hash?: string) => void; +}) { + if (link.href === "/") { + return ( + { + event.preventDefault(); + onNavigate("home"); + }} + > + {link.label} + + ); + } + + if (link.href === "/viewer/") { + return ( + { + event.preventDefault(); + onNavigate("viewer"); + }} + > + {link.label} + + ); + } + + return ( + + {link.label} + + ); +} + function ViewerDocumentOutlineView({ items }: { @@ -3176,8 +3333,8 @@ export function App() { }} /> - {route === "landing" ? ( - navigateToRoute("viewer")} onLoadSample={() => { const firstSample = viewerDemoExampleArchives[0]; @@ -3188,6 +3345,8 @@ export function App() { onLoadArchive={(example) => void handleSampleArchive(example)} sampleLoadingId={sampleLoadingId} /> + ) : route === "docs" ? ( + ) : ( { - it("describes the landing page without inventing unavailable product behavior", () => { + it("describes the Home page without inventing unavailable product behavior", () => { expect(viewerLandingHero.title).toContain("Create"); expect(viewerLandingHero.description).toContain("Portable Responsive Document"); expect(viewerLandingHero.primaryAction).toBe("Open Viewer"); @@ -49,6 +52,43 @@ describe("viewer demo content", () => { expect(viewerLandingProfiles[2]?.command).toContain("--profile storyboard"); }); + it("publishes a public docs navigation layer without linking Codex workflow docs", () => { + expect(viewerPublicDocsIntro.title).toContain("Start"); + expect(viewerPublicDocsSections.map((section) => section.title)).toEqual([ + "Home", + "Getting Started", + "CLI", + "Format", + "Profiles", + "Examples", + "Viewer", + "Conformance", + "Release/Operator Notes" + ]); + const allPublicDocsHrefs = viewerPublicDocsSections.flatMap((section) => [ + section.primaryLink.href, + ...section.links.map((link) => link.href) + ]); + expect(allPublicDocsHrefs).toEqual( + expect.arrayContaining([ + "/", + "/viewer/", + "docs/product/PRD_AUTHORING_WORKFLOW.md", + "docs/core/PRD_MINIMAL_VALID_SPEC.md", + "docs/governance/PRD_HOSTING_RUNBOOK.md" + ]) + ); + expect(allPublicDocsHrefs.every((href) => !href.startsWith("codex/"))).toBe(true); + }); + + it("locks Cloudflare production and GitHub Pages staging hosting copy", () => { + expect(viewerPublicHostingNotes.map((note) => note.value)).toEqual( + expect.arrayContaining(["Cloudflare Pages", "GitHub Pages", "/, /viewer/, /docs/"]) + ); + expect(viewerPublicHostingNotes[0]?.description).toContain("prd.eonhive.com"); + expect(viewerPublicHostingNotes[1]?.description).toContain("/prd/"); + }); + it("describes the create/import to open public product flow", () => { expect(viewerDemoFlowSteps.map((step) => step.title)).toEqual([ "Create or import", diff --git a/apps/prd-viewer-web/src/viewerDemoContent.ts b/apps/prd-viewer-web/src/viewerDemoContent.ts index 5d99d47..af7ff15 100644 --- a/apps/prd-viewer-web/src/viewerDemoContent.ts +++ b/apps/prd-viewer-web/src/viewerDemoContent.ts @@ -1,10 +1,10 @@ /* * Company: EonHive Inc. * Title: PRD Viewer Demo Content - * Purpose: Keep public viewer demo copy and command examples stable and testable. + * Purpose: Keep public site, docs, and viewer demo copy stable and testable. * Author: Stan Nesi * Created: June 2, 2026 - * Updated: June 5, 2026 + * Updated: June 7, 2026 * Notes: Vibe coded with Codex. */ @@ -21,6 +21,25 @@ export interface ViewerLandingProfile { command: string; } +export interface ViewerPublicDocsLink { + label: string; + href: string; +} + +export interface ViewerPublicDocsSection { + id: string; + title: string; + summary: string; + primaryLink: ViewerPublicDocsLink; + links: ViewerPublicDocsLink[]; +} + +export interface ViewerPublicHostingNote { + label: string; + value: string; + description: string; +} + export interface ViewerDemoFlowStep { label: string; title: string; @@ -47,6 +66,138 @@ export const viewerLandingHero = { tertiaryAction: "View CLI Flow" }; +export const viewerPublicDocsIntro = { + eyebrow: "Public docs", + title: "Start with the product path, then go deeper into canon.", + description: + "This docs page is a public navigation layer over the canonical repository docs. It keeps users oriented around Home, authoring, CLI tooling, format basics, profiles, examples, the viewer, conformance, and release/operator notes without exposing internal Codex workflow docs as product documentation." +}; + +export const viewerPublicDocsSections: ViewerPublicDocsSection[] = [ + { + id: "home", + title: "Home", + summary: + "The public product overview for PRD: what ships now, what is deferred, and how the create/import to open loop works.", + primaryLink: { label: "Open Home", href: "/" }, + links: [ + { label: "Product boundaries", href: "docs/product/PRD_PRODUCT_BOUNDARIES.md" }, + { label: "Roadmap", href: "docs/foundation/04_PRD/PRD_ROADMAP.md" } + ] + }, + { + id: "getting-started", + title: "Getting Started", + summary: + "Install the public CLI, create or import a package, validate it, inspect package facts, pack it, and open it in the reference viewer.", + primaryLink: { label: "Authoring workflow", href: "docs/product/PRD_AUTHORING_WORKFLOW.md" }, + links: [ + { label: "Root quickstart", href: "README.md" }, + { label: "Import/export matrix", href: "docs/product/PRD_IMPORT_EXPORT_MATRIX.md" } + ] + }, + { + id: "cli", + title: "CLI", + summary: + "Command contracts for `prd init`, imports, validation, inspection, packing, text output, JSON output, and exit codes.", + primaryLink: { label: "CLI README", href: "packages/prd-cli/README.md" }, + links: [ + { label: "CLI JSON contract", href: "docs/runtime/PRD_CLI_JSON_CONTRACT.md" }, + { label: "npm release policy", href: "docs/governance/PRD_RELEASE_POLICY.md" } + ] + }, + { + id: "format", + title: "Format", + summary: + "Manifest-first package rules, minimal valid PRD requirements, package layout, versioning, localization, assets, attachments, and loading truth.", + primaryLink: { label: "Minimal valid spec", href: "docs/core/PRD_MINIMAL_VALID_SPEC.md" }, + links: [ + { label: "Manifest draft", href: "docs/core/PRD_MANIFEST_DRAFT.md" }, + { label: "Package layout", href: "docs/core/PRD_PACKAGE_LAYOUT_DRAFT.md" }, + { label: "Performance and loading", href: "docs/core/PRD_PERFORMANCE_AND_LOADING.md" } + ] + }, + { + id: "profiles", + title: "Profiles", + summary: + "Current first-class profiles are `general-document`, `comic`, and `storyboard`. Other document kinds stay inside those families unless canon promotes them later.", + primaryLink: { label: "Profile registry", href: "docs/governance/PRD_PROFILE_REGISTRY.md" }, + links: [ + { label: "General document", href: "docs/profiles/PRD_PROFILE_GENERAL_DOCUMENT.md" }, + { label: "Comic", href: "docs/profiles/PRD_PROFILE_COMIC.md" }, + { label: "Storyboard", href: "docs/profiles/PRD_PROFILE_STORYBOARD.md" } + ] + }, + { + id: "examples", + title: "Examples", + summary: + "Canonical example packages prove validation, packaging, import lanes, hosted samples, and viewer behavior without committing generated `.prd` binaries.", + primaryLink: { label: "Example packages", href: "examples/" }, + links: [ + { label: "Runtime conformance corpus", href: "examples/runtime-conformance/runtime-conformance-manifest.json" }, + { label: "Pack examples", href: "README.md#example-flow" } + ] + }, + { + id: "viewer", + title: "Viewer", + summary: + "The reference Web Viewer validates first, reports real package facts, and opens supported packages through eager whole-package in-memory loading.", + primaryLink: { label: "Open Viewer", href: "/viewer/" }, + links: [ + { label: "Runtime capabilities", href: "docs/runtime/PRD_CAPABILITY_MODEL.md" }, + { label: "Runtime conformance", href: "docs/runtime/PRD_CONFORMANCE.md" } + ] + }, + { + id: "conformance", + title: "Conformance", + summary: + "Executable foundation and runtime checks define the current reference baseline for package validity, support states, and fixture expectations.", + primaryLink: { label: "Runtime conformance", href: "docs/runtime/PRD_CONFORMANCE.md" }, + links: [ + { label: "Minimal valid spec", href: "docs/core/PRD_MINIMAL_VALID_SPEC.md" }, + { label: "Foundation gate", href: "README.md#foundation-gate" } + ] + }, + { + id: "release-operator-notes", + title: "Release/Operator Notes", + summary: + "Maintainer-facing release, npm verification, and hosting runbooks for operating the public preview without mixing those notes into user-facing product docs.", + primaryLink: { label: "Release policy", href: "docs/governance/PRD_RELEASE_POLICY.md" }, + links: [ + { label: "npm runbook", href: "docs/governance/PRD_NPM_RELEASE_RUNBOOK.md" }, + { label: "Hosting runbook", href: "docs/governance/PRD_HOSTING_RUNBOOK.md" } + ] + } +]; + +export const viewerPublicHostingNotes: ViewerPublicHostingNote[] = [ + { + label: "Production", + value: "Cloudflare Pages", + description: + "`prd.eonhive.com` is the intended production host after custom-domain setup and launch QA." + }, + { + label: "Staging/fallback", + value: "GitHub Pages", + description: + "GitHub Pages remains the temporary staging and fallback deployment using the `/prd/` base path." + }, + { + label: "Routes", + value: "/, /viewer/, /docs/", + description: + "`/` is Home, `/viewer/` is the Web Viewer workspace, and `/docs/` is the public docs index." + } +]; + export const viewerLandingCapabilities: ViewerLandingCapability[] = [ { title: "Manifest-first core", diff --git a/apps/prd-viewer-web/src/viewerRoutes.test.ts b/apps/prd-viewer-web/src/viewerRoutes.test.ts index 0846d05..a06ec5f 100644 --- a/apps/prd-viewer-web/src/viewerRoutes.test.ts +++ b/apps/prd-viewer-web/src/viewerRoutes.test.ts @@ -1,10 +1,10 @@ /* * Company: EonHive Inc. * Title: PRD Viewer Route Tests - * Purpose: Verify landing/viewer route behavior under local and hosted base paths. + * Purpose: Verify Home/docs/viewer route behavior under local and hosted base paths. * Author: Stan Nesi * Created: June 5, 2026 - * Updated: June 5, 2026 + * Updated: June 7, 2026 * Notes: Vibe coded with Codex. */ @@ -24,24 +24,29 @@ describe("viewer routes", () => { expect(normalizeViewerBasePath("/prd/")).toBe("/prd/"); }); - it("resolves landing and viewer routes locally", () => { - expect(getViewerAppRouteFromPath("/", "/")).toBe("landing"); + it("resolves Home, docs, and viewer routes locally", () => { + expect(getViewerAppRouteFromPath("/", "/")).toBe("home"); + expect(getViewerAppRouteFromPath("/docs", "/")).toBe("docs"); + expect(getViewerAppRouteFromPath("/docs/", "/")).toBe("docs"); expect(getViewerAppRouteFromPath("/viewer", "/")).toBe("viewer"); expect(getViewerAppRouteFromPath("/viewer/", "/")).toBe("viewer"); - expect(getViewerAppRouteFromPath("/anything-else", "/")).toBe("landing"); + expect(getViewerAppRouteFromPath("/anything-else", "/")).toBe("home"); }); - it("resolves landing and viewer routes under GitHub Pages base path", () => { - expect(getViewerAppRouteFromPath("/prd/", "/prd/")).toBe("landing"); + it("resolves Home, docs, and viewer routes under hosted base path", () => { + expect(getViewerAppRouteFromPath("/prd/", "/prd/")).toBe("home"); + expect(getViewerAppRouteFromPath("/prd/docs", "/prd/")).toBe("docs"); + expect(getViewerAppRouteFromPath("/prd/docs/", "/prd/")).toBe("docs"); expect(getViewerAppRouteFromPath("/prd/viewer", "/prd/")).toBe("viewer"); expect(getViewerAppRouteFromPath("/prd/viewer/", "/prd/")).toBe("viewer"); }); it("builds stable route paths for local and hosted deployment", () => { - expect(getViewerAppRoutePath("landing", "/")).toBe("/"); + expect(getViewerAppRoutePath("home", "/")).toBe("/"); + expect(getViewerAppRoutePath("docs", "/")).toBe("/docs/"); expect(getViewerAppRoutePath("viewer", "/")).toBe("/viewer/"); - expect(getViewerAppRoutePath("landing", "/prd/")).toBe("/prd/"); + expect(getViewerAppRoutePath("home", "/prd/")).toBe("/prd/"); + expect(getViewerAppRoutePath("docs", "/prd/")).toBe("/prd/docs/"); expect(getViewerAppRoutePath("viewer", "/prd/")).toBe("/prd/viewer/"); }); }); - diff --git a/apps/prd-viewer-web/src/viewerRoutes.ts b/apps/prd-viewer-web/src/viewerRoutes.ts index e75e042..48d11b4 100644 --- a/apps/prd-viewer-web/src/viewerRoutes.ts +++ b/apps/prd-viewer-web/src/viewerRoutes.ts @@ -1,14 +1,14 @@ /* * Company: EonHive Inc. * Title: PRD Viewer Routes - * Purpose: Keep hosted landing/viewer route behavior stable under local and GitHub Pages base paths. + * Purpose: Keep hosted Home/docs/viewer route behavior stable under local and hosted base paths. * Author: Stan Nesi * Created: June 5, 2026 - * Updated: June 5, 2026 + * Updated: June 7, 2026 * Notes: Vibe coded with Codex. */ -export type ViewerAppRoute = "landing" | "viewer"; +export type ViewerAppRoute = "home" | "viewer" | "docs"; export function normalizeViewerBasePath(basePath: string): string { const trimmed = basePath.trim(); @@ -33,9 +33,15 @@ export function getViewerAppRouteFromPath( ? normalizedPath.slice(normalizedBase.length) : normalizedPath.replace(/^\/+/, ""); - return routePath === "viewer" || routePath.startsWith("viewer/") - ? "viewer" - : "landing"; + if (routePath === "viewer" || routePath.startsWith("viewer/")) { + return "viewer"; + } + + if (routePath === "docs" || routePath.startsWith("docs/")) { + return "docs"; + } + + return "home"; } export function getViewerAppRoutePath( @@ -43,6 +49,13 @@ export function getViewerAppRoutePath( basePath: string ): string { const normalizedBase = normalizeViewerBasePath(basePath); - return route === "viewer" ? `${normalizedBase}viewer/` : normalizedBase; -} + if (route === "viewer") { + return `${normalizedBase}viewer/`; + } + + if (route === "docs") { + return `${normalizedBase}docs/`; + } + return normalizedBase; +} diff --git a/codex/SESSION_HANDOFF.md b/codex/SESSION_HANDOFF.md index e7ace4e..73af110 100644 --- a/codex/SESSION_HANDOFF.md +++ b/codex/SESSION_HANDOFF.md @@ -2,148 +2,116 @@ ## Current status -- PR `#43` (`[stannesi] add public viewer demo ux`) is merged into `main` at `2f3e2221a70fcc13a843b9e0db204d0ca22b0b8a`. -- Local `main` was fast-forwarded to `origin/main`. -- Current branch is `thehive/prd-landing-viewer-route-split`, based on current `origin/main`. -- This branch implements `NEXT_STEPS.md` item `42`: hosted PRD landing page plus reference web viewer demo/deployment path. -- PR `#44` (`[stannesi] add hosted landing and viewer dashboard`) was merged while the route-split revision was being implemented. -- PR `#45` was opened from the pre-squash PR `#44` branch and then closed because it included already-merged files in the comparison. -- Clean PR `#46` (`[stannesi] separate hosted landing and viewer routes`) is open: https://github.com/eonhive/prd/pull/46. -- Scope remains one deployable app under `apps/prd-viewer-web`. -- After design review, the app was revised so `/` is the product landing page and `/viewer/` is the actual PRD Web Viewer workspace. Under GitHub Pages those become `/prd/` and `/prd/viewer/`. -- No manifest, schema, validator, CLI command, package export, npm package, Studio, Cloud, PRDc, AI assistant, account/library, payment, crypto, rights, universal viewer, or broad conversion behavior was added. -- No changeset was added. +- PR `#46` (`[stannesi] separate hosted landing and viewer routes`) was merged into `main`. +- Local `main` was synced, then branch `thehive/prd-public-site-docs-hosting` was created. +- Current branch implements the public site/docs/hosting polish lane. +- The hosted app still lives in one deployable Vite app: `apps/prd-viewer-web`. +- Public app routes are now `/` = Home, `/viewer/` = PRD Web Viewer, and `/docs/` = public docs index. +- Cloudflare Pages at `prd.eonhive.com` is documented as the intended production host. +- GitHub Pages remains staging/fallback under `/prd/` until Cloudflare launch QA passes. ## Completed work -- Added a premium dark/light PRD landing page and viewer workspace inside the existing web viewer app. -- Separated landing and viewer into route-level surfaces using a small no-dependency route helper. -- Added persistent theme selection with dark mode as the default. -- Added landing content for the real public loop: `prd init/import -> validate -> inspect -> pack -> open`. -- Added dashboard-style viewer chrome while preserving the existing validator-first archive open path and renderer behavior. -- Added package-derived document outline rows for structured `general-document`, `comic`, and `storyboard` packages. -- Added hosted sample archive loading for generated examples. Hosted samples load through the same eager whole-package in-memory open path as user-selected `.prd` archives. -- Added `apps/prd-viewer-web/src/viewerArchiveFiles.ts` and tests for `.prd` archive selection and hosted sample URL behavior. -- Added `apps/prd-viewer-web/src/viewerRoutes.ts` and tests for local/GitHub Pages route mapping. -- Added `apps/prd-viewer-web/src/viewerDocumentOutline.ts` and tests for package-derived outline rows. -- Expanded `apps/prd-viewer-web/src/viewerDemoContent.ts` and tests for landing capabilities, profile cards, command copy, sample archive labels, and future-lane disclaimers. -- Added `scripts/prepare-viewer-demo-assets.mjs` and tests to copy generated `.prd` archives from `examples/dist` into ignored `apps/prd-viewer-web/public/examples/`. -- Added root scripts: `viewer:demo:assets`, `viewer:demo:build`, and `viewer:demo:dev`. -- Added `.github/workflows/viewer-demo-pages.yml` for GitHub Pages deployment using `PRD_VIEWER_BASE_PATH=/prd/`. -- Updated README, docs index, product-boundary docs, authoring workflow, import/export matrix, roadmap, build status, and backlog state. -- Marked `NEXT_STEPS.md` item `42` complete and added item `43` for hosted-demo launch QA. +- Renamed user-facing hosted-app navigation from “Landing” to “Home” while keeping route `/`. +- Added `/docs/` to the app route helper and browser app shell. +- Added an in-app public docs index for Home, Getting Started, CLI, Format, Profiles, Examples, Viewer, Conformance, and Release/Operator Notes. +- Kept public docs as a navigation layer over canonical repo docs rather than copying or replacing `docs/`. +- Ensured public docs do not link tracked `codex/` planning or handoff files. +- Added Cloudflare/GitHub Pages hosting notes to the public docs surface. +- Added Cloudflare Pages `_redirects` SPA fallback for `/viewer/` and `/docs/` refreshes. +- Added GitHub Pages `404.html` fallback generation in the Pages workflow. +- Added `docs/governance/PRD_HOSTING_RUNBOOK.md`. +- Updated README, docs index, product docs, roadmap, build status, and backlog state. +- Marked `NEXT_STEPS.md` item `43` complete and added next launch-QA/polish items. ## In-progress work -- Implementation and validation are complete locally. -- PR `#46` is open and ready for normal GitHub validation/review. +- No code work is currently in progress. +- Branch is ready for commit/push/PR after final review. ## Changed files -- [.gitignore](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/.gitignore) -- [viewer-demo-pages.yml](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/.github/workflows/viewer-demo-pages.yml) -- [package.json](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/package.json) -- [App.tsx](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/apps/prd-viewer-web/src/App.tsx) -- [styles.css](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/apps/prd-viewer-web/src/styles.css) -- [viewerArchiveFiles.ts](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/apps/prd-viewer-web/src/viewerArchiveFiles.ts) -- [viewerArchiveFiles.test.ts](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/apps/prd-viewer-web/src/viewerArchiveFiles.test.ts) -- [viewerDocumentOutline.ts](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/apps/prd-viewer-web/src/viewerDocumentOutline.ts) -- [viewerDocumentOutline.test.ts](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/apps/prd-viewer-web/src/viewerDocumentOutline.test.ts) -- [viewerDemoContent.ts](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/apps/prd-viewer-web/src/viewerDemoContent.ts) -- [viewerDemoContent.test.ts](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/apps/prd-viewer-web/src/viewerDemoContent.test.ts) -- [viewerRoutes.ts](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/apps/prd-viewer-web/src/viewerRoutes.ts) -- [viewerRoutes.test.ts](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/apps/prd-viewer-web/src/viewerRoutes.test.ts) -- [vite.config.ts](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/apps/prd-viewer-web/vite.config.ts) -- [prepare-viewer-demo-assets.mjs](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/scripts/prepare-viewer-demo-assets.mjs) -- [prepare-viewer-demo-assets.test.ts](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/scripts/prepare-viewer-demo-assets.test.ts) -- [README.md](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/README.md) -- [docs/README.md](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/docs/README.md) -- [PRD_PRODUCT_BOUNDARIES.md](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/docs/product/PRD_PRODUCT_BOUNDARIES.md) -- [PRD_AUTHORING_WORKFLOW.md](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/docs/product/PRD_AUTHORING_WORKFLOW.md) -- [PRD_IMPORT_EXPORT_MATRIX.md](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/docs/product/PRD_IMPORT_EXPORT_MATRIX.md) -- [PRD_ROADMAP.md](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/docs/foundation/04_PRD/PRD_ROADMAP.md) -- [BUILD_STATUS.md](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/BUILD_STATUS.md) -- [NEXT_STEPS.md](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/NEXT_STEPS.md) -- [SESSION_HANDOFF.md](/Users/nappy.cat/Labs/eonHive.lab/prd.lab/prd/codex/SESSION_HANDOFF.md) +- `BUILD_STATUS.md` +- `NEXT_STEPS.md` +- `README.md` +- `.github/workflows/viewer-demo-pages.yml` +- `apps/prd-viewer-web/public/_redirects` +- `apps/prd-viewer-web/src/App.tsx` +- `apps/prd-viewer-web/src/styles.css` +- `apps/prd-viewer-web/src/viewerDemoContent.ts` +- `apps/prd-viewer-web/src/viewerDemoContent.test.ts` +- `apps/prd-viewer-web/src/viewerRoutes.ts` +- `apps/prd-viewer-web/src/viewerRoutes.test.ts` +- `docs/README.md` +- `docs/foundation/04_PRD/PRD_ROADMAP.md` +- `docs/governance/PRD_HOSTING_RUNBOOK.md` +- `docs/product/PRD_AUTHORING_WORKFLOW.md` +- `docs/product/PRD_IMPORT_EXPORT_MATRIX.md` +- `docs/product/PRD_PRODUCT_BOUNDARIES.md` +- `codex/SESSION_HANDOFF.md` ## Commands run - `git status --short --branch` +- GitHub connector: inspected and merged PR `#46` - `git fetch origin main` - `git switch main` - `git pull --ff-only origin main` -- `git switch -c thehive/prd-landing-viewer-dashboard` -- `git switch -c thehive/prd-landing-viewer-route-split origin/main` -- `git cherry-pick 7210e667fe88b79f02f769c7288eb26827de4512` +- `git switch -c thehive/prd-public-site-docs-hosting` - `PATH="/opt/homebrew/bin:$PATH" node_modules/.bin/tsc -b apps/prd-viewer-web/tsconfig.json --pretty false` -- `PATH="/opt/homebrew/bin:$PATH" pnpm exec vitest run apps/prd-viewer-web/src/viewerDemoContent.test.ts apps/prd-viewer-web/src/viewerArchiveFiles.test.ts scripts/prepare-viewer-demo-assets.test.ts` -- `PATH="/opt/homebrew/bin:$PATH" pnpm exec vitest run apps/prd-viewer-web/src/viewerDemoContent.test.ts apps/prd-viewer-web/src/viewerArchiveFiles.test.ts scripts/prepare-viewer-demo-assets.test.ts apps/prd-viewer-web/src/viewerRenderMode.test.ts apps/prd-viewer-web/src/viewerRenderMode.integration.test.ts` -- `PATH="/opt/homebrew/bin:$PATH" pnpm exec vitest run apps/prd-viewer-web/src/viewerRoutes.test.ts apps/prd-viewer-web/src/viewerDocumentOutline.test.ts apps/prd-viewer-web/src/viewerDemoContent.test.ts apps/prd-viewer-web/src/viewerArchiveFiles.test.ts scripts/prepare-viewer-demo-assets.test.ts apps/prd-viewer-web/src/viewerRenderMode.test.ts apps/prd-viewer-web/src/viewerRenderMode.integration.test.ts` -- `PATH="/opt/homebrew/bin:$PATH" pnpm viewer:demo:build` +- `PATH="/opt/homebrew/bin:$PATH" pnpm exec vitest run apps/prd-viewer-web/src/viewerRoutes.test.ts apps/prd-viewer-web/src/viewerDemoContent.test.ts apps/prd-viewer-web/src/viewerArchiveFiles.test.ts apps/prd-viewer-web/src/viewerDocumentOutline.test.ts apps/prd-viewer-web/src/viewerRenderMode.test.ts apps/prd-viewer-web/src/viewerRenderMode.integration.test.ts` - `PATH="/opt/homebrew/bin:$PATH" pnpm docs:check -- --include-root-docs` - `git diff --check` -- `PATH="/opt/homebrew/bin:$PATH" pnpm typecheck` +- `PATH="/opt/homebrew/bin:$PATH" pnpm viewer:demo:build` - `PATH="/opt/homebrew/bin:$PATH" pnpm viewer:demo:dev -- --host 127.0.0.1 --port 5173` - Browser verification at `http://localhost:5173/` - Browser verification at `http://localhost:5173/viewer/` +- Browser verification at `http://localhost:5173/docs/` - `PATH="/opt/homebrew/bin:$PATH" pnpm foundation:gate` -- `git add ...` -- `git commit -m "feat: add hosted landing and viewer dashboard"` -- `git push -u origin thehive/prd-landing-viewer-dashboard` -- GitHub connector: opened PR `#44` -- `git push -u origin thehive/prd-landing-viewer-route-split` -- GitHub connector: opened clean PR `#46` -- GitHub connector: commented on and closed duplicate PR `#45` ## Tests / verification -- `PATH="/opt/homebrew/bin:$PATH" node_modules/.bin/tsc -b apps/prd-viewer-web/tsconfig.json --pretty false` passed. -- Targeted viewer/script tests passed after route revision: 7 files, 25 tests. -- `PATH="/opt/homebrew/bin:$PATH" pnpm viewer:demo:build` passed and generated ignored hosted sample archives. -- `PATH="/opt/homebrew/bin:$PATH" pnpm docs:check -- --include-root-docs` passed. +- Viewer route/content/render targeted tests passed: 6 files, 24 tests. +- `apps/prd-viewer-web` TypeScript build passed. +- `pnpm docs:check -- --include-root-docs` passed. - `git diff --check` passed. -- `PATH="/opt/homebrew/bin:$PATH" pnpm typecheck` passed. -- `PATH="/opt/homebrew/bin:$PATH" pnpm foundation:gate` passed: 18 test files, 177 tests, docs consistency, example validation, and aggregate example smoke. -- Browser desktop verification passed for: - - `/` premium dark landing surface - - `/viewer/` separate viewer workspace route - - light mode toggle and theme DOM state - - hosted sample buttons - - dashboard viewer workspace - - hosted `document-basic`, `comic-basic`, and `storyboard-basic` sample open paths - - package-derived outline panels - - no browser console warnings/errors -- Browser mobile verification passed for light/dark single-column layout with samples and drop zone present. -- Screenshot artifacts: - - `/tmp/prd-redesign-screens/landing-dark.png` - - `/tmp/prd-redesign-screens/viewer-loaded-storyboard.png` - - `/tmp/prd-redesign-screens/viewer-light.png` - - `/tmp/prd-redesign-screens/mobile-viewer-light.png` - - `/tmp/prd-redesign-screens/mobile-landing-light.png` +- `pnpm viewer:demo:build` passed and regenerated ignored hosted sample archives. +- Cloudflare Pages `_redirects` is expected to be copied into `apps/prd-viewer-web/dist` during Vite build. +- GitHub Pages workflow now creates `apps/prd-viewer-web/dist/404.html` during CI deployment. +- Browser verification confirmed: + - `/` renders Home with route state `home` + - `/viewer/` renders the PRD Web Viewer with route state `viewer` + - `/docs/` renders the public docs index with route state `docs` + - public docs sections render in the expected order + - Cloudflare Pages and GitHub Pages hosting copy is visible + - public docs contain no `codex/` links + - browser console had no errors or warnings +- `pnpm foundation:gate` passed: build, tests, docs consistency, example validation, and aggregate example smoke. ## Known issues -- GitHub Pages must be enabled/configured for the repository environment before the new workflow can publish a live URL. -- Hosted sample archives are generated build assets and are intentionally ignored in git. -- Hosted sample loading is web-demo behavior only and does not change PRD's packaged-first loading semantics. -- The in-app Browser Playwright subset still does not expose local file upload control, so manual file-picker/drop upload could not be automated visually. Archive selection is covered by `viewerArchiveFiles` tests, and hosted sample loading exercises the same package-open/render path after bytes are available. +- Cloudflare Pages production deployment is not configured or launch-QA verified yet. +- GitHub Pages remains staging/fallback until `prd.eonhive.com` passes launch QA. +- Hosted sample archives are generated ignored build assets and should not be committed. +- Manual `.prd` file-picker/drop upload was not automated in-browser; archive filtering remains covered by tests, and hosted sample loading exercises the same in-memory open path after archive bytes are available. ## Next recommended task -- Monitor and merge clean PR `#46` after checks pass. -- After the PR lands, run `NEXT_STEPS.md` item `43`: launch QA against the live GitHub Pages URL and choose the next focused viewer/product polish step. +- Commit and open PR `[stannesi] add public docs and hosting path`. +- After merge, run `NEXT_STEPS.md` item `44`: configure/verify Cloudflare Pages for `prd.eonhive.com`, then launch-QA `/`, `/viewer/`, `/docs/`, hosted samples, route refresh, theme persistence, mobile layout, and manual `.prd` upload. ## Important decisions -- Use one app: `apps/prd-viewer-web`. -- Separate the one app into `/` landing and `/viewer/` workspace routes instead of creating separate apps or deployments. -- Use GitHub Pages for the public hosted demo path. -- Support both light mode and premium dark mode; dark mode is default. -- Keep hosted samples as generated demo assets instead of committed `.prd` binaries. -- Keep the viewer truth as eager whole-package in-memory loading. +- Keep one deployable app: `apps/prd-viewer-web`. +- Use route labels `/` Home, `/viewer/` Web Viewer, and `/docs/` public docs. +- Use Cloudflare Pages as intended production hosting for `prd.eonhive.com`. +- Keep GitHub Pages as staging/fallback under `/prd/`. +- Keep canonical docs in `docs/`; public `/docs/` is an index/navigation layer. +- Keep `codex/PLANS.md` and `codex/SESSION_HANDOFF.md` tracked but hidden from public docs/site navigation. +- Do not add a changeset; this is private app/docs/operator state. ## Do not redo - Do not redo npm publication, deprecation, registry audit, or consumer smoke for `0.1.1`. -- Do not add Studio, Cloud, PRDc, AI assistant, library/accounts, payment, crypto, rights, universal file viewer, DOCX/EPUB/PDF conversion, HTML import, or visual-editor behavior to this slice. -- Do not add new manifest fields, schema rules, validator issue codes, viewer support states, CLI commands, package exports, or npm release behavior for this slice. +- Do not add Studio, Cloud authoring, PRDc product behavior, AI assistant, accounts/library, payment, crypto, rights, universal file viewer, DOCX/EPUB/PDF conversion, HTML import, or visual-editor behavior in this slice. +- Do not add new manifest fields, schema rules, validator issue codes, viewer support states, CLI commands, package exports, or npm release behavior in this slice. diff --git a/docs/README.md b/docs/README.md index ceb0d04..e384148 100644 --- a/docs/README.md +++ b/docs/README.md @@ -34,6 +34,7 @@ Primary paths: * `governance/PRD_PROFILE_REGISTRY.md` * `governance/PRD_PROMPT_DOCTRINE.md` * `governance/PRD_RELEASE_POLICY.md` + * `governance/PRD_HOSTING_RUNBOOK.md` * product boundaries * `product/PRD_PRODUCT_BOUNDARIES.md` * `product/PRD_AUTHORING_WORKFLOW.md` @@ -62,6 +63,7 @@ Supporting control docs: * `governance/PRD_PROMPT_DOCTRINE.md` * `governance/PRD_RELEASE_POLICY.md` * `governance/PRD_NPM_RELEASE_RUNBOOK.md` +* `governance/PRD_HOSTING_RUNBOOK.md` * `prompts/PRD_MASTER_PROMPTS.md` --- @@ -103,6 +105,7 @@ Control docs for profile governance and prompt discipline: * `PRD_PROMPT_DOCTRINE.md` * `PRD_RELEASE_POLICY.md` * `PRD_NPM_RELEASE_RUNBOOK.md` +* `PRD_HOSTING_RUNBOOK.md` ### `prompts/` @@ -160,8 +163,11 @@ Product-boundary and ecosystem-role docs: Current public demo surface: -* `../apps/prd-viewer-web/` (one deployable app with `/` landing page and `/viewer/` reference Web Viewer workspace) -* `../.github/workflows/viewer-demo-pages.yml` (GitHub Pages deployment) +* `../apps/prd-viewer-web/` (one deployable app with `/` Home, `/viewer/` reference Web Viewer workspace, and `/docs/` public docs index) +* `governance/PRD_HOSTING_RUNBOOK.md` (Cloudflare production and GitHub Pages fallback/staging path) +* `../.github/workflows/viewer-demo-pages.yml` (temporary GitHub Pages staging/fallback deployment) + +The public `/docs/` route is a navigation layer over canonical repo docs. It is not a replacement for this directory, and it intentionally does not link `../codex/` operational planning files. ### `market/` diff --git a/docs/foundation/04_PRD/PRD_ROADMAP.md b/docs/foundation/04_PRD/PRD_ROADMAP.md index 147f9b8..04c0e6d 100644 --- a/docs/foundation/04_PRD/PRD_ROADMAP.md +++ b/docs/foundation/04_PRD/PRD_ROADMAP.md @@ -162,9 +162,10 @@ Do not build late-stage fantasy systems before the base format is real. - `prd import markdown` now provides deterministic Markdown-to-structured-`general-document` import - `prd import images` now provides deterministic ordered image-folder import for `comic` and `storyboard` - the current authoring workflow and import/export matrix docs define how those commands fit into public authoring -- the current executable lane is public viewer/demo/landing UX polish that demonstrates the create/import, validate, pack, and open flow -- the current executable lane is the hosted PRD landing page and reference Web Viewer demo deployed through GitHub Pages, with `/` for landing and `/viewer/` for the workspace -- the next product lane should launch-QA the hosted demo and then choose the next viewer/product polish step +- the current executable lane is public Home/docs/viewer polish that demonstrates the create/import, validate, pack, and open flow +- the current executable lane is the hosted PRD Home page, public docs index, and reference Web Viewer demo, with `/` for Home, `/viewer/` for the workspace, and `/docs/` for public docs +- Cloudflare Pages at `prd.eonhive.com` is the intended production host; GitHub Pages remains staging/fallback under `/prd/` until Cloudflare launch QA passes +- the next product lane should launch-QA the Cloudflare production path, keep GitHub Pages as fallback, and then choose the next focused viewer/product polish step - defer full visual Studio, broad conversion, and hosted conversion workflows until the hosted public demo/viewer path is proven --- diff --git a/docs/governance/PRD_HOSTING_RUNBOOK.md b/docs/governance/PRD_HOSTING_RUNBOOK.md new file mode 100644 index 0000000..7e25c1b --- /dev/null +++ b/docs/governance/PRD_HOSTING_RUNBOOK.md @@ -0,0 +1,82 @@ +# PRD Hosting Runbook + +## Purpose + +This runbook defines the intended public hosting path for the PRD public site and reference Web Viewer demo. + +It covers deployment ownership only. It does not change PRD package validity, manifest shape, viewer conformance, CLI behavior, npm releases, or runtime loading semantics. + +## Public Routes + +Production target: + +- `https://prd.eonhive.com/` = Home +- `https://prd.eonhive.com/viewer/` = PRD Web Viewer workspace +- `https://prd.eonhive.com/docs/` = public docs index + +Temporary staging/fallback target: + +- GitHub Pages continues to serve the same Vite app under the repository base path `/prd/`. +- GitHub Pages routes are `/prd/`, `/prd/viewer/`, and `/prd/docs/`. + +## Hosting Policy + +Cloudflare Pages is the intended production host for `prd.eonhive.com`. + +GitHub Pages remains a staging and fallback host until the Cloudflare custom-domain path is live, route refresh works, hosted samples load, theme persistence works, and mobile QA passes. + +The public docs route is a navigation layer over the canonical repository docs. Canonical docs remain in `docs/`. Codex operational docs remain tracked in `codex/` for workflow continuity, but they are not public docs, marketing pages, or site navigation entries. + +## Build Inputs + +The hosted app lives in `apps/prd-viewer-web`. + +Current build surfaces: + +```bash +pnpm viewer:demo:assets +pnpm viewer:demo:build +pnpm viewer:demo:dev +``` + +`viewer:demo:assets` packs canonical examples and copies selected generated `.prd` archives into the ignored `apps/prd-viewer-web/public/examples/` directory. + +Hosted sample archives are demo assets only. They do not define a PRD network-loading guarantee and do not change the reference viewer truth: eager whole-package in-memory loading. + +The Vite public directory includes `_redirects` so Cloudflare Pages serves the SPA entry for `/viewer/` and `/docs/` refreshes. The GitHub Pages workflow copies `index.html` to `404.html` after build for the same staging/fallback route behavior. + +## Cloudflare Setup Checklist + +1. Create or select the Cloudflare Pages project for `apps/prd-viewer-web`. +2. Configure production domain `prd.eonhive.com`. +3. Build with a root-domain base path, not the GitHub Pages `/prd/` base path. +4. Ensure generated demo assets are prepared before the Vite build. +5. Verify direct refresh for `/`, `/viewer/`, and `/docs/`. +6. Verify hosted sample archives open through the same viewer path as manual `.prd` uploads. +7. Verify dark/light theme persistence on production. +8. Verify desktop and mobile layouts. + +Reference docs: + +- Cloudflare Pages custom domains: `https://developers.cloudflare.com/pages/configuration/custom-domains/` +- Cloudflare Pages direct upload: `https://developers.cloudflare.com/pages/get-started/direct-upload/` + +## GitHub Pages Fallback + +The existing `.github/workflows/viewer-demo-pages.yml` workflow remains the fallback/staging deployment path. + +It builds with `PRD_VIEWER_BASE_PATH=/prd/` and deploys `apps/prd-viewer-web/dist`. + +Reference docs: + +- GitHub Pages custom domains: `https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site` + +## Do Not Add In This Lane + +- Accounts, sign-in, pricing, checkout, or free-trial behavior +- Studio, Cloud authoring, PRDc archive product behavior, or AI assistant behavior +- New manifest fields or schema semantics +- New validator rules +- New CLI commands +- New npm package exports or release behavior +- Streaming, range requests, worker unzip, lazy section fetch, or network-loading format claims diff --git a/docs/product/PRD_AUTHORING_WORKFLOW.md b/docs/product/PRD_AUTHORING_WORKFLOW.md index 89e3b95..762056f 100644 --- a/docs/product/PRD_AUTHORING_WORKFLOW.md +++ b/docs/product/PRD_AUTHORING_WORKFLOW.md @@ -173,6 +173,6 @@ Those remain future product or extension lanes. ## 6. Next Implementation Lane -After `prd import markdown` and `prd import images`, the current executable public-product lane is the hosted PRD landing page and reference Web Viewer demo. It demonstrates the real create/import, validate, inspect, pack, and open flow with light and premium dark modes, using `/` for the product landing page and `/viewer/` for the actual package-opening workspace. +After `prd import markdown` and `prd import images`, the current executable public-product lane is the hosted PRD Home page, public docs index, and reference Web Viewer demo. It demonstrates the real create/import, validate, inspect, pack, and open flow with light and premium dark modes, using `/` for Home, `/viewer/` for the actual package-opening workspace, and `/docs/` for the public docs navigation layer over canonical repo docs. Full Studio, hosted conversion, DOCX/EPUB/PDF fidelity, and broad HTML import remain deferred. diff --git a/docs/product/PRD_IMPORT_EXPORT_MATRIX.md b/docs/product/PRD_IMPORT_EXPORT_MATRIX.md index ad0a41c..cdda394 100644 --- a/docs/product/PRD_IMPORT_EXPORT_MATRIX.md +++ b/docs/product/PRD_IMPORT_EXPORT_MATRIX.md @@ -105,15 +105,15 @@ This lane does not attempt image processing, optimization, OCR, panel detection, ## 7. Current Hosted Viewer Demo Lane -The current public-product implementation is the hosted PRD landing page and reference web viewer demo that demonstrates the now-real authoring loop: +The current public-product implementation is the hosted PRD Home page, public docs index, and reference web viewer demo that demonstrates the now-real authoring loop: ```text init/import -> validate -> inspect -> pack -> open in the reference viewer ``` -That keeps the product story focused on usable PRD creation before adding broad conversion. The web demo separates `/` landing from `/viewer/` workspace. It can load generated hosted sample archives, but those samples are demo assets only and do not change PRD's packaged-first, eager whole-package reference loading baseline. +That keeps the product story focused on usable PRD creation before adding broad conversion. The web demo separates `/` Home, `/viewer/` workspace, and `/docs/` public docs navigation. It can load generated hosted sample archives, but those samples are demo assets only and do not change PRD's packaged-first, eager whole-package reference loading baseline. -The next public-product lane should launch-QA the hosted demo, verify the GitHub Pages deployment, and then choose the next viewer/product polish step. +The next public-product lane should launch-QA the hosted demo, verify the Cloudflare Pages production path at `prd.eonhive.com`, keep GitHub Pages as staging/fallback until that passes, and then choose the next viewer/product polish step. --- diff --git a/docs/product/PRD_PRODUCT_BOUNDARIES.md b/docs/product/PRD_PRODUCT_BOUNDARIES.md index 4e4674f..1fbcb10 100644 --- a/docs/product/PRD_PRODUCT_BOUNDARIES.md +++ b/docs/product/PRD_PRODUCT_BOUNDARIES.md @@ -52,7 +52,9 @@ The current clean public npm baseline is `0.1.1`. The web viewer and viewer-core packages are present in the repository as reference implementation surfaces, but they are not part of the public npm publish set. -The hosted PRD Web Viewer demo is a public reference-stack demo surface. It lives in `apps/prd-viewer-web`, deploys as one static GitHub Pages app, and separates the product landing page (`/`) from the actual reference Web Viewer workspace (`/viewer/`). It may include generated sample `.prd` archives for demonstration. Those hosted samples are demo assets only; they do not add a PRD network-loading guarantee or change the package validity model. +The hosted PRD Web Viewer demo is a public reference-stack demo surface. It lives in `apps/prd-viewer-web`, deploys as one static app, and separates Home (`/`), the actual reference Web Viewer workspace (`/viewer/`), and the public docs index (`/docs/`). Cloudflare Pages is the intended production host for `prd.eonhive.com`; GitHub Pages remains the temporary staging/fallback path under `/prd/`. It may include generated sample `.prd` archives for demonstration. Those hosted samples are demo assets only; they do not add a PRD network-loading guarantee or change the package validity model. + +Codex operational files under `codex/` may remain tracked for implementation continuity, but they are not part of the public product docs, public site navigation, or canonical format documentation. --- @@ -182,4 +184,4 @@ The current Phase 5 authoring docs are: The current Phase 5 executable authoring lanes are `prd init`, `prd import markdown`, and `prd import images`. Together they cover starter package scaffolding, structured `general-document` import from a small Markdown subset, and ordered image-folder import for `comic` and `storyboard`. -The current public-product lane is the hosted PRD landing page and reference Web Viewer demo. It shows the real create/import, validate, inspect, pack, and open flow, separates `/` landing from `/viewer/` workspace, includes light and premium dark modes, and deploys through GitHub Pages as a static app. HTML, DOCX, EPUB, PDF, hosted conversion, full Studio, Cloud publishing, PRDc workflows, and broad visual editing remain deferred product lanes. +The current public-product lane is the hosted PRD Home page, public docs index, and reference Web Viewer demo. It shows the real create/import, validate, inspect, pack, and open flow; separates `/` Home, `/viewer/` workspace, and `/docs/` public docs; includes light and premium dark modes; and treats Cloudflare Pages at `prd.eonhive.com` as the intended production host with GitHub Pages as staging/fallback. HTML, DOCX, EPUB, PDF, hosted conversion, full Studio, Cloud publishing, PRDc workflows, and broad visual editing remain deferred product lanes.