merge main and update markdown example to modern Fresh 2 API

- Use define.page() in a route file instead of old App/ctx.render API
- Use @/utils.ts import consistent with other examples
- Fix route path to routes/markdown.tsx
- Use inline lint-ignore comments instead of file-level directive
- Remove external tutorial link (could go stale)
- Fix step numbering (was skipping step 3)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: bartlomieju

.github/CONTRIBUTING.md

@@ -1,5 +1,20 @@
 # Contributing Guidelines
 
-## Submitting a pull request
+For the full contributing guide, see the
+[Fresh documentation](https://fresh.deno.dev/docs/latest/contributing).
 
-First, please be sure to ensure `deno task ok` is run and successfully passes.
+## PR title format
+
+PR titles must be all lowercase and start with one of the following prefixes:
+
+- `feat:` - new features
+- `fix:` - bug fixes
+- `test:` - test additions or changes
+- `chore:` - maintenance, refactoring, docs
+- `ci:` - CI/CD changes
+
+Example: `feat: add middleware compilation`
+
+## Before submitting
+
+Run `deno task ok` and ensure it passes.

.github/workflows/ci.yml

@@ -7,6 +7,19 @@ on:
     branches: [main]
 
 jobs:
+  pr-title:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate PR title
+        env:
+          TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          if ! echo "$TITLE" | grep -qP '^(chore|ci|docs|feat|fix|refactor|test):'; then
+            echo "::error::PR title must start with chore:, ci:, docs:, feat:, fix:, refactor: or test:"
+            exit 1
+          fi
+
   test:
     runs-on: ${{ matrix.os }}
     timeout-minutes: 10
@@ -34,6 +47,9 @@ jobs:
           cache: true
           deno-version: ${{ matrix.deno }}
 
+      - name: Install dependencies
+        run: deno install
+
       - name: Verify formatting
         if: startsWith(matrix.os, 'ubuntu') && matrix.deno == 'v2.x'
         run: deno fmt --check
@@ -58,3 +74,7 @@ jobs:
       - name: Build fresh.deno.dev
         if: startsWith(matrix.os, 'ubuntu') && matrix.deno == 'v2.x'
         run: deno task build-www
+
+      - name: Check links
+        if: startsWith(matrix.os, 'ubuntu') && matrix.deno == 'v2.x'
+        run: deno task check:links

.github/workflows/deploy.yml

@@ -22,6 +22,10 @@ jobs:
         uses: denoland/setup-deno@v2
         with:
           cache: true
+          deno-version: canary
+
+      - name: Install dependencies
+        run: deno install
 
       - name: Publish
         run: deno publish

.github/workflows/publish.yml

@@ -0,0 +1,156 @@
+# Agents
+
+## Repository Overview
+
+Fresh is a web framework for Deno built on Preact. This is a **Deno monorepo**
+with workspace members in `packages/*` and `www/`.
+
+### Packages
+
+- **`packages/fresh/`** (`@fresh/core`): Core framework — routing, rendering,
+  islands, build cache, middlewares, and client/server runtime.
+- **`packages/plugin-vite/`** (`@fresh/plugin-vite`): Vite integration plugin
+  with dev server, SSR/client builds, and HMR.
+- **`packages/init/`** (`@fresh/init`): Project scaffolding
+  (`deno create @fresh/init`).
+- **`packages/update/`** (`@fresh/update`): Automated Fresh 1.x to 2.x migration
+  tool using ts-morph for AST transforms.
+- **`packages/build-id/`** (`@fresh/build-id`): Build/deployment ID generation.
+- **`packages/plugin-tailwindcss/`** (`@fresh/plugin-tailwind`): TailwindCSS v4
+  plugin.
+- **`packages/plugin-tailwindcss-v3/`** (`@fresh/plugin-tailwind-v3`): Legacy
+  TailwindCSS v3 plugin.
+- **`packages/examples/`** (`@fresh/examples`): Example components for tests.
+
+### Other directories
+
+- **`www/`**: Documentation website (fresh.deno.dev), built with Fresh + Vite +
+  Tailwind. Has its own routes, islands, and vite.config.ts.
+- **`docs/`**: Markdown documentation organized by version (`latest/`, `1.x/`,
+  `canary/`).
+- **`tools/`**: `release.ts` (version bumping), `check_docs.ts` (doc
+  validation), `check_links.ts` (link checker).
+- **`vendor/`**: Vendored dependencies (`"vendor": true` in deno.json).
+
+## Git Workflow
+
+- To check out a PR branch, use `gh pr checkout <pr-number>`. Do not set up
+  remotes manually.
+- Always run `deno fmt` before pushing.
+- Do not commit `deno.lock` changes unless the PR is specifically about updating
+  dependencies. Lockfile diffs tend to be noisy and environment-specific.
+- **Never amend commits or force push.** Always create new commits.
+
+## Development
+
+- Run `deno task ok` before pushing — it runs the full local CI check (fmt,
+  lint, type check, tests).
+- Run `deno install` if you get missing dependency errors.
+- Tests: `deno task test` (all tests, parallel). Tests use `@std/expect` for
+  assertions and `linkedom` for DOM testing.
+- JSX is configured in "precompile" mode with Preact as the import source.
+
+### Lockfile quirks
+
+The lockfile contains remote specifiers pointing to `refs/heads/main` (e.g.
+`raw.githubusercontent.com/.../refs/heads/main/...`). These hashes go stale when
+upstream pushes. When that happens, manually update the hash in `deno.lock`
+since `deno cache --reload` cannot fix it (see
+https://github.com/denoland/deno/issues/32991).
+
+## Architecture
+
+### Request lifecycle
+
+1. `App.handler()` receives an HTTP request (`app.ts`)
+2. URL is parsed and normalized (double slashes removed)
+3. `UrlPatternRouter.match()` finds the matching route — static routes are
+   checked first via direct `Map` lookup, then dynamic routes via `URLPattern`
+4. A `Context` is created with request, params, and build cache
+5. The middleware chain executes (built backwards as nested closures)
+6. `ctx.render()` composes layouts and app wrapper around the page component
+7. Preact's `renderToString()` generates HTML, with option hooks detecting
+   islands along the way
+8. `FreshScripts` component emits the inline boot script with island imports and
+   serialized props
+9. Response is returned with HTML and `Link` modulepreload headers
+
+### Island architecture
+
+Islands are interactive Preact components that hydrate on the client while the
+rest of the page stays static HTML.
+
+**Server side** (`runtime/server/preact_hooks.ts`):
+
+- Preact's diff hook intercepts every VNode during SSR
+- When a component exists in `buildCache.islandRegistry`, it's wrapped in HTML
+  comment markers: `<!--frsh:island:NAME:PROPSIDX:KEY-->...<!--/frsh:island-->`
+- Island props are collected into a `RenderState.islandProps[]` array
+- JSX element props become **slots** — stored in `<template>` elements and
+  replaced with symbolic references
+
+**Client side** (`runtime/client/reviver.ts`):
+
+- The `boot()` function is called from an inline `<script type="module">`
+- DOM is walked to find `<!--frsh:island:...-->` comment markers
+- Props are deserialized with custom handlers: signals become reactive, slots
+  become VNode references
+- Each island is hydrated via `render(h(component, props), container)` using
+  `scheduler.postTask()` for non-blocking hydration
+
+### Routing
+
+Filesystem paths are converted to URL patterns (`router.ts`, `fs_routes.ts`):
+
+- `/routes/blog/[id].tsx` becomes `/blog/:id`
+- `/routes/blog/[...rest].tsx` becomes `/blog/:rest*`
+- `/routes/(group)/page.tsx` becomes `/page` (groups are transparent)
+- `/routes/[[id]].tsx` becomes `/:id?` (optional segment)
+
+Routes form a **segment tree** (`segments.ts`) where each level accumulates
+middlewares, layouts, and error handlers. When a route matches, the tree is
+walked from root to leaf to build the full middleware chain.
+
+### Build system
+
+Two build paths exist:
+
+- **esbuild-based** (`dev/builder.ts`, `dev/esbuild.ts`): The native Fresh
+  builder. Discovers islands, creates entry points per island + a
+  `fresh-runtime` entry, bundles with esbuild-wasm (splitting, tree-shaking, ESM
+  output). Output goes to `/_fresh/js/{BUILD_ID}/`.
+- **Vite-based** (`plugin-vite/`): Uses Vite's environment API for dual
+  client/SSR builds. Provides the same island discovery and bundling through
+  Vite's plugin system with HMR in dev.
+
+Both produce: separate island bundles, a client runtime entry, static assets
+with content hashing, and a BUILD_ID for cache busting.
+
+Build caches come in two flavors:
+
+- `MemoryBuildCache` / `DiskBuildCache` for development (live rebuilds)
+- `ProdBuildCache` for production (snapshot-based, read from `_fresh/`)
+
+### Partials
+
+`<Partial>` components enable incremental page updates without full reloads.
+They are wrapped with markers (`<!--frsh:partial:{name}:{mode}:{key}-->`) and
+support `replace`, `append`, and `prepend` modes. Elements with `f-client-nav`
+enable client-side navigation that fetches and swaps partials instead of full
+page loads.
+
+## CI
+
+CI runs on every PR against `main` across a matrix of Deno v2.x + canary on
+macOS, Windows, and Ubuntu. Steps:
+
+1. `deno install`
+2. `deno fmt --check` (Ubuntu + v2.x only)
+3. `deno lint` (Ubuntu + v2.x only)
+4. Spell-check via `typos` (Ubuntu + v2.x only)
+5. `deno task check:types` (all platforms)
+6. `deno task test` (all platforms)
+7. `deno task check:docs` (all platforms)
+8. `deno task build-www` (Ubuntu + v2.x only)
+
+Publishing to JSR happens automatically on push to `main` via `deno publish`.

AGENTS.md

@@ -10,7 +10,6 @@ simplicity.
 
 Some stand-out features:
 
-- Just-in-time rendering on the edge.
 - Island based client hydration for maximum interactivity.
 - Zero runtime overhead: no JS is shipped to the client by default.
 - No configuration necessary.
@@ -30,34 +29,33 @@ You can scaffold a new project by running the Fresh init script. To scaffold a
 project run the following:
 
 ```sh
-deno run -A -r https://fresh.deno.dev
+deno create @fresh/init
 ```
 
 Then navigate to the newly created project folder:
 
 ```
-cd deno-fresh-demo
+cd fresh-project
 ```
 
 From within your project folder, start the development server using the
 `deno task` command:
 
 ```
-deno task start
+deno task dev
 ```
 
-Now open http://localhost:8000 in your browser to view the page. You make
+Now open http://localhost:5173 in your browser to view the page. You make
 changes to the project source code and see them reflected in your browser.
 
 To deploy the project to the live internet, you can use
 [Deno Deploy](https://deno.com/deploy):
 
 1. Push your project to GitHub.
-2. [Create a Deno Deploy project](https://dash.deno.com/new).
-3. [Link](https://docs.deno.com/deploy/manual/#deploy-your-project) the Deno
-   Deploy project to the **`main.ts`** file in the root of the created
-   repository.
-4. The project will be deployed to a public $project.deno.dev subdomain.
+2. [Create a Deno Deploy project.](https://console.deno.com/new)
+3. Select your GitHub repository.
+4. The project will be deployed to a public $project.$username.deno.net
+   subdomain with no configuration necessary.
 
 For a more in-depth getting started guide, visit the
 [Getting Started](https://fresh.deno.dev/docs/getting-started) page in the Fresh

README.md

@@ -1,5 +1,6 @@
 {
-  "nodeModulesDir": "auto",
+  "vendor": true,
+  "nodeModulesDir": "manual",
   "workspace": [
     "./packages/*",
     "./www"
@@ -15,6 +16,7 @@
     "check:types": "deno check --allow-import",
     "check:docs": "deno run -A tools/check_docs.ts",
     "ok": "deno fmt --check && deno lint && deno task check:types && deno task test",
+    "check:links": "deno run -A tools/check_links.ts",
     "test:www": "deno test -A www/main_test.*",
     "release": "deno run -A tools/release.ts"
   },
@@ -47,17 +49,20 @@
     "@std/dotenv": "jsr:@std/dotenv@^0.225.5",
     "@std/http": "jsr:@std/http@^1.0.15",
     "@std/uuid": "jsr:@std/uuid@^1.0.7",
+    "@supabase/postgrest-js": "npm:@supabase/postgrest-js@^1.21.4",
+    "@types/mime-db": "npm:@types/mime-db@^1.43.6",
     "@types/node": "npm:@types/node@^24.3.0",
-    "docsearch": "https://esm.sh/@docsearch/js@3.5.2?target=es2020",
+    "@types/pg": "npm:@types/pg@^8.15.5",
+    "@types/prismjs": "npm:@types/prismjs@^1.26.5",
+    "docsearch": "npm:@docsearch/js@^3.5.2",
     "esbuild": "npm:esbuild@0.25.7",
     "esbuild-wasm": "npm:esbuild-wasm@0.25.7",
     "fresh": "jsr:@fresh/core@^2.0.0",
     "mime-db": "npm:mime-db@^1.54.0",
-    "preact": "npm:preact@^10.27.0",
-    "preact-render-to-string": "npm:preact-render-to-string@^6.5.11",
-    "$ga4": "https://raw.githubusercontent.com/denoland/ga4/main/mod.ts",
+    "preact": "npm:preact@^10.28.2",
+    "preact-render-to-string": "npm:preact-render-to-string@^6.6.5",
     "@opentelemetry/api": "npm:@opentelemetry/api@^1.9.0",
-    "@preact/signals": "npm:@preact/signals@^2.2.1",
+    "@preact/signals": "npm:@preact/signals@^2.5.1",
     "@std/encoding": "jsr:@std/encoding@1",
     "@std/fmt": "jsr:@std/fmt@^1.0.7",
     "@std/fs": "jsr:@std/fs@1",
@@ -68,27 +73,28 @@
     "@std/semver": "jsr:@std/semver@1",
     "@std/streams": "jsr:@std/streams@1",
 
-    "@astral/astral": "jsr:@astral/astral@^0.5.3",
+    "@astral/astral": "jsr:@astral/astral@^0.5.5",
     "@marvinh-test/fresh-island": "jsr:@marvinh-test/fresh-island@^0.0.3",
     "linkedom": "npm:linkedom@^0.18.10",
     "@std/async": "jsr:@std/async@^1.0.13",
     "@std/expect": "jsr:@std/expect@^1.0.16",
     "@std/testing": "jsr:@std/testing@^1.0.12",
 
     "@tailwindcss/postcss": "npm:@tailwindcss/postcss@^4.1.10",
-    "rollup": "npm:rollup@^4.50.0",
+    "redis": "npm:redis@^5.8.2",
+    "rollup": "npm:rollup@^4.55.1",
     "tailwindcss": "npm:tailwindcss@^4.1.10",
     "postcss": "npm:postcss@8.5.6",
 
-    "ts-morph": "npm:ts-morph@^26.0.0",
+    "ts-morph": "npm:ts-morph@^27.0.2",
 
     "@std/front-matter": "jsr:@std/front-matter@^1.0.5",
     "github-slugger": "npm:github-slugger@^2.0.0",
-    "imagescript": "https://deno.land/x/imagescript@1.3.0/mod.ts",
+    "imagescript": "jsr:@matmen/imagescript@^1.3.0",
     "marked": "npm:marked@^15.0.11",
     "marked-mangle": "npm:marked-mangle@^1.1.9",
     "prismjs": "npm:prismjs@^1.29.0",
-    "vite": "npm:vite@^7.1.5"
+    "vite": "npm:vite@^7.3.1"
   },
   "compilerOptions": {
     "lib": ["dom", "dom.asynciterable", "deno.ns", "deno.unstable"],