@orderlyshop/web-components 0.1.0-build.7051 → 0.1.0-build.7056

package/README.md

@@ -28,7 +28,7 @@ npx orderly-init-shop --account-id 00000000-0000-0000-0000-000000000000
 
 Re-running `npx orderly-init-shop` in an existing shop is non-destructive by default. Existing scaffold files are left unchanged with warnings, while missing new scaffold files are added. Use `--force` only when you explicitly want scaffold files overwritten.
 
-The scaffold uses Vite for local development and static builds, but Vite is added to the generated shop's `devDependencies`. Consumers should test locally from `http://localhost:61677` or `https://localhost:61677` because those are the expected local development origins for backend CORS. The generated Vite setup defaults to `http://localhost:61677`; if a local reverse proxy or TLS terminator is added, keep the same `localhost:61677` origin over HTTPS. `@orderlyshop/web-components` does not depend on Vite at runtime.
+The scaffold uses Vite for local development and static builds, but Vite is added to the generated shop's `devDependencies`. Dev mode SSR for product/category URLs is enabled by default, so View Source on local category/product URLs shows semantic server-rendered markup. Consumers should test locally from `http://localhost:61677` or `https://localhost:61677` because those are the expected local development origins for backend CORS. The generated Vite setup defaults to `http://localhost:61677`; if a local reverse proxy or TLS terminator is added, keep the same `localhost:61677` origin over HTTPS. `@orderlyshop/web-components` does not depend on Vite at runtime.
 
 ## Browser Standalone Bundle
 
@@ -377,7 +377,7 @@ Build with generated category pages and then clean the generated source files. S
 npx orderly-build-category-pages
 ```
 
-`orderly-build-category-pages` also hydrates the built `dist/index.html` and generated `dist/categories/**/index.html` pages with SEO-friendly fallback HTML. The hydration step embeds a small product snapshot per category using `SearchService.Search`; it reads `--base-url`, `VITE_ORDERLY_BASE_URL`, or `ORDERLY_BASE_URL`, and otherwise uses the default `https://service.orderly.shop` backend. Live web components hide the fallback when their client-side search data has loaded, so users avoid a blank category page while Google receives meaningful initial HTML.
+`orderly-build-category-pages` also hydrates the built `dist/index.html` and generated `dist/categories/**/index.html` pages with SEO-friendly fallback HTML. The hydration step embeds semantic product cards per category using `SearchService.Search`; it reads `--base-url`, `VITE_ORDERLY_BASE_URL`, or `ORDERLY_BASE_URL`, and otherwise uses the default `https://service.orderly.shop` backend. Live web components read the semantic fallback as initial state, hide it, and then continue as normal client components.
 
 Hydrate an already-built site manually, for example in a nightly job:
 
@@ -389,6 +389,26 @@ Use `--skip-products` for metadata-only hydration, `--strict-products` when a ni
 
 The category generator expects `src/navigation.ts` or `src/navigation.js` to export `navigationDefinitions` and the template page to contain `<orderly-category-page></orderly-category-page>`. TypeScript navigation files use the current shop project's `typescript` dependency for one-off transpilation. Useful options include `--navigation`, `--template`, `--categories-dir`, `--site-title`, `--component-tag`, and `--export`. The older `--taxonomy` flag and `categoryDefinitions` export are still accepted as compatibility aliases.
 
