@webstir-io/webstir-frontend 0.1.40 → 0.1.41

package/README.md

@@ -1,30 +1,92 @@
 # @webstir-io/webstir-frontend
 
-Frontend build and publish toolkit for Webstir workspaces. The package bundles the HTML/CSS/JS pipeline, scaffolding helpers, and module provider used by the Webstir CLI and installers.
+HTML-first frontend delivery for Webstir workspaces. This package builds page documents, shared app assets, CSS, and browser-side enhancement scripts for applications that start with server-rendered HTML and selectively add JavaScript where it improves the experience.
 
-## Status
+## What It Ships
 
-- Experimental provider for the Webstir ecosystem — pipeline details and configuration surfaces may change between releases.
-- Best suited for exploration and demos today; do not rely on it as a hardened production frontend pipeline yet.
+- Multi-page HTML/CSS/JS builds for `src/frontend/**`
+- Publish output with fingerprinted assets under `dist/frontend/**`
+- Watch-mode rebuilds used by the Bun orchestrator
+- Shared app-shell assets such as navigation, refresh, and client enhancement hooks
+- Runtime helpers for boundary-style mount/unmount lifecycles and cleanup scopes
+- SSG as a supported mode, without making static-only delivery the center of the product story
+
+Requires Bun **1.3.11** or newer.
+
+## Runtime Model
+
+Client code that participates in hot updates should use the boundary runtime instead of relying on module top-level side effects.
+
+```ts
+import { createCleanupScope, defineBoundary } from '@webstir-io/webstir-frontend/runtime';
+```
+
+- `createCleanupScope()` collects cleanup handlers and disposes them in reverse registration order.
+- `defineBoundary()` wraps a page or app region with explicit `mount()` and `unmount()` lifecycle methods.
+- Boundary scopes can mount nested child boundaries with `scope.mountChild(...)`; child boundaries unmount before the parent boundary tears down.
+- Boundaries can opt into hot-state preservation with `snapshotState()` and `restoreState()`; when those hooks are absent, remounts start fresh.
+- `listen()`, `scheduleTimeout()`, `scheduleInterval()`, `trackObserver()`, and `createAbortController()` wrap common side effects so cleanup stays attached to the boundary scope.
+- Boundary code should register DOM listeners, timers, observers, and similar side effects through the cleanup scope so remounts stay deterministic.
+
+## Hot Update Rules
+
+Webstir watch mode follows a narrow fallback policy:
+
+- CSS edits hot-swap in the browser.
+- JS edits remount only when the module or boundary explicitly opts in.
+- Most content, HTML, and route-shape changes fall back to rebuild + reload.
+- Current exception: the SSG docs-sidebar pilot also remounts on `src/frontend/content/_sidebar.json` edits.
+- Any cleanup failure or declined boundary update falls back to reload.
+
+## Fragment Ownership Decision
+
+The current SSG runtime has a working fragment-ownership pilot on the docs sidebar boundary. It now covers the sidebar manifest input (`src/frontend/content/_sidebar.json`) in addition to direct docs page module edits, but owned-fragment HTML replacement is still not justified yet as a general mechanism.
+
+Keep reload/remount as the default until the runtime has:
+
+- More than one real owned fragment with clear parent/child invalidation rules
+- A stable fragment-to-source mapping for generated HTML updates
+- A lifecycle contract for replacing HTML without duplicating side effects or breaking page state
+
+Until then, content and HTML changes should continue to fall back to rebuild + reload.
+
+## HTML-First Workflow
+
+The frontend package is designed to pair with the backend runtime rather than replace it:
+
+- Build document shells under `build/frontend/pages/**`
+- Publish optimized assets under `dist/frontend/**`
+- Let backend routes or request-time views deliver HTML first
+- Use enhancement scripts for fragment updates, navigation polish, and form handling when JavaScript is available
+
+Canonical proof apps in this repo:
+
+- [`examples/demos/auth-crud`](../../../examples/demos/auth-crud) for server-handled auth, validation, redirect-after-post, and CRUD flows
+- [`examples/demos/dashboard`](../../../examples/demos/dashboard) for shell-level and panel-level partial refreshes without SPA architecture
 
 ## Quick Start
 
