Prefer server-rendered HTML over SPA-first architecture.
Treat forms, links, redirects, and document navigation as primary primitives.
Use client JavaScript to enhance the baseline experience, not to replace it.
Keep the network, browser, and device cost low by default.
Do not assume Webstir lacks any cache or invalidation foundation, but distinguish the current contract/build-cache surfaces from the still-missing request/runtime story.
Completed: progressive-enhancement route primitives landed in @webstir-io/module-contract.
Routes now support explicit mutation metadata, form metadata, fragment metadata, redirect outputs, and fragment/redirect handler results.
Completed: backend scaffold runtime honors the new route results.
The default server and Fastify scaffold now handle redirects, fragment responses, and application/x-www-form-urlencoded request bodies.
Backend tests now include an end-to-end runtime check for redirect and fragment responses.
Completed: the Bun client/runtime enhancement path can now consume fragment responses from enhanced forms.
client-nav now intercepts eligible same-origin POST forms, applies fragment updates, and keeps full-document HTML swaps for non-fragment responses.
Bun tests now cover fragment response metadata parsing and the expanded client-nav asset scaffolding.
Completed: the canonical full-demo application now proves the form-submit -> fragment-update flow end to end.
examples/demos/full now exposes a backend-served HTML form route that redirects cleanly without JavaScript and returns fragment updates when client-nav enhances the submission.
The demo now validates the route directly via backend tests and through the /api proxy path in the full watch integration test, and the page resolves shared frontend assets in both watch and publish flows.
Current focus: extend the default scaffold/runtime ergonomics around validation, flash/session messaging, auth-aware form workflows, and broader fragment-mode hardening.
1. Contract primitives for progressive enhancement
Extend @webstir-io/module-contract so forms, mutations, fragment responses, redirects, flash/session messaging, and request pipeline hooks are explicit framework primitives.
Keep route/view contracts, but add the missing authoring model for progressive enhancement workflows.
Main touchpoint: packages/contracts/module-contract/src/index.ts.
Status: initial slice complete; follow-up work still needed for richer response variants and adjacent primitives such as flash/session messaging.
Build a runtime path for request-time HTML rendering, not only SSG metadata and view-data.json generation.
Treat server-rendered HTML as the flagship path in the frontend/backend integration.
Main touchpoints: packages/tooling/webstir-backend/templates/backend/index.ts, packages/tooling/webstir-backend/templates/backend/server/fastify.ts, and then the frontend/backend provider packaging surfaces once the request-time runtime exists.
Add an official way to update a region of the page after form submissions or user interactions.
This should feel native to the framework and preserve the non-JavaScript baseline.
Main touchpoints: orchestrators/bun/resources/features/client_nav/*, packages/tooling/webstir-backend/templates/backend/index.ts, packages/tooling/webstir-backend/templates/backend/server/fastify.ts.
Status: the first client-side slice is in place for enhanced same-origin POST forms, and examples/demos/full now proves the canonical form -> fragment path end to end; broader hardening and richer modes are still outstanding.
Make server-handled forms easier than client-heavy mutation flows.
Cover parsing, validation, error presentation, redirect-after-post, CSRF, and flash message ergonomics in the default scaffold/runtime.
Main touchpoints: packages/tooling/webstir-backend/src/scaffold/assets.ts, packages/tooling/webstir-backend/src/build/*, packages/tooling/webstir-backend/src/manifest/pipeline.ts.
Wire middleware or request hooks through the actual Bun runtime, not just the manifest schema.
Make auth, logging, sessions, redirects, and cache-aware behavior composable in the request path.
Main touchpoints: packages/contracts/module-contract/src/index.ts, packages/tooling/webstir-backend/templates/backend/index.ts, packages/tooling/webstir-backend/templates/backend/server/fastify.ts.
Surface the current cache foundations in a way application authors can use and understand, and close the gap between build-time cache metadata and request/runtime cache behavior.
Document what is cached, where it lives, how it is invalidated, and how page or fragment correctness is maintained.
Main touchpoints: contract docs, backend runtime, and framework docs.
7. Reframe the frontend package around HTML-first app delivery
Move the product story away from "experimental page pipeline" and toward "HTML-first application runtime."
Keep SSG as one mode, not the center of the framework identity.
Main touchpoints: packages/tooling/webstir-frontend/README.md, apps/portal/docs/how-to/*, apps/portal/docs/reference/*.
Add canonical end-to-end apps that prove the model on real software, not just toy demos.
Target examples such as auth, CRUD backoffice, content plus forms, dashboards with partial refreshes, and background jobs.
Main touchpoint: examples/demos/*.
Status: the initial canonical form-flow proof now exists in examples/demos/full; follow-up apps should expand the surface area to auth, CRUD, and dashboard-style partial refreshes.