@quilted/create 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,122 @@
 # @quilted/create
 
+## 0.3.3
+
+### Patch Changes
+
+- [#890](https://github.com/lemonmade/quilt/pull/890) [`b0f2334`](https://github.com/lemonmade/quilt/commit/b0f23340945280c951998bf77b3be8b8df13338c) Thanks [@lemonmade](https://github.com/lemonmade)! - Redesign asset loading APIs for better performance and clearer structure.
+
+  ## Breaking changes
+
+  ### `@quilted/assets`: `BrowserAssetsEntry` redesigned
+
+  The `BrowserAssetsEntry` type has been completely restructured. The previous flat `scripts` and `styles` arrays have been replaced with structured `script` and `style` objects that separate the entry asset from its dependencies:
+
+  ```ts
+  // Before
+  interface BrowserAssetsEntry {
+    scripts: Asset[];
+    styles: Asset[];
+  }
+
+  // After
+  interface BrowserAssetsEntry {
+    script?: {
+      asset: Asset;
+      syncDependencies: readonly Asset[];
+      asyncDependencies: readonly Asset[];
+    };
+    style?: {
+      asset: Asset;
+      syncDependencies: readonly Asset[];
+      asyncDependencies: readonly Asset[];
+    };
+  }
+  ```
+
+  This separation enables the renderer to treat the entry script, its preloadable sync dependencies, and its async dependencies differently in the HTML output.
+
+  ### `@quilted/assets`: `BrowserAssets.modules()` return type changed
+
+  `modules()` now returns `readonly BrowserAssetsEntry[]` (one entry per module ID) instead of a single merged `BrowserAssetsEntry`:
+
+  ```ts
+  // Before
+  modules(modules: Iterable<...>, options?): BrowserAssetsEntry;
+
+  // After
+  modules(modules: Iterable<string>, options?): readonly BrowserAssetsEntry[];
+  ```
+
+  ### `@quilted/assets`: `BrowserAssetModuleSelector` removed
+
+  The `BrowserAssetModuleSelector` interface and the `modules` field on `BrowserAssetSelector` have been removed. If you want to get the asset details for modules in addition to the entrypoints, use `BrowserAssets.modules()` instead.
+
+  ### `@quilted/assets`: `AssetBuildManifest` module entry format changed
+
+  `AssetBuildManifest.modules` values changed from `number[]` to the new `AssetBuildModuleEntry` tuple type. The tuple uses positional slots for each asset category and is serialized in JSON as an object with numeric string keys (omitting empty positions):
+
+  ```ts
+  type AssetBuildModuleEntry = [
+    script?: number, // [0] entry JS chunk
+    style?: number, // [1] entry CSS file
+    scriptSync?: number[], // [2] sync JS dependency indices
+    styleSync?: number[], // [3] CSS from sync JS dependencies
+    scriptAsync?: number[], // [4] dynamic JS dependency indices
+    styleAsync?: number[], // [5] CSS from dynamic JS dependencies
+  ];
+  ```
+
+  ### `@quilted/browser`: `BrowserResponseAssets.get()` return type changed
+
+  `get()` now returns `string[]` (module IDs) instead of `BrowserAssetModuleSelector[]`.
+
+  ## New features
+
+  ### `@quilted/preact-browser`: `BrowserApp` class
+
+  A new `BrowserApp` class simplifies constructing and running a browser app. It handles waiting for the `#app` DOM element via `MutationObserver`, which is necessary now that the entry script runs with the `async` attribute:
+
+  ```ts
+  import {BrowserApp} from '@quilted/quilt/browser';
+  import {BrowserAppContext} from '~/context/browser.ts';
+  import {App} from './App.tsx';
+
+  const context = new BrowserAppContext();
+  const app = new BrowserApp(<App context={context} />, {context});
+  await app.hydrate();
+  ```
+
+  ## Render behavior changes
+
+  ### Entry script rendered as `async` module
+
+  The browser entry script is now rendered as `<script type="module" async>` instead of a blocking `<script type="module">`. This means the script no longer blocks HTML parsing, and does not wait for DOMContentLoaded. This change is meant to allow streaming HTML responses to begin executing JavaScript earlier.
+
+  ### Sync dependencies rendered as `modulepreload` links
+
+  Sync JS dependencies (previously rendered as additional `<script type="module">` tags) are now rendered as `<link rel="modulepreload">` hints. This tells the browser to fetch them eagerly without executing them, since the entry script will import them when it runs.
+
+  ### Stylesheets rendered after all script references
+
+  Entry and async stylesheets are now emitted from the `<HTMLTemplate.Assets async />` placeholder, after all script and modulepreload tags. This ensures the stylesheet `<link>` elements appear after all JS references in the HTML.
+
+  ### Asset deduplication across streamed chunks
+
+  Asset deduplication (preventing the same `src`/`href` from appearing more than once) now works across all streamed HTML chunks within a single response, not just within a single placeholder.
+
+## 0.3.2
+
+### Patch Changes
+
+- [`be4e753`](https://github.com/lemonmade/quilt/commit/be4e7532de2bdda83302c2eb8bc2a0a09aeae07e) Thanks [@lemonmade](https://github.com/lemonmade)! - Refactor app template context structure: replace `shared/` directory with `context/` directory
+
+  The `shared/` directory, which used TypeScript declaration merging to build up the `AppContext` interface across multiple files, has been replaced with a `context/` directory that defines the full interface explicitly in a single `types.ts` file. This makes the shape of the application context immediately visible without needing to trace module augmentations.
+
+  The new structure separates each concern into its own file: `types.ts` owns the interface, `navigation.ts` provides the router and route helpers, `preact.ts` holds the Preact context binding, `browser.ts` exports `BrowserAppContext`, and `server.ts` exports `ServerAppContext`. The context classes have been extracted from `browser.tsx` and `server.tsx` into these dedicated files, keeping the entry points lean.
+
+  Navigation is now accessed as `context.navigation.router` instead of `context.router`, grouping router state under a `navigation` namespace. A `browser.css` file has also been added to each app template for global CSS resets.
+
 ## 0.3.1
 
 ### Patch Changes

package/build/esm/node_modules/.pnpm/prompts@2.4.2/node_modules/prompts/dist/prompts.mjs

@@ -1,4 +1,4 @@
-import { __exports as prompts } from '../../../../../../_virtual/prompts2.mjs';
+import { __exports as prompts } from '../../../../../../_virtual/prompts.mjs';
 import { __require as requireElements } from './elements/index.mjs';
 
 var hasRequiredPrompts;

package/build/esm/node_modules/.pnpm/prompts@2.4.2/node_modules/prompts/lib/prompts.mjs

@@ -1,4 +1,4 @@
-import { __exports as prompts } from '../../../../../../_virtual/prompts.mjs';
+import { __exports as prompts } from '../../../../../../_virtual/prompts2.mjs';
 import { __require as requireElements } from './elements/index.mjs';
 
 var hasRequiredPrompts;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@quilted/create",
   "type": "module",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "license": "MIT",
   "repository": {
     "type": "git",

package/templates/app-basic/App.tsx

@@ -7,8 +7,9 @@ import {Frame} from './foundation/frame.ts';
 
 import {Home} from './features/home.ts';
 
-import {AppContextPreact, type AppContext} from './shared/context.ts';
-import {routeWithAppContext} from './shared/navigation.ts';
+import type {AppContext} from './context/types.ts';
+import {AppContextPreact} from './context/preact.ts';
+import {routeWithAppContext} from './context/navigation.ts';
 
 export interface AppProps {
   context: AppContext;
@@ -38,7 +39,11 @@ export function App({context}: AppProps) {
     <AppContextPreact.Provider value={context}>
       <Localization>
         <Head />
-        <Navigation router={context.router} routes={routes} context={context} />
+        <Navigation
+          router={context.navigation.router}
+          routes={routes}
+          context={context}
+        />
       </Localization>
     </AppContextPreact.Provider>
   );

package/templates/app-basic/browser.css

@@ -0,0 +1,10 @@
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+}

package/templates/app-basic/browser.tsx

@@ -1,49 +1,26 @@
-import type {ComponentChild} from 'preact';
-import {hydrate} from '@quilted/quilt/browser';
-import {Router} from '@quilted/quilt/navigation';
+import './browser.css';
 
-import type {AppContext} from '~/shared/context.ts';
-import {App} from './App.tsx';
-
-class BrowserAppContext implements AppContext {
-  readonly router: Router;
-
-  constructor() {
-    this.router = new Router();
-  }
-}
-
-class BrowserApp {
-  /**
-   * The app’s globally-available context.
-   */
-  readonly context: BrowserAppContext;
+import {BrowserApp} from '@quilted/quilt/browser';
 
-  /**
-   * The app’s root JSX element, seeded with the necessary app context.
-   */
-  readonly rendered: ComponentChild;
-
-  constructor() {
-    this.context = new BrowserAppContext();
-    this.rendered = <App context={this.context} />;
-
-    // Makes key parts of the app available in the browser console.
-    //
-    // @example
-    // ```js
-    // // Log the current URL
-    // console.log(globalThis.app.context.router.currentRequest.url);
-    // ```
-    Object.defineProperty(globalThis, 'app', {
-      value: this,
-      enumerable: false,
-      configurable: true,
-      writable: true,
-    });
-  }
-}
-
-const app = new BrowserApp();
+import {BrowserAppContext} from '~/context/browser.ts';
+import {App} from './App.tsx';
 
-hydrate(app.rendered);
+const context = new BrowserAppContext();
+
+const app = new BrowserApp(<App context={context} />, {context});
+
+// Makes key parts of the app available in the browser console.
+//
+// @example
+// ```js
+// // Log the current URL
+// console.log(globalThis.app.context.router.currentRequest.url);
+// ```
+Object.defineProperty(globalThis, 'app', {
+  value: app,
+  enumerable: false,
+  configurable: true,
+  writable: true,
+});
+
+await app.hydrate();

package/templates/app-basic/context/browser.ts

@@ -0,0 +1,10 @@
+import type {AppContext} from './types.ts';
+import {NavigationForApp} from './navigation.ts';
+
+export class BrowserAppContext implements AppContext {
+  readonly navigation: NavigationForApp;
+
+  constructor() {
+    this.navigation = new NavigationForApp();
+  }
+}

package/templates/app-basic/context/navigation.ts

@@ -0,0 +1,17 @@
+import {createContextRouteFunction, Router} from '@quilted/quilt/navigation';
+
+import type {AppContext} from './types.ts';
+
+export interface Navigation {
+  readonly router: Router;
+}
+
+export class NavigationForApp implements Navigation {
+  readonly router: Router;
+
+  constructor(url?: string | URL) {
+    this.router = new Router(url);
+  }
+}
+
+export const routeWithAppContext = createContextRouteFunction<AppContext>();

package/templates/app-basic/{shared/context.ts → context/preact.ts}

@@ -1,6 +1,6 @@
 import {createOptionalContext} from '@quilted/quilt/context';
 
-export interface AppContext {}
+import type {AppContext} from './types.ts';
 
 export const AppContextPreact = createOptionalContext<AppContext>();
 export const useAppContext = AppContextPreact.use;

package/templates/app-basic/context/server.ts

@@ -0,0 +1,10 @@
+import type {AppContext} from './types.ts';
+import {NavigationForApp} from './navigation.ts';
+
+export class ServerAppContext implements AppContext {
+  readonly navigation: NavigationForApp;
+
+  constructor(request: Request) {
+    this.navigation = new NavigationForApp(request.url);
+  }
+}

package/templates/app-basic/context/types.ts

@@ -0,0 +1,5 @@
+import type {Navigation} from './navigation.ts';
+
+export interface AppContext {
+  readonly navigation: Navigation;
+}

package/templates/app-basic/foundation/frame/Frame.module.css

@@ -1,14 +1,3 @@
-*,
-*::before,
-*::after {
-  box-sizing: border-box;
-}
-
-html,
-body {
-  margin: 0;
-}
-
 .Frame {
   padding: 1rem;
 }

package/templates/app-basic/server.tsx

@@ -6,30 +6,21 @@ import {
   PermissionsPolicyHeader,
   StrictTransportSecurityHeader,
 } from '@quilted/quilt/server';
-import {Router} from '@quilted/quilt/navigation';
-
 import Env from 'quilt:module/env';
 import {BrowserAssets} from 'quilt:module/assets';
 
-import type {AppContext} from '~/shared/context.ts';
-
-import {App} from './App.tsx';
-
 const app = new Hono();
 const assets = new BrowserAssets();
 
-class ServerAppContext implements AppContext {
-  readonly router: Router;
-
-  constructor(request: Request) {
-    this.router = new Router(request.url);
-  }
-}
-
 // For all GET requests, render our Preact application.
 app.get('*', async (c) => {
   const request = c.req.raw;
 
+  const [{App}, {ServerAppContext}] = await Promise.all([
+    import('./App.tsx'),
+    import('./context/server.ts'),
+  ]);
+
   const context = new ServerAppContext(request);
 
   const isHttps = request.url.startsWith('https://');

package/templates/app-basic/tests/render/render.tsx

@@ -6,7 +6,7 @@ import {
 import {Navigation, TestRouter} from '@quilted/quilt/navigation/testing';
 import {Localization} from '@quilted/quilt/localize';
 
-import {AppContextPreact} from '~/shared/context.ts';
+import {AppContextPreact} from '~/context/preact.ts';
 
 import {RenderOptions, RenderContext, RenderActions} from './types.ts';
 
@@ -24,11 +24,14 @@ export const renderApp = createRender<
   // authors on the `root.context` property. Context is used to share data between your
   // React tree and your test code, and is ideal for mocking out global context providers.
   context({router = new TestRouter(), browser = new BrowserTestMock()}) {
-    return {router, browser};
+    return {navigation: {router}, browser};
   },
   // Render all of our app-wide context providers around each component under test.
   render(element, context, {locale = 'en'}) {
-    const {router, browser} = context;
+    const {
+      navigation: {router},
+      browser,
+    } = context;
 
     return (
       <AppContextPreact.Provider value={context}>

package/templates/app-basic/tests/render/types.ts

@@ -1,7 +1,7 @@
 import type {TestRouter} from '@quilted/quilt/navigation/testing';
 import type {BrowserTestMock} from '@quilted/quilt/browser/testing';
 
-import type {AppContext} from '~/shared/context.ts';
+import type {AppContext} from '~/context/types.ts';
 
 export interface RenderOptions {
   /**
@@ -27,7 +27,7 @@ export interface RenderContext extends AppContext {
   /**
    * The router used for this component test.
    */
-  readonly router: TestRouter;
+  readonly navigation: {router: TestRouter};
 
   /**
    * The browser environment for this component test.

package/templates/app-basic/tsconfig.json

@@ -3,10 +3,8 @@
   "compilerOptions": {
     "jsxImportSource": "preact",
     "paths": {
-      "~/shared/*": ["./shared/*"],
-      "~/tests/*": ["./tests/*"],
-      "react": ["./node_modules/preact/compat"],
-      "react-dom": ["./node_modules/preact/compat"]
+      "~/context/*": ["./context/*"],
+      "~/tests/*": ["./tests/*"]
     }
   },
   "include": ["**/*"],

package/templates/app-graphql/App.tsx

@@ -8,8 +8,9 @@ import {Frame} from './foundation/frame.ts';
 
 import {Home, homeQuery} from './features/home.ts';
 
-import {AppContextPreact, type AppContext} from './shared/context.ts';
-import {routeWithAppContext} from './shared/navigation.ts';
+import type {AppContext} from './context/types.ts';
+import {AppContextPreact} from './context/preact.ts';
+import {routeWithAppContext} from './context/navigation.ts';
 
 export interface AppProps {
   context: AppContext;
@@ -44,7 +45,7 @@ export function App({context}: AppProps) {
         <Localization>
           <Head />
           <Navigation
-            router={context.router}
+            router={context.navigation.router}
             routes={routes}
             context={context}
           />

package/templates/app-graphql/browser.css

@@ -0,0 +1,10 @@
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+}

package/templates/app-graphql/browser.tsx

@@ -1,60 +1,27 @@
-import type {ComponentChild} from 'preact';
-import {hydrate} from '@quilted/quilt/browser';
-import {Router} from '@quilted/quilt/navigation';
-import {createGraphQLFetch, GraphQLCache} from '@quilted/quilt/graphql';
+import './browser.css';
 
-import type {AppContext} from '~/shared/context.ts';
+import {BrowserApp} from '@quilted/quilt/browser';
 
-import {App} from './App.tsx';
-
-class BrowserAppContext implements AppContext {
-  readonly router: Router;
-  readonly graphql: AppContext['graphql'];
-
-  constructor() {
-    this.router = new Router();
-
-    const graphQLFetch = createGraphQLFetch({url: '/api/graphql'});
-    const graphQLCache = new GraphQLCache({fetch: graphQLFetch});
-
-    this.graphql = {
-      fetch: graphQLFetch,
-      cache: graphQLCache,
-    };
-  }
-}
+import {BrowserAppContext} from '~/context/browser.ts';
 
-class BrowserApp {
-  /**
-   * The app's globally-available context.
-   */
-  readonly context: BrowserAppContext;
-
-  /**
-   * The app's root JSX element, seeded with the necessary app context.
-   */
-  readonly rendered: ComponentChild;
-
-  constructor() {
-    this.context = new BrowserAppContext();
-    this.rendered = <App context={this.context} />;
-
-    // Makes key parts of the app available in the browser console.
-    //
-    // @example
-    // ```js
-    // // Log the current URL
-    // console.log(globalThis.app.context.router.currentRequest.url);
-    // ```
-    Object.defineProperty(globalThis, 'app', {
-      value: this,
-      enumerable: false,
-      configurable: true,
-      writable: true,
-    });
-  }
-}
-
-const app = new BrowserApp();
+import {App} from './App.tsx';
 
-hydrate(app.rendered);
+const context = new BrowserAppContext();
+
+const app = new BrowserApp(<App context={context} />, {context});
+
+// Makes key parts of the app available in the browser console.
+//
+// @example
+// ```js
+// // Log the current URL
+// console.log(globalThis.app.context.navigation.router.currentRequest.url);
+// ```
+Object.defineProperty(globalThis, 'app', {
+  value: app,
+  enumerable: false,
+  configurable: true,
+  writable: true,
+});
+
+await app.hydrate();

package/templates/app-graphql/context/browser.ts

@@ -0,0 +1,21 @@
+import {createGraphQLFetch, GraphQLCache} from '@quilted/quilt/graphql';
+
+import type {AppContext} from './types.ts';
+import {NavigationForApp} from './navigation.ts';
+
+export class BrowserAppContext implements AppContext {
+  readonly navigation: NavigationForApp;
+  readonly graphql: AppContext['graphql'];
+
+  constructor() {
+    this.navigation = new NavigationForApp();
+
+    const graphQLFetch = createGraphQLFetch({url: '/api/graphql'});
+    const graphQLCache = new GraphQLCache({fetch: graphQLFetch});
+
+    this.graphql = {
+      fetch: graphQLFetch,
+      cache: graphQLCache,
+    };
+  }
+}

package/templates/app-graphql/context/navigation.ts

@@ -0,0 +1,17 @@
+import {createContextRouteFunction, Router} from '@quilted/quilt/navigation';
+
+import type {AppContext} from './types.ts';
+
+export interface Navigation {
+  readonly router: Router;
+}
+
+export class NavigationForApp implements Navigation {
+  readonly router: Router;
+
+  constructor(url?: string | URL) {
+    this.router = new Router(url);
+  }
+}
+
+export const routeWithAppContext = createContextRouteFunction<AppContext>();

package/templates/{app-trpc/shared/context.ts → app-graphql/context/preact.ts}

@@ -1,6 +1,6 @@
 import {createOptionalContext} from '@quilted/quilt/context';
 
-export interface AppContext {}
+import type {AppContext} from './types.ts';
 
 export const AppContextPreact = createOptionalContext<AppContext>();
 export const useAppContext = AppContextPreact.use;

package/templates/app-graphql/context/server.ts

@@ -0,0 +1,23 @@
+import {GraphQLCache} from '@quilted/quilt/graphql';
+
+import type {AppContext} from './types.ts';
+import {NavigationForApp} from './navigation.ts';
+
+export class ServerAppContext implements AppContext {
+  readonly navigation: NavigationForApp;
+  readonly graphql: AppContext['graphql'];
+
+  constructor(request: Request) {
+    this.navigation = new NavigationForApp(request.url);
+
+    const graphQLFetch: AppContext['graphql']['fetch'] = async (...args) => {
+      const {performGraphQLOperation} = await import('../server/graphql.ts');
+      return performGraphQLOperation(...args);
+    };
+
+    this.graphql = {
+      fetch: graphQLFetch,
+      cache: new GraphQLCache({fetch: graphQLFetch}),
+    };
+  }
+}

package/templates/app-graphql/context/types.ts

@@ -0,0 +1,10 @@
+import type {Navigation} from './navigation.ts';
+import type {GraphQLFetch, GraphQLCache} from '@quilted/quilt/graphql';
+
+export interface AppContext {
+  readonly navigation: Navigation;
+  readonly graphql: {
+    readonly fetch: GraphQLFetch;
+    readonly cache: GraphQLCache;
+  };
+}

package/templates/app-graphql/server.tsx

@@ -1,5 +1,4 @@
 import {Hono} from 'hono';
-import {Router} from '@quilted/quilt/navigation';
 import {
   renderAppToHTMLResponse,
   CacheControlHeader,
@@ -7,35 +6,13 @@ import {
   PermissionsPolicyHeader,
   StrictTransportSecurityHeader,
 } from '@quilted/quilt/server';
-import {GraphQLCache} from '@quilted/quilt/graphql';
 
 import Env from 'quilt:module/env';
 import {BrowserAssets} from 'quilt:module/assets';
 
-import type {AppContext} from '~/shared/context.ts';
-
 const app = new Hono();
 const assets = new BrowserAssets();
 
-class ServerAppContext implements AppContext {
-  readonly router: Router;
-  readonly graphql: AppContext['graphql'];
-
-  constructor(request: Request) {
-    this.router = new Router(request.url);
-
-    const graphQLFetch: AppContext['graphql']['fetch'] = async (...args) => {
-      const {performGraphQLOperation} = await import('./server/graphql.ts');
-      return performGraphQLOperation(...args);
-    };
-
-    this.graphql = {
-      fetch: graphQLFetch,
-      cache: new GraphQLCache({fetch: graphQLFetch}),
-    };
-  }
-}
-
 // GraphQL API, called from the client
 app.post('/api/graphql', async (c) => {
   const request = c.req.raw;
@@ -55,7 +32,10 @@ app.post('/api/graphql', async (c) => {
 app.get('*', async (c) => {
   const request = c.req.raw;
 
-  const [{App}] = await Promise.all([import('./App.tsx')]);
+  const [{App}, {ServerAppContext}] = await Promise.all([
+    import('./App.tsx'),
+    import('./context/server.ts'),
+  ]);
 
   const context = new ServerAppContext(request);
 

package/templates/app-graphql/tests/render/render.tsx

@@ -9,7 +9,7 @@ import {Navigation, TestRouter} from '@quilted/quilt/navigation/testing';
 import {Localization} from '@quilted/quilt/localize';
 import {GraphQLCache} from '@quilted/quilt/graphql';
 
-import {AppContextPreact} from '~/shared/context.ts';
+import {AppContextPreact} from '~/context/preact.ts';
 
 import {GraphQLTesting, GraphQLController} from '../graphql.ts';
 
@@ -32,18 +32,21 @@ export const renderApp = createRender<
     router = new TestRouter(),
     browser = new BrowserTestMock(),
     graphql = new GraphQLController(),
-    graphQLCache = new GraphQLCache(),
+    graphQLCache = new GraphQLCache({fetch: graphql.fetch}),
   }) {
     return {
-      router,
+      navigation: {router},
       browser,
-      graphql: {fetch: graphql.fetch, cache: graphQLCache},
-      graphQLController: graphql,
+      graphql: {fetch: graphql.fetch, cache: graphQLCache, controller: graphql},
     };
   },
   // Render all of our app-wide context providers around each component under test.
   render(element, context, {locale = 'en'}) {
-    const {router, browser, graphql, graphQLController} = context;
+    const {
+      navigation: {router},
+      browser,
+      graphql,
+    } = context;
 
     return (
       <AppContextPreact.Provider value={context}>
@@ -51,7 +54,7 @@ export const renderApp = createRender<
           <Localization locale={locale}>
             <Navigation router={router}>
               <GraphQLTesting
-                controller={graphQLController}
+                controller={graphql.controller}
                 cache={graphql.cache}
               >
                 <Suspense fallback={null}>{element}</Suspense>
@@ -69,7 +72,7 @@ export const renderApp = createRender<
     // once the data is ready.
 
     await wrapper.act(async () => {
-      await wrapper.context.graphQLController.resolveAll();
+      await wrapper.context.graphql.controller.resolveAll();
     });
   },
 });

package/templates/app-graphql/tests/render/types.ts

@@ -2,7 +2,7 @@ import type {TestRouter} from '@quilted/quilt/navigation/testing';
 import type {BrowserTestMock} from '@quilted/quilt/browser/testing';
 import type {GraphQLCache} from '@quilted/quilt/graphql';
 
-import type {AppContext} from '~/shared/context.ts';
+import type {AppContext} from '~/context/types.ts';
 
 import type {GraphQLController} from '../graphql.ts';
 
@@ -58,7 +58,7 @@ export interface RenderContext extends AppContext {
   /**
    * The router used for this component test.
    */
-  readonly router: TestRouter;
+  readonly navigation: {router: TestRouter};
 
   /**
    * The browser environment for this component test.
@@ -66,9 +66,14 @@ export interface RenderContext extends AppContext {
   readonly browser: BrowserTestMock;
 
   /**
-   * The GraphQL controller used for this component test.
+   * The GraphQL context used for this component test.
    */
-  readonly graphQLController: GraphQLController;
+  readonly graphql: AppContext['graphql'] & {
+    /**
+     * The GraphQL controller used for this component test.
+     */
+    readonly controller: GraphQLController;
+  };
 }
 
 export interface RenderActions extends Record<string, never> {}

package/templates/app-graphql/tsconfig.json

@@ -3,7 +3,7 @@
   "compilerOptions": {
     "jsxImportSource": "preact",
     "paths": {
-      "~/shared/*": ["./shared/*"],
+      "~/context/*": ["./context/*"],
       "~/tests/*": ["./tests/*"],
       "react": ["./node_modules/preact/compat"],
       "react-dom": ["./node_modules/preact/compat"]

package/templates/app-trpc/App.tsx

@@ -9,12 +9,10 @@ import {Frame} from './foundation/frame.ts';
 
 import {Home} from './features/home.ts';
 
-import {trpc} from './shared/trpc.ts';
-import {
-  AppContextPreact,
-  type AppContext as AppContextType,
-} from './shared/context.ts';
-import {routeWithAppContext} from './shared/navigation.ts';
+import {trpc} from './context/trpc.ts';
+import type {AppContext as AppContextType} from './context/types.ts';
+import {AppContextPreact} from './context/preact.ts';
+import {routeWithAppContext} from './context/navigation.ts';
 
 export interface AppProps {
   context: AppContextType;
@@ -47,7 +45,7 @@ export function App({context}: AppProps) {
           <Localization>
             <Head />
             <Navigation
-              router={context.router}
+              router={context.navigation.router}
               routes={routes}
               context={context}
             />

package/templates/app-trpc/browser.css

@@ -0,0 +1,10 @@
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+}

package/templates/app-trpc/browser.tsx

@@ -1,60 +1,27 @@
-import type {ComponentChild} from 'preact';
-import {hydrate} from '@quilted/quilt/browser';
-import {Router} from '@quilted/quilt/navigation';
+import './browser.css';
 
-import {httpBatchLink} from '@trpc/client';
-import {QueryClient} from '@tanstack/react-query';
+import {BrowserApp} from '@quilted/quilt/browser';
 
-import type {AppContext} from '~/shared/context.ts';
-import {trpc} from '~/shared/trpc.ts';
+import {BrowserAppContext} from '~/context/browser.ts';
 
 import {App} from './App.tsx';
 
-class BrowserAppContext implements AppContext {
-  readonly router: Router;
-  readonly trpc: AppContext['trpc'];
-  readonly queryClient: QueryClient;
-
-  constructor() {
-    this.router = new Router();
-    this.queryClient = new QueryClient();
-    this.trpc = trpc.createClient({
-      links: [httpBatchLink({url: new URL('/api', window.location.href).href})],
-    });
-  }
-}
-
-class BrowserApp {
-  /**
-   * The app's globally-available context.
-   */
-  readonly context: BrowserAppContext;
-
-  /**
-   * The app's root JSX element, seeded with the necessary app context.
-   */
-  readonly rendered: ComponentChild;
-
-  constructor() {
-    this.context = new BrowserAppContext();
-    this.rendered = <App context={this.context} />;
-
-    // Makes key parts of the app available in the browser console.
-    //
-    // @example
-    // ```js
-    // // Log the current URL
-    // console.log(globalThis.app.context.router.currentRequest.url);
-    // ```
-    Object.defineProperty(globalThis, 'app', {
-      value: this,
-      enumerable: false,
-      configurable: true,
-      writable: true,
-    });
-  }
-}
-
-const app = new BrowserApp();
-
-hydrate(app.rendered);
+const context = new BrowserAppContext();
+
+const app = new BrowserApp(<App context={context} />, {context});
+
+// Makes key parts of the app available in the browser console.
+//
+// @example
+// ```js
+// // Log the current URL
+// console.log(globalThis.app.context.navigation.router.currentRequest.url);
+// ```
+Object.defineProperty(globalThis, 'app', {
+  value: app,
+  enumerable: false,
+  configurable: true,
+  writable: true,
+});
+
+await app.hydrate();

package/templates/app-trpc/context/browser.ts

@@ -0,0 +1,20 @@
+import {httpBatchLink} from '@trpc/client';
+import {QueryClient} from '@tanstack/react-query';
+
+import type {AppContext} from './types.ts';
+import {NavigationForApp} from './navigation.ts';
+import {trpc} from './trpc.ts';
+
+export class BrowserAppContext implements AppContext {
+  readonly navigation: NavigationForApp;
+  readonly trpc: AppContext['trpc'];
+  readonly queryClient: QueryClient;
+
+  constructor() {
+    this.navigation = new NavigationForApp();
+    this.queryClient = new QueryClient();
+    this.trpc = trpc.createClient({
+      links: [httpBatchLink({url: new URL('/api', window.location.href).href})],
+    });
+  }
+}

package/templates/app-trpc/context/navigation.ts

@@ -0,0 +1,17 @@
+import {createContextRouteFunction, Router} from '@quilted/quilt/navigation';
+
+import type {AppContext} from './types.ts';
+
+export interface Navigation {
+  readonly router: Router;
+}
+
+export class NavigationForApp implements Navigation {
+  readonly router: Router;
+
+  constructor(url?: string | URL) {
+    this.router = new Router(url);
+  }
+}
+
+export const routeWithAppContext = createContextRouteFunction<AppContext>();

package/templates/{app-graphql/shared/context.ts → app-trpc/context/preact.ts}

@@ -1,6 +1,6 @@
 import {createOptionalContext} from '@quilted/quilt/context';
 
-export interface AppContext {}
+import type {AppContext} from './types.ts';
 
 export const AppContextPreact = createOptionalContext<AppContext>();
 export const useAppContext = AppContextPreact.use;

package/templates/app-trpc/context/server.ts

@@ -0,0 +1,18 @@
+import {createDirectClient} from '@quilted/trpc/server';
+import {QueryClient} from '@tanstack/react-query';
+
+import type {AppContext} from './types.ts';
+import {NavigationForApp} from './navigation.ts';
+import {appRouter} from '../trpc.ts';
+
+export class ServerAppContext implements AppContext {
+  readonly navigation: NavigationForApp;
+  readonly trpc: AppContext['trpc'];
+  readonly queryClient: QueryClient;
+
+  constructor(request: Request) {
+    this.navigation = new NavigationForApp(request.url);
+    this.trpc = createDirectClient(appRouter);
+    this.queryClient = new QueryClient();
+  }
+}

package/templates/app-trpc/context/trpc.ts

@@ -0,0 +1,6 @@
+import {createTRPCReact, type CreateTRPCReact} from '@trpc/react-query';
+
+import type {AppRouter} from '../trpc.ts';
+
+export const trpc: CreateTRPCReact<AppRouter, {}> =
+  createTRPCReact<AppRouter>();

package/templates/app-trpc/context/types.ts

@@ -0,0 +1,11 @@
+import type {Navigation} from './navigation.ts';
+import type {TRPCUntypedClient} from '@trpc/client';
+import type {QueryClient} from '@tanstack/react-query';
+
+import type {AppRouter} from '../trpc.ts';
+
+export interface AppContext {
+  readonly navigation: Navigation;
+  readonly trpc: TRPCUntypedClient<AppRouter>;
+  readonly queryClient: QueryClient;
+}

package/templates/app-trpc/features/home/Home.tsx

@@ -1,4 +1,4 @@
-import {trpc} from '~/shared/trpc.ts';
+import {trpc} from '~/context/trpc.ts';
 
 import styles from './Home.module.css';
 

package/templates/app-trpc/server.tsx

@@ -6,34 +6,16 @@ import {
   PermissionsPolicyHeader,
   StrictTransportSecurityHeader,
 } from '@quilted/quilt/server';
-import {Router} from '@quilted/quilt/navigation';
-
 import Env from 'quilt:module/env';
 import {BrowserAssets} from 'quilt:module/assets';
 
-import {createDirectClient} from '@quilted/trpc/server';
 import {fetchRequestHandler} from '@trpc/server/adapters/fetch';
-import {QueryClient} from '@tanstack/react-query';
-
-import type {AppContext} from '~/shared/context.ts';
 
 import {appRouter} from './trpc.ts';
 
 const app = new Hono();
 const assets = new BrowserAssets();
 
-class ServerAppContext implements AppContext {
-  readonly router: Router;
-  readonly trpc: AppContext['trpc'];
-  readonly queryClient: QueryClient;
-
-  constructor(request: Request) {
-    this.router = new Router(request.url);
-    this.trpc = createDirectClient(appRouter);
-    this.queryClient = new QueryClient();
-  }
-}
-
 // TRPC API
 app.all('/api/*', async (c) => {
   const request = c.req.raw;
@@ -49,7 +31,10 @@ app.all('/api/*', async (c) => {
 app.get('*', async (c) => {
   const request = c.req.raw;
 
-  const [{App}] = await Promise.all([import('./App.tsx')]);
+  const [{App}, {ServerAppContext}] = await Promise.all([
+    import('./App.tsx'),
+    import('./context/server.ts'),
+  ]);
 
   const context = new ServerAppContext(request);
 

package/templates/app-trpc/tests/render/render.tsx

@@ -8,8 +8,8 @@ import {Localization} from '@quilted/quilt/localize';
 
 import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
 
-import {trpc} from '~/shared/trpc.ts';
-import {AppContextPreact} from '~/shared/context.ts';
+import {trpc} from '~/context/trpc.ts';
+import {AppContextPreact} from '~/context/preact.ts';
 
 import {RenderOptions, RenderContext, RenderActions} from './types.ts';
 
@@ -28,7 +28,7 @@ export const renderApp = createRender<
   // React tree and your test code, and is ideal for mocking out global context providers.
   context({router = new TestRouter(), browser = new BrowserTestMock()}) {
     return {
-      router,
+      navigation: {router},
       browser,
       trpc: trpc.createClient(),
       queryClient: new QueryClient(),
@@ -36,7 +36,12 @@ export const renderApp = createRender<
   },
   // Render all of our app-wide context providers around each component under test.
   render(element, context, {locale = 'en'}) {
-    const {router, browser, trpc: trpcClient, queryClient} = context;
+    const {
+      navigation: {router},
+      browser,
+      trpc: trpcClient,
+      queryClient,
+    } = context;
 
     return (
       <AppContextPreact.Provider value={context}>

package/templates/app-trpc/tests/render/types.ts

@@ -2,7 +2,7 @@ import type {TestRouter} from '@quilted/quilt/navigation/testing';
 import type {BrowserTestMock} from '@quilted/quilt/browser/testing';
 import type {QueryClient} from '@tanstack/react-query';
 
-import type {AppContext} from '~/shared/context.ts';
+import type {AppContext} from '~/context/types.ts';
 
 export interface RenderOptions {
   /**
@@ -28,7 +28,7 @@ export interface RenderContext extends AppContext {
   /**
    * The router used for this component test.
    */
-  readonly router: TestRouter;
+  readonly navigation: {router: TestRouter};
 
   /**
    * The browser environment for this component test.

package/templates/app-trpc/tsconfig.json

@@ -3,7 +3,7 @@
   "compilerOptions": {
     "jsxImportSource": "preact",
     "paths": {
-      "~/shared/*": ["./shared/*"],
+      "~/context/*": ["./context/*"],
       "~/tests/*": ["./tests/*"],
       "react": ["./node_modules/preact/compat"],
       "react-dom": ["./node_modules/preact/compat"]

package/templates/app-basic/shared/navigation.ts

@@ -1,15 +0,0 @@
-import type {Router} from '@quilted/quilt/navigation';
-import {createContextRouteFunction} from '@quilted/quilt/navigation';
-
-import type {AppContext} from '~/shared/context.ts';
-
-declare module '~/shared/context.ts' {
-  interface AppContext {
-    /**
-     * The router used to control navigation throughout the application.
-     */
-    readonly router: Router;
-  }
-}
-
-export const routeWithAppContext = createContextRouteFunction<AppContext>();

package/templates/app-graphql/shared/graphql.ts

@@ -1,22 +0,0 @@
-import type {GraphQLFetch, GraphQLCache} from '@quilted/quilt/graphql';
-
-declare module '~/shared/context.ts' {
-  interface AppContext {
-    /**
-     * The app’s GraphQL client.
-     */
-    readonly graphql: {
-      /**
-       * A function to perform GraphQL operations.
-       */
-      readonly fetch: GraphQLFetch;
-
-      /**
-       * The app’s GraphQL cache.
-       */
-      readonly cache: GraphQLCache;
-    };
-  }
-}
-
-export {};

package/templates/app-graphql/shared/navigation.ts

@@ -1,15 +0,0 @@
-import type {Router} from '@quilted/quilt/navigation';
-import {createContextRouteFunction} from '@quilted/quilt/navigation';
-
-import type {AppContext} from '~/shared/context.ts';
-
-declare module '~/shared/context.ts' {
-  interface AppContext {
-    /**
-     * The router used to control navigation throughout the application.
-     */
-    readonly router: Router;
-  }
-}
-
-export const routeWithAppContext = createContextRouteFunction<AppContext>();

package/templates/app-trpc/shared/navigation.ts

@@ -1,15 +0,0 @@
-import type {Router} from '@quilted/quilt/navigation';
-import {createContextRouteFunction} from '@quilted/quilt/navigation';
-
-import type {AppContext} from '~/shared/context.ts';
-
-declare module '~/shared/context.ts' {
-  interface AppContext {
-    /**
-     * The router used to control navigation throughout the application.
-     */
-    readonly router: Router;
-  }
-}
-
-export const routeWithAppContext = createContextRouteFunction<AppContext>();

package/templates/app-trpc/shared/trpc.ts

@@ -1,18 +0,0 @@
-import type {TRPCUntypedClient} from '@trpc/client';
-import {createTRPCReact, type CreateTRPCReact} from '@trpc/react-query';
-import type {QueryClient} from '@tanstack/react-query';
-
-// Get access to our app’s router type signature, which will
-// provide strong typing on the queries and mutations we can
-// perform.
-import type {AppRouter} from '../trpc.ts';
-
-export const trpc: CreateTRPCReact<AppRouter, {}> =
-  createTRPCReact<AppRouter>();
-
-declare module '~/shared/context.ts' {
-  interface AppContext {
-    trpc: TRPCUntypedClient<AppRouter>;
-    queryClient: QueryClient;
-  }
-}