-1. **Install the package**
-   ```bash
-   npm install @webstir-io/webstir-frontend
-   ```
-2. **Run a build**
-   ```bash
-   npx webstir-frontend build --workspace /absolute/path/to/workspace
-   ```
+1. Install the package
+
+```bash
+bun add @webstir-io/webstir-frontend
+```
 
-Requires Node.js **20.18.x** or newer.
+2. Build a workspace
 
-## Workspace Layout
+```bash
+bunx webstir-frontend build --workspace /absolute/path/to/workspace
+```
 
-The provider assumes the standard Webstir workspace shape:
+3. Publish optimized frontend assets
 
+```bash
+bunx webstir-frontend publish --workspace /absolute/path/to/workspace
 ```
+
+## Workspace Layout
+
+```text
 workspace/
   src/frontend/
     app/
@@ -32,42 +94,44 @@ workspace/
     images/
     fonts/
     media/
-    frontend.config.json   # optional feature flag overrides
-    webstir.config.mjs     # optional hook definitions
-  build/frontend/...       # generated build artifacts
-  dist/frontend/...        # publish-ready assets
-  .webstir/manifest.json   # pipeline manifest emitted on each run
+    frontend.config.json   # optional feature flags
+    webstir.config.mjs     # optional hooks
+  build/frontend/...       # watch/build output
+  dist/frontend/...        # publish output
+  .webstir/manifest.json   # pipeline manifest
 ```
 
 ## CLI Commands
 
-Binary name: `webstir-frontend`. All commands require `--workspace` pointing to the absolute workspace root.
+Binary name: `webstir-frontend`. All commands require `--workspace`.
 
 | Command | Description | Useful options |
-|---------|-------------|----------------|
-| `build` | Runs the development pipeline (incremental safe). | `--changed-file <path>` to scope rebuilds. |
-| `publish` | Produces optimized assets under `dist/frontend`. | `--mode <bundle\|ssg>` (SSG preview). |
-| `rebuild` | Incremental rebuild triggered by a file change. | `--changed-file <path>` to pass the changed file. |
-| `add-page <name>` | Scaffolds a page (HTML/CSS/TS) inside `src/frontend/pages`. | — |
-| `watch-daemon` | Persistent watcher + HMR coordinator. | `--no-auto-start`, `--verbose`, `--hmr-verbose`. |
+| --- | --- | --- |
+| `build` | Runs the development-oriented pipeline. | `--changed-file <path>` to scope rebuilds. |
+| `publish` | Produces optimized frontend assets. | `--mode <bundle\|ssg>` |
+| `rebuild` | Incremental rebuild after a file change. | `--changed-file <path>` |
+| `add-page <name>` | Scaffolds `index.html`, `index.css`, and `index.ts`. | None |
 
-### Feature Flags
+## Feature Flags
 
-`frontend.config.json` enables or disables pipeline features:
+`frontend.config.json` controls optional pipeline features:
 
 ```jsonc
 {
   "features": {
     "htmlSecurity": true,
+    "externalResourceIntegrity": false,
     "imageOptimization": true,
     "precompression": false
   }
 }
 ```
 
-### Lifecycle Hooks
+`externalResourceIntegrity` stays `false` by default so publish does not fetch third-party script or stylesheet URLs just to compute SRI. Enable it only when you explicitly want remote fetches during publish; otherwise, add `integrity` and `crossorigin` attributes yourself for external CDN assets.
+
+## Lifecycle Hooks
 
-Hooks live in `webstir.config.mjs` (or `.js`/`.cjs`) at the workspace root:
+Hooks live in `webstir.config.mjs` (or `.js` / `.cjs`) at the workspace root:
 
 ```js
 export const hooks = {
@@ -78,7 +142,7 @@ export const hooks = {
   },
   builders: {
     assets: {
-      after({ config }) {
+      after() {
         // custom post-processing
       }
     }
@@ -88,8 +152,6 @@ export const hooks = {
 
 ## API Usage
 
-The package exports a `ModuleProvider` compatible with `@webstir-io/module-contract`:
-
 ```ts
 import { frontendProvider } from '@webstir-io/webstir-frontend';
 