+## Local SSR Dev Mode
+
+Scaffolded shops use SSR in dev mode by default through the package Vite middleware:
+
+```js
+import { orderlySsrDevServer } from "@orderlyshop/web-components/server/vite";
+
+export default defineConfig({
+  plugins: [htmlIncludes(), orderlySsrDevServer(), rootHtmlOutput()]
+});
+```
+
+When you run `npm run dev`, product and category URLs such as `http://localhost:61677/products/example.html/` and `http://localhost:61677/categories/sko/` are served from the normal `src/product.html` and `src/category.html` templates with semantic SSR HTML injected before Vite transforms the page. Use browser View Source to inspect the server-rendered markup.
+
+SSR responses include a small inline critical CSS block for the semantic fallback markup. Normal browser requests hide that fallback and route component light DOM, such as utility banners, until the web components hydrate, so users do not see an unstyled intermediate layout. Googlebot user agents receive the visible fallback layout instead. The HTML source is identical in both cases; only fallback visibility changes.
+
+After the first SSR entry render, the default storefront router intercepts same-origin category, product, checkout, payment-result, and configured static-page links. Navigation then stays virtual with `pushState` and persistent app-shell state, while the anchors still keep real `href` values for SEO, no-JS clients, copied links, and direct entry URLs. Set `storefrontRouter: { enabled: false }` only if the host app deliberately wants physical navigation after every click.
+
+Set `ORDERLY_DEV_SSR=0` or run `npm run dev -- --no-ssr` to debug pure client-side rendering. Dev SSR uses `VITE_ORDERLY_BASE_URL`, `ORDERLY_BASE_URL`, or `https://service.orderly.shop`, defaults to `grpc-web`, and keeps a short per-URL in-memory cache. Override the cache with `ORDERLY_DEV_SSR_CACHE_TTL_MS`.
+
 ## Publish Static Sites
 
 Installing `@orderlyshop/web-components` also installs a publish command for the consuming shop project. Run it from the project directory. The command generates category pages, builds, hydrates the built homepage/category pages, and publishes the resulting `dist` folder as vanilla HTML/JS/CSS.
@@ -419,33 +439,25 @@ Re-enter saved FTP settings:
 npx orderly-publish-site --target ftp --configure
 ```
 
-## Server Side Product URLs
-
-Category pages can be generated and hydrated statically. Product pages usually need real URLs without generating one HTML file per product. The package ships server helper files under `server/` for this pattern:
+## Server Side Product And Category URLs
 
-- `server/apache/.htaccess` rewrites unknown product-like `.html` URLs to PHP.
-- `server/php/orderly-product.php` reuses the built `product.html`, injects declarative SSR fallback markup into `<orderly-product-detail-page>`, and preserves built JS/CSS references.
-- `server/nginx/orderly-products.conf` provides the equivalent Nginx rewrite for PHP-FPM.
-- `server/node/product-snapshot-server.mjs` is an optional Node snapshot endpoint that calls `SearchService.Search` through `@orderlyshop/core-client` and returns product title, brand, price, image, and description as JSON.
-
-Apache deployment example:
+Production SSR for Apache/PHP is generated into the built site:
 
 ```sh
 npm run build
-cp node_modules/@orderlyshop/web-components/server/apache/.htaccess dist/.htaccess
-cp node_modules/@orderlyshop/web-components/server/php/orderly-product.php dist/orderly-product.php
+npx orderly-generate-server-renderers --site-title "My Shop"
 ```
 
-If PHP should SSR real product fields, configure a server-side snapshot endpoint:
+Scaffolded shops run that generator from `npm run build` by default. It writes `dist/product.php`, `dist/category.php`, `dist/.htaccess`, and `dist/orderly-ssr-manifest.json`. The PHP renderers call `SearchService.Search` over gRPC-web, inject semantic HTML into the built `product.html` or `category.html`, and preserve the normal web-component scripts and styles.
 
-```sh
-ORDERLY_BACKEND_URL=https://service.orderly.shop \
-node node_modules/@orderlyshop/web-components/server/node/product-snapshot-server.mjs
+Runtime options:
 
-export ORDERLY_PRODUCT_SNAPSHOT_ENDPOINT=http://127.0.0.1:4107/orderly-product-snapshot
-```
+- `ORDERLY_BASE_URL` overrides the backend URL used by PHP.
+- `ORDERLY_SSR_TIMEOUT` controls PHP backend timeout in seconds.
+- `ORDERLY_SSR_HEADERS` can add internal server-side request headers. Do not expose API keys or bearer tokens to browser JavaScript.
+- `ORDERLY_SSR_MANIFEST` can point PHP to a manifest outside the web root.
 
-The PHP renderer emits a small declarative fallback with `data-orderly-ssr-fallback`; `orderly-product-detail-page` hides that fallback when the browser has loaded the live `SearchObject`. See [`server/README.md`](./server/README.md) for Apache, Nginx, PHP, Node, caching, and SEO notes.
+The semantic fallback uses real headings, links, images, schema.org Product/Offer metadata, and small `data-orderly-*` attributes only for behavior-critical values. Components hydrate from that HTML, then hide the fallback and continue as normal interactive web components. Generated SSR output keeps the same HTML for users and crawlers, hides fallback visibility for normal browser hydration, and serves a visible fallback layout to Googlebot. See [`server/README.md`](./server/README.md) for details.
 
 ## Define Elements