@@ -98,49 +160,51 @@ const result = await frontendProvider.build({
   env: { WEBSTIR_MODULE_MODE: 'publish' }
 });
 
-   console.log(result.manifest.entryPoints);
-   ```
+console.log(result.manifest.entryPoints);
+```
 
-- `frontendProvider.metadata` surfaces id/version compatibility.
-- `frontendProvider.resolveWorkspace` returns canonical source/build/test paths.
-- `frontendProvider.build` executes the pipeline and returns artifacts + manifest.
+- `frontendProvider.metadata` exposes package and runtime-compatibility metadata
+- `frontendProvider.resolveWorkspace()` returns canonical source/build roots
+- `frontendProvider.build()` executes the pipeline and returns artifacts plus manifest data
+- `inspectFrontendWorkspace()` returns resolved config plus shallow workspace facts without building
 
-## SSG Preview
+## SSG Mode
 
-When invoked as:
+SSG is a supported frontend output mode, not a separate product:
 
 ```bash
-npx webstir-frontend publish --workspace /absolute/path/to/workspace --mode ssg
+bunx webstir-frontend publish --workspace /absolute/path/to/workspace --mode ssg
 ```
 
-the provider:
+That run:
 
-- Runs the normal publish pipeline to populate `dist/frontend/**`.
-- Creates static-friendly `index.html` aliases (root and per-page).
-- When `package.json` includes `webstir.moduleManifest.views` with `renderMode: 'ssg'` and `staticPaths`, uses those paths to add additional `index.html` aliases under `dist/frontend/**`.
+- Builds normal publish assets under `dist/frontend/**`
+- Generates `index.html` aliases for document routes
+- Uses `webstir.moduleManifest.views` metadata when present to emit extra static paths
 
 ## Maintainer Workflow
 
 ```bash
-npm install
-npm run clean          # remove dist artifacts
-npm run build          # TypeScript → dist/
-npm run test           # Node --test against compiled output
-npm run smoke          # scaffolds a temp workspace and runs build/publish
-# Release helper (bumps version, pushes tags to trigger release workflow)
-npm run release -- patch
+bun install
+bun run clean
+bun run build
+bun run test
+bun run release -- patch
 ```
 
-GitHub Actions should run `npm ci`, `npm run clean`, `npm run build`, `npm run test`, and `npm run smoke` before publishing. The release workflow publishes to npm with trusted publishing (`id-token: write` + provenance).
+Recommended package validation before release:
 
-CI notes
-- Package CI runs clean + build + tests + smoke on PRs and main.
+- `bun run build`
+- `bun run test`
 
 ## Troubleshooting
 
-- **“404 Not Found” when installing `@webstir-io/module-contract`** — verify the dependency has been published to npm and re-generate `package-lock.json` against npmjs.
-- **“No frontend test files found”** — the `test` script expects files under `tests/**/*.test.js` after build.
-- **Missing entry points in manifest** — confirm `build/frontend` contains at least one `.js`/`.mjs` bundle; the provider falls back to `build/app/index.js` and emits a warning if empty.
+- `No frontend test files found`
+  The package test script expects compiled tests under `tests/**/*.test.js`.
+- `Missing entry points in manifest`
+  Confirm `build/frontend` contains at least one generated JS entry.
+- `SSG output missing a route`
+  Check `webstir.moduleManifest.views` for `renderMode: "ssg"` and the expected `staticPaths`.
 
 ## Community & Support
 
@@ -151,7 +215,7 @@ CI notes
 
 ## Third-Party Notices
 
-Webstir Frontend depends on third-party libraries and data sets (including `sharp`/libvips and `caniuse-lite`) under their respective licenses. See [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) for a summary of notable licenses and attribution.
+Webstir Frontend depends on third-party libraries and data sets (including `sharp` / libvips and `caniuse-lite`) under their respective licenses. See [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) for the attribution summary.
 
 ## License
 

package/dist/assets/imageOptimizer.js

@@ -1,13 +1,9 @@
 import path from 'node:path';
 import sharp from 'sharp';
-import { glob } from 'glob';
 import { copy, ensureDir, emptyDir, pathExists, remove } from '../utils/fs.js';
 import { EXTENSIONS } from '../core/constants.js';
-const TRANSCODABLE_EXTENSIONS = new Set([
-    EXTENSIONS.png,
-    EXTENSIONS.jpg,
-    EXTENSIONS.jpeg
-]);
+import { scanGlob } from '../utils/glob.js';
+const TRANSCODABLE_EXTENSIONS = new Set([EXTENSIONS.png, EXTENSIONS.jpg, EXTENSIONS.jpeg]);
 export async function optimizeImages(sourceDir, destinationDir, files) {
     if (!(await pathExists(sourceDir))) {
         await emptyDir(destinationDir);
@@ -15,7 +11,7 @@ export async function optimizeImages(sourceDir, destinationDir, files) {
     }
     if (!files || files.length === 0) {
         await emptyDir(destinationDir);
-        const allFiles = await glob('**/*', { cwd: sourceDir, nodir: true });
+        const allFiles = await scanGlob('**/*', { cwd: sourceDir });
         await Promise.all(allFiles.map(async (relative) => processImage(sourceDir, destinationDir, relative)));
         return;
     }
@@ -40,9 +36,7 @@ function replaceExtension(filePath, extension) {
 }
 async function createWebpVariant(sourcePath, destinationPath) {
     try {
-        await sharp(sourcePath)
-            .webp({ quality: 75 })
-            .toFile(destinationPath);
+        await sharp(sourcePath).webp({ quality: 75 }).toFile(destinationPath);
     }
     catch {
         // Ignore failures; fall back to original image only.
@@ -50,9 +44,7 @@ async function createWebpVariant(sourcePath, destinationPath) {
 }
 async function createAvifVariant(sourcePath, destinationPath) {
     try {
-        await sharp(sourcePath)
-            .avif({ quality: 45 })
-            .toFile(destinationPath);
+        await sharp(sourcePath).avif({ quality: 45 }).toFile(destinationPath);
     }
     catch {
         // Ignore failures; fall back to original image only.
@@ -79,11 +71,14 @@ async function processImage(sourceDir, destinationDir, relative, incremental = f
     }
     await Promise.all([
         createWebpVariant(sourcePath, replaceExtension(destinationPath, EXTENSIONS.webp)),
-        createAvifVariant(sourcePath, replaceExtension(destinationPath, EXTENSIONS.avif))
+        createAvifVariant(sourcePath, replaceExtension(destinationPath, EXTENSIONS.avif)),
     ]);
 }
 async function removeVariants(destinationPath, includeBase) {
-    const targets = [replaceExtension(destinationPath, EXTENSIONS.webp), replaceExtension(destinationPath, EXTENSIONS.avif)];
+    const targets = [
+        replaceExtension(destinationPath, EXTENSIONS.webp),
+        replaceExtension(destinationPath, EXTENSIONS.avif),
+    ];
     if (includeBase) {
         targets.push(destinationPath);
     }

package/dist/assets/precompression.js

@@ -3,7 +3,7 @@ import { constants as zlibConstants, createBrotliCompress, createGzip } from 'no
 export async function createCompressedVariants(filePath) {
     await Promise.all([
         compress(filePath, '.br', () => createBrotliCompress({ params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 11 } })),
-        compress(filePath, '.gz', () => createGzip({ level: zlibConstants.Z_BEST_COMPRESSION }))
+        compress(filePath, '.gz', () => createGzip({ level: zlibConstants.Z_BEST_COMPRESSION })),
     ]);
 }
 async function compress(source, extension, factory) {