@rshono/create 1.0.0-rc.12 → 1.0.0-rc.14

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lasse Tange
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/create-rshono.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-// Thin launcher, kept deliberately old-syntax and dependency-free: it is the one file that has to
-// parse and run on whatever Node the user happens to have. The CLI itself is a bundle — its imports
-// are evaluated before any statement in it, so a version check *inside* it would be too late to
-// produce anything friendlier than a stack trace.
+// Thin launcher, deliberately old-syntax and dependency-free: it is the one file that has to parse and run on
+// whatever Node the user happens to have. A version check inside the CLI bundle would be too late — its imports
+// evaluate before any statement in it.
+//
 // Kept in step with `engines.node` in @rshono/core's manifest, which is what a scaffolded app pins.
 var MINIMUM = [22, 18, 0];
 

package/dist/api.mjs

@@ -52,12 +52,12 @@ __webpack_require__.d(__webpack_exports__, {
 
 ;// CONCATENATED MODULE: ./src/features/combinations.ts
 /**
- * Biome's CSS parser rejects Tailwind's syntax — `@apply` and a `@layer` block are parse errors, not
- * unknown-at-rule warnings — so a project with both needs Biome pointed away from stylesheets. The
- * overlay is a second `biome.json` listed after the first, which is all "later overlay wins" means.
+ * Biome's CSS parser rejects Tailwind's syntax — `@apply` is a parse error, not an unknown-at-rule warning — so
+ * a project with both needs Biome pointed away from stylesheets. The overlay is a second `biome.json` listed
+ * after the first.
  *
- * Narrow on purpose: the alternative was excluding CSS for everybody, which would quietly give up
- * formatting the plain-CSS template that Biome handles perfectly well.
+ * Narrow on purpose: excluding CSS for everybody would give up formatting the plain-CSS template that Biome
+ * handles perfectly well.
  */ const BIOME_TAILWIND = {
     id: 'biome-tailwind',
     overlays: [
@@ -83,14 +83,12 @@ __webpack_require__.d(__webpack_exports__, {
 /**
  * The scripts every app gets, whatever it targets.
  *
- * `start`, `preview` and `deploy` are deliberately not here: each one means something different per
- * platform, so the deploy target contributes its own. The three names are a contract the targets keep,
- * and the reason the README can describe an app it was not written for:
+ * `start`, `preview` and `deploy` are not here: each means something different per platform, so the deploy
+ * target contributes its own. The three names are a contract the targets keep, which is what lets the README
+ * describe an app it was not written for:
  *
- * - **`start`** runs a build that already exists and never makes one — what a host's own start command
- *   calls. Only the target whose build is a server has one.
- * - **`preview`** builds, then runs the result here — for the targets where that is not the same two
- *   commands, because otherwise the production build is unanswerable without deploying it.
+ * - **`start`** runs a build that already exists and never makes one — what a host's own start command calls.
+ * - **`preview`** builds, then runs the result here, so the production build is answerable without deploying.
  * - **`deploy`** builds, then ships it — where the platform has one command that does the shipping.
  */ const BASE_SCRIPTS = {
     dev: 'rshono dev',
@@ -98,9 +96,8 @@ __webpack_require__.d(__webpack_exports__, {
     typecheck: 'tsc --noEmit'
 };
 /**
- * Every script the app gets, in the order they are written: the base ones, then each feature's, in the order
- * the features were selected. The manifest and the README's command table are both this, so neither can
- * document a script the other does not have.
+ * Every script the app gets, in the order they are written: the base ones, then each feature's. The manifest and
+ * the README's command table are both this, so neither can document a script the other lacks.
  */ function buildScripts(features) {
     const scripts = {
         ...BASE_SCRIPTS
@@ -116,9 +113,8 @@ __webpack_require__.d(__webpack_exports__, {
     };
 }
 /**
- * Script names a package manager has a command of its own for. `pnpm deploy` runs pnpm's workspace-deploy
- * command and never looks at the manifest, so printing it would hand somebody a line that quietly does
- * something else. The explicit `run` form is what all four managers accept, so those names get it.
+ * Script names a package manager has a command of its own for: `pnpm deploy` runs pnpm's workspace-deploy and
+ * never looks at the manifest. These get the explicit `run` form, which all four managers accept.
  */ const SHADOWED = new Set([
     'deploy'
 ]);
@@ -126,10 +122,9 @@ __webpack_require__.d(__webpack_exports__, {
     return `${SHADOWED.has(script) ? `${pm.name} run` : pm.run} ${script}`;
 }
 /**
- * The README's command table: one line per script, with the command to type and a one-line gloss.
- *
- * A script whose feature supplies no `scriptHelp` is left out and covered by the "package.json has the
- * rest" line — that is how a formatter's `format:check` stays out of a table about running the app.
+ * The README's command table: one line per script, with the command to type and a one-line gloss. A script whose
+ * feature supplies no `scriptHelp` is left out — that is how `format:check` stays out of a table about running
+ * the app — and covered by the line pointing at `package.json`.
  */ function scriptTable(answers, features, pm) {
     const help = baseScriptHelp(answers.deploy);
     for (const feature of features)Object.assign(help, feature.scriptHelp);
@@ -138,31 +133,28 @@ __webpack_require__.d(__webpack_exports__, {
     return documented.map((name)=>`${invoke(pm, name).padEnd(width)}  # ${help[name]}`).join('\n');
 }
 /**
- * The command that gets this app into production, as a sentence — the README's deploy step, and the same
- * choice the closing summary makes, so the two cannot name different commands.
+ * The command that gets this app into production, as a sentence — the README's deploy step and the closing
+ * summary's, so the two cannot name different commands.
  *
  * Read off the scripts rather than the target, so a target that gains a `deploy` gains the sentence with it.
- * `start` is the answer where there is no `deploy`: it ships nothing itself, but it is what the host runs.
  */ function deployStep(features, pm) {
     const scripts = buildScripts(features);
     if (scripts.deploy) return `\`${invoke(pm, 'deploy')}\` does the build and the upload in one step.`;
     if (scripts.start) return `\`${invoke(pm, 'start')}\` runs that build wherever you host it, and never makes one.`;
-    // Every branch names a script the app has, so a target that contributes none of the three still reads true.
     if (scripts.preview) return `\`${invoke(pm, 'preview')}\` runs the build here, so you can check it first.`;
     return `\`${invoke(pm, 'build')}\` produces it; getting it there is yours to script.`;
 }
 
 ;// CONCATENATED MODULE: ./src/generated/framework.ts
 // GENERATED by scripts/codegen.mjs from packages/core — do not edit. Run `pnpm --filter @rshono/create codegen`.
-/** The framework release a scaffolded app is pinned to: this package and rshono ship together. */ const RSHONO_VERSION = '1.0.0-rc.12';
+/** The framework release a scaffolded app is pinned to: this package and rshono ship together. */ const RSHONO_VERSION = '1.0.0-rc.14';
 /**
- * The Node range rshono itself declares, restated in every scaffolded app's `engines` — so a CI image
- * or a contributor on an older Node hears it from their package manager rather than from a stack trace.
+ * The Node range rshono declares, restated in every scaffolded app's `engines` — so a CI image or a contributor
+ * on an older Node hears it from their package manager rather than from a stack trace.
  */ const NODE_ENGINE = '>=22.18.0';
 /**
- * The dependency versions rshono is tested against, copied from its own manifest. Exact where it is
- * exact — React's RSC internals are coupled across builds, and a generated app has no workspace
- * overrides to fall back on.
+ * The dependency versions rshono is tested against, copied from its own manifest. Exact where it is exact:
+ * React's RSC internals are coupled across builds, and a generated app has no workspace overrides.
  */ const FRAMEWORK_DEPS = {
     hono: '^4.12.31',
     react: '19.2.8',
@@ -195,14 +187,12 @@ __webpack_require__.d(__webpack_exports__, {
 /** Passed straight through, so everything generated from the framework reaches the rest of the package here. */ 
 /** The framework range a scaffolded app gets. The two packages are released together, so this is ours. */ const RSHONO_RANGE = `^${RSHONO_VERSION}`;
 /**
- * Versions for the optional tooling the features can add — the one place in this package where a
- * dependency range is typed out by hand, because none of these are things the framework itself
- * declares. Everything a *scaffolded app* needs to run rshono comes from {@link FRAMEWORK_DEPS},
- * which is generated from rshono's own manifest and must not be edited here.
+ * Versions for the optional tooling the features can add — the one place in this package where a range is typed
+ * by hand, because the framework declares none of these. Everything a scaffolded app needs to *run* rshono comes
+ * from {@link FRAMEWORK_DEPS}, generated from rshono's own manifest.
  *
- * Ranges are caret, not exact: these are the app's own dev tools, and a scaffold made six months from
- * now should pick up their patch releases rather than pinning whatever was current the day this file
- * was last touched.
+ * Caret ranges, not exact: these are the app's own dev tools, and a scaffold made six months from now should
+ * pick up their patch releases.
  */ const TOOL_VERSIONS = {
     tailwindcss: '^4.3.3',
     '@tailwindcss/postcss': '^4.3.3',
@@ -214,23 +204,20 @@ __webpack_require__.d(__webpack_exports__, {
     oxlint: '^1.76.0',
     oxfmt: '^0.61.0',
     eslint: '^10.8.0',
-    // ESLint's own recommended JavaScript rules, which typescript-eslint layers on top of rather than
-    // replaces, and the rules of hooks — the one class of React mistake no type checker sees.
+    // ESLint's recommended JavaScript rules, which typescript-eslint layers on rather than replaces, and the rules
+    // of hooks — the one class of React mistake no type checker sees.
     '@eslint/js': '^10.0.1',
     'typescript-eslint': '^8.65.0',
     'eslint-plugin-react-hooks': '^7.1.1',
     wrangler: '^4.115.0'
 };
 /**
- * The TypeScript an ESLint app pins, in place of the framework's own — the one deliberate exception to
+ * The TypeScript an ESLint app pins in place of the framework's own — the one deliberate exception to
  * {@link FRAMEWORK_DEPS}.
  *
- * typescript-eslint reads TypeScript's compiler API directly rather than through a stable interface,
- * so it accepts `typescript >=4.8.4 <6.1.0` and nothing above; `~6.0.3` is the newest that satisfies
- * it. rshono's declarations compile the same under either, which is what makes this an app's business
- * and not the framework's.
- *
- * When upstream widens the range, this constant and the ESLint feature's use of it are what to delete.
+ * typescript-eslint reads TypeScript's compiler API directly, so it accepts `>=4.8.4 <6.1.0` and nothing above;
+ * `~6.0.3` is the newest that satisfies it. rshono's declarations compile the same under either, which is what
+ * makes this the app's business. When upstream widens its range, this constant is what to delete.
  */ const ESLINT_TYPESCRIPT = '~6.0.3';
 
 ;// CONCATENATED MODULE: ./src/features/deploy.ts
@@ -239,22 +226,17 @@ __webpack_require__.d(__webpack_exports__, {
 /**
  * What a deploy target adds beyond the `deploy` line in `rshono.config.ts`, which the template carries.
  *
- * Deliberately thin: the framework arranges its own output for every platform, and `rshono build`
- * writes the one platform config that has to exist (`wrangler.jsonc`) if the project has none — a second
- * copy generated here would only go stale. So a target contributes the commands that run and ship the
- * build, the CLI they need, the directories to gitignore, and a note for the step no command covers.
- *
- * What the three script names promise is documented once, above `BASE_SCRIPTS` in `scripts.ts`. Only `node`
- * has a `start`, because `rshono start` refuses a bundle built for anywhere else, and it needs no `preview`:
- * `build` then `start` already is one.
+ * Thin on purpose: the framework arranges its own output for every platform, and `rshono build` writes the one
+ * platform config that has to exist. So a target contributes the commands that run and ship the build, the CLI
+ * they need, the directories to gitignore, and a note for the step no command covers.
  *
- * `pm` is here because two things have to be spelled for the app's package manager — the runner that fetches
- * the uninstalled Vercel CLI ({@link PackageManager.dlx}), and every command in {@link Feature.platformSetup}.
+ * What the three script names promise is documented above `BASE_SCRIPTS` in `scripts.ts`. Only `node` has a
+ * `start` — `rshono start` refuses a bundle built for anywhere else — and it needs no `preview`, since `build`
+ * then `start` already is one.
  */ function deployFeatures(pm) {
     const build = invoke(pm, 'build');
     return {
-        // Where a Node build goes from here is a Dockerfile or a process manager, neither of which this can
-        // guess — so the target contributes only the command that runs what was built.
+        // Where a Node build goes next is a Dockerfile or a process manager, neither of which this can guess.
         node: {
             id: 'deploy-node',
             scripts: {
@@ -277,16 +259,14 @@ __webpack_require__.d(__webpack_exports__, {
             devDependencies: {
                 wrangler: TOOL_VERSIONS.wrangler
             },
-            // The only two install scripts a scaffolded app can end up with, and wrangler brings both. Each
-            // one merely picks the platform binary out of the optional dependency that already carries it, so
-            // neither needs to run — `workerd --version` and `esbuild --version` both answer without it.
+            // The only two install scripts a scaffolded app can end up with, and wrangler brings both. Each merely
+            // picks the platform binary out of the optional dependency already carrying it, so neither needs to run.
             allowBuilds: {
                 esbuild: false,
                 workerd: false
             },
-            // `wrangler dev` is the one preview that runs the code in the runtime it will actually run in:
-            // workerd, not Node, serving the assets the build assembled. Both scripts read the wrangler.jsonc the
-            // build wrote, so nothing here has to know where the bundle or the assets went.
+            // `wrangler dev` is the one preview that runs the code in workerd rather than Node. Both scripts read the
+            // wrangler.jsonc the build wrote, so nothing here has to know where the bundle went.
             scripts: {
                 preview: 'rshono build && wrangler dev',
                 deploy: 'rshono build && wrangler deploy'
@@ -308,9 +288,8 @@ __webpack_require__.d(__webpack_exports__, {
         },
         vercel: {
             id: 'deploy-vercel',
-            // `--prod` because the script is called `deploy`: without it the CLI uploads to a throwaway preview
-            // URL, which is a useful thing to have but not what the word means. The local `preview` is a Node
-            // build run here — the platform has no way to run its own prebuilt output on your machine.
+            // `--prod` because the script is called `deploy`: without it the CLI uploads to a throwaway preview URL.
+            // `preview` is a Node build run here — the platform cannot run its own prebuilt output on your machine.
             scripts: {
                 preview: 'rshono build --deploy node && rshono start',
                 deploy: `rshono build && ${pm.dlx} vercel deploy --prebuilt --prod`
@@ -336,8 +315,7 @@ __webpack_require__.d(__webpack_exports__, {
         },
         'aws-lambda': {
             id: 'deploy-aws-lambda',
-            // No CLI to wrap, and no upload this could guess at. `preview` still applies — the bundle is a Node
-            // handler, so it runs here.
+            // No CLI to wrap and no upload to guess at, but `preview` still applies: the bundle is a Node handler.
             scripts: {
                 preview: 'rshono build --deploy node && rshono start'
             },
@@ -349,8 +327,9 @@ __webpack_require__.d(__webpack_exports__, {
             ],
             platformSetup: [
                 `There is no settings page here; the upload is yours to script. A job needs \`${pm.name} install && ${build}\`,`,
-                'then the function package: `dist/`, plus `node_modules` for any dependency of your own, which the server',
-                'bundle leaves external.'
+                'then the function package: `dist/` and nothing else, with the handler at `dist/server/main.mjs`. Your',
+                'dependencies are compiled into the bundle for this target, so no `node_modules` is uploaded — which also',
+                'means a native addon fails the build here rather than the deploy.'
             ].join('\n')
         }
     };
@@ -362,14 +341,11 @@ function deployFeature(target, pm) {
 ;// CONCATENATED MODULE: ./src/features/quality.ts
 
 /**
- * The formatter and linter features. Biome answers to both slots and appears once — `selectFeatures`
- * deduplicates by `id`, so `formatter: 'biome', linter: 'biome'` contributes one set of files, one
- * dependency and one pair of scripts.
+ * The formatter and linter features. Biome answers to both slots and appears once, because `selectFeatures`
+ * deduplicates by `id`.
  *
- * A formatter brings `format:check` beside `format`, because the writing half and the CI half want
- * different exit-code behaviour: `format` rewrites files, `format:check` fails instead. A linter brings
- * `lint:fix` beside `lint`, for the same reason in the other direction — `lint` is already the failing
- * one. Biome adds a `check` of its own, which is the pair of them in a single pass.
+ * Each brings a pair of scripts, since the writing half and the CI half want different exit codes: `format`
+ * rewrites and `format:check` fails, `lint:fix` rewrites and `lint` fails. Biome's `check` is both in one pass.
  */ const PRETTIER = {
     id: 'prettier',
     overlays: [
@@ -410,11 +386,10 @@ const OXLINT = {
     }
 };
 /**
- * The one feature that changes a dependency the framework otherwise decides: typescript-eslint cannot
- * be installed alongside the TypeScript rshono is tested against, so an ESLint app pins the newest one
- * its peer range accepts (see {@link ESLINT_TYPESCRIPT}). Its rules are type-aware — the reason to
- * reach for ESLint over a syntax-only linter — so the config it ships hands the parser the whole
- * program rather than linting file by file.
+ * The one feature that changes a dependency the framework otherwise decides: typescript-eslint cannot be
+ * installed alongside the TypeScript rshono is tested against, so an ESLint app pins the newest its peer range
+ * accepts (see {@link ESLINT_TYPESCRIPT}). Its rules are type-aware — the reason to reach for ESLint at all —
+ * so the config it ships hands the parser the whole program.
  */ const ESLINT = {
     id: 'eslint',
     overlays: [
@@ -430,6 +405,12 @@ const OXLINT = {
     scripts: {
         lint: 'eslint .',
         'lint:fix': 'eslint . --fix'
+    },
+    // The pin is invisible from the command line, and its consequence is not: the rules reason about the
+    // program through an older compiler than the one that builds it, so a fix can produce code `tsc` rejects.
+    // The generated eslint.config.mjs explains why; the README's table is where someone reads what to type.
+    scriptHelp: {
+        'lint:fix': 'apply what it can — then run typecheck, see eslint.config.mjs'
     }
 };
 const BIOME = {
@@ -470,13 +451,12 @@ function linterFeature(linter) {
 ;// CONCATENATED MODULE: ./src/features/styling.ts
 
 /**
- * Tailwind is a PostCSS plugin and nothing more, which is the whole of this feature: four packages,
- * plus an overlay carrying `postcss.config.mjs`, an `rshono.config.ts` whose `rspack` hook puts
- * postcss-loader in front of the CSS parser, a Tailwind entry stylesheet, and the two views rewritten
- * in utilities.
+ * Tailwind is a PostCSS plugin and nothing more, which is the whole of this feature: four packages, plus an
+ * overlay carrying `postcss.config.mjs`, an `rshono.config.ts` whose `rspack` hook puts postcss-loader in front
+ * of the CSS parser, a Tailwind entry stylesheet, and the two views rewritten in utilities.
  *
- * `postcss` and `postcss-loader` are the app's dependencies rather than the framework's — rshono
- * compiles CSS natively, so an app that does not want a plugin chain does not install one.
+ * `postcss` is the app's dependency rather than the framework's: rshono compiles CSS natively, so an app that
+ * wants no plugin chain installs none.
  */ const TAILWIND = {
     id: 'tailwind',
     overlays: [
@@ -499,12 +479,11 @@ function stylingFeature(styling) {
 
 
 /**
- * The features a set of answers selects, in application order — so an overlay listed later wins a file
- * both of them ship. Deduplicated by `id`, which is what lets one feature answer two questions (Biome
- * is both the formatter and the linter) without contributing twice.
+ * The features a set of answers selects, in application order — so an overlay listed later wins a file both
+ * ship. Deduplicated by `id`, which is what lets one feature answer two questions (Biome is both formatter and
+ * linter) without contributing twice.
  *
- * `pm` reaches the deploy target because one script has to name the runner that fetches an uninstalled
- * CLI; nothing else here depends on which package manager the app is for.
+ * `pm` reaches the deploy target because one script has to name the runner that fetches an uninstalled CLI.
  */ function selectFeatures(answers, pm) {
     const selected = [
         deployFeature(answers.deploy, pm),
@@ -526,9 +505,8 @@ function stylingFeature(styling) {
 ;// CONCATENATED MODULE: ./src/options.ts
 
 /*
- * The names each option accepts, spelled once. The types below are derived from them, the CLI validates
- * its flags against them and prints them in `--help`, and `pm.ts` recognises a package manager by them
- * — so a name added here reaches all three without a second list to remember.
+ * The names each option accepts, spelled once: the types below are derived from them, the CLI validates its
+ * flags against them and prints them in `--help`, and `pm.ts` recognises a package manager by them.
  */ const FORMATTER_NAMES = [
     'prettier',
     'biome',
@@ -589,14 +567,13 @@ const QUALITY_PRESETS = [
     }
 ];
 /**
- * Turns whatever the user typed into a name npm will accept, or returns `null` when nothing usable is
- * left. Lowercasing and replacing runs of invalid characters covers the ordinary cases (`My App`,
- * `my_app`); a scoped name is kept intact, since `@scope/name` is legal.
+ * Turns whatever the user typed into a name npm will accept, or `null` when nothing usable is left.
+ * Lowercasing and replacing runs of invalid characters covers the ordinary cases (`My App`, `my_app`).
  */ function toPackageName(input) {
     const trimmed = input.trim().replace(/^\.\/+/, '').replace(/\/+$/, '');
     if (!trimmed || trimmed === '.') return null;
-    // A scoped name is a name, not a path: `@scope/pkg` stays whole rather than becoming `pkg`. Anything
-    // else is a path, and the last segment is the one that names the project.
+    // A scoped name is a name, not a path: `@scope/pkg` stays whole. Anything else is a path, whose last
+    // segment names the project.
     const scoped = /^@[^\\/]+[\\/][^\\/]+$/.test(trimmed);
     const base = scoped ? trimmed : trimmed.split(/[\\/]/).filter(Boolean).pop() ?? '';
     if (!base) return null;
@@ -630,15 +607,11 @@ function sorted(record) {
     return Object.fromEntries(Object.entries(record).sort(([a], [b])=>a < b ? -1 : 1));
 }
 /**
- * pnpm's settings for the new app, written only when a feature has something to put in them. `null`
- * means there is nothing to say, so no file is written.
- *
- * It exists for one field, `allowBuilds`. pnpm fails an install — and every `pnpm dev` after it —
- * until the project has said whether a dependency's install script should run. Nothing rshono itself
- * installs has one, so most apps get no file; the packages that do (wrangler's esbuild and workerd)
- * declare their answer on the feature that brings them.
+ * pnpm's settings for the new app, or `null` when no feature has anything to put in them.
  *
- * A file rather than a `pnpm` key in `package.json`, which pnpm 11 no longer reads.
+ * It exists for one field, `allowBuilds`: pnpm fails an install until the project has said whether a
+ * dependency's install script should run. Nothing rshono installs has one, so most apps get no file. A file
+ * rather than a `pnpm` key in `package.json`, which pnpm 11 no longer reads.
  */ function buildPnpmSettings(features) {
     const allowBuilds = {};
     for (const feature of features)Object.assign(allowBuilds, feature.allowBuilds);
@@ -654,10 +627,8 @@ function sorted(record) {
     ].join('\n');
 }
 /**
- * Assembles `package.json` from the answers and whatever the selected features contribute.
- *
- * Dependencies are sorted by name and scripts keep the order {@link buildScripts} gives them — so two runs
- * with the same answers produce byte-identical output, which is what makes the manifest snapshot-testable.
+ * Assembles `package.json` from the answers and whatever the selected features contribute. Dependencies are
+ * sorted and scripts keep {@link buildScripts}'s order, so two runs with the same answers are byte-identical.
  */ function buildPackageJson(answers, features, pm) {
     const dependencies = {
         '@rshono/core': RSHONO_RANGE,
@@ -687,8 +658,8 @@ function sorted(record) {
         dependencies: sorted(dependencies),
         devDependencies: sorted(devDependencies)
     };
-    // Only when the environment told us the exact version: `packageManager` pins the tool for Corepack,
-    // and a guess at the version is worse than leaving the field out.
+    // Only when the environment told us the exact version: this field pins the tool for Corepack, and a guess is
+    // worse than leaving it out.
     if (pm.version) manifest.packageManager = `${pm.name}@${pm.version}`;
     const ordered = Object.fromEntries(FIELD_ORDER.filter((field)=>field in manifest).map((field)=>[
             field,
@@ -700,25 +671,22 @@ function sorted(record) {
 ;// CONCATENATED MODULE: ./src/render.ts
 
 /**
- * `{{NAME}}`, deliberately not `__NAME__`: templates are real files that real tools run over, and in
- * markdown `__NAME__` *is* strong emphasis — Prettier rewrites it to `**NAME**` and the token stops
- * matching. `{{…}}` means nothing to any format these templates are written in.
+ * `{{NAME}}`, not `__NAME__`: in markdown the latter is strong emphasis, so Prettier rewrites it to `**NAME**`
+ * and the token stops matching. `{{…}}` means nothing to any format these templates are written in.
  */ const TOKEN_PATTERN = /\{\{[A-Z][A-Z\d_]*\}\}/g;
 function tokensFor(answers, features, pm) {
     return {
         '{{PROJECT_NAME}}': answers.packageName,
         '{{DEPLOY_TARGET}}': answers.deploy,
-        // Derived from the features rather than the answers, because all three are about the scripts the app
-        // actually got: its command table, the one command that ships it, and what its platform asks for.
+        // From the features rather than the answers, because all three are about the scripts the app actually got.
         '{{SCRIPT_TABLE}}': scriptTable(answers, features, pm),
         '{{DEPLOY_STEP}}': deployStep(features, pm),
         '{{PLATFORM_SETUP}}': features.map((feature)=>feature.platformSetup ?? '').join('')
     };
 }
 /**
- * Substitutes tokens, and throws on one it doesn't know — a typo in a template would otherwise ship a
- * literal `{{PORJECT_NAME}}` into somebody's new app, which no test of the generator's logic would
- * catch.
+ * Substitutes tokens, and throws on one it does not know — a typo in a template would otherwise ship a literal
+ * `{{PORJECT_NAME}}` into somebody's new app, which no test of the generator's logic would catch.
  */ function render(contents, tokens, source) {
     return contents.replace(TOKEN_PATTERN, (token)=>{
         const value = tokens[token];
@@ -748,11 +716,9 @@ function readTemplateDir(dir) {
     return files;
 }
 /**
- * `_gitignore` → `.gitignore`, and so on for every dotfile.
- *
- * npm strips a literal `.gitignore` out of a published tarball, so a template cannot contain one — it
- * would exist in the repo, pass every local test, and be missing from the package everybody installs.
- * Applies to the basename only, so `src/lib/_x.ts` is a dotfile but `templates/_x/y.ts` is not.
+ * `_gitignore` → `.gitignore`, and so on for every dotfile: npm strips a literal `.gitignore` out of a
+ * published tarball, so a template that contained one would pass every local test and be missing from the
+ * package everybody installs. The basename only, so `templates/_x/y.ts` is left alone.
  */ function undotted(path) {
     const segments = path.split(posix.sep);
     const name = segments.pop();
@@ -761,19 +727,16 @@ function readTemplateDir(dir) {
         name.startsWith('_') ? `.${name.slice(1)}` : name
     ].join(posix.sep);
 }
-/**
- * A feature's `.gitignore` lines, appended under a heading naming it — so somebody reading the file six
- * months later can tell why `.wrangler/` is in there.
- */ function appendGitignore(existing, features) {
+/** A feature's `.gitignore` lines, under a heading naming it — so a reader can tell why `.wrangler/` is there. */ function appendGitignore(existing, features) {
     const additions = features.filter((feature)=>feature.gitignore?.length);
     if (additions.length === 0) return existing;
     const blocks = additions.map((feature)=>`\n# ${feature.id}\n${feature.gitignore.join('\n')}\n`);
     return existing + blocks.join('');
 }
 /**
- * Turns answers into the exact set of files to write, without touching the target directory — the
- * decisions and the I/O are separated so the whole matrix of answers can be asserted on in a test, and
- * so `--dry-run` is the same code path minus the last step.
+ * Turns answers into the exact set of files to write, without touching the target directory. Separating the
+ * decisions from the I/O is what lets a test assert on the whole matrix of answers, and makes `--dry-run` the
+ * same code path minus the last step.
  */ function plan_plan(answers, pm) {
     const features = selectFeatures(answers, pm);
     const tokens = tokensFor(answers, features, pm);
@@ -847,11 +810,9 @@ function packageManager(name, version) {
     };
 }
 /**
- * Which package manager invoked us. Every one of them sets `npm_config_user_agent` on the process it
- * spawns — `pnpm/11.9.0 npm/? node/v22.14.0 darwin arm64` — so `pnx @rshono/create` scaffolds a pnpm
- * project without asking, and the exact version comes along for the `packageManager` field.
- *
- * Falls back to npm, which is also what a bare `node bin/create-rshono.mjs` gets.
+ * Which package manager invoked us. All four set `npm_config_user_agent` on the process they spawn — `pnpm/11.9.0
+ * npm/? node/v22.14.0 darwin arm64` — so `pnx @rshono/create` scaffolds a pnpm project without asking, exact
+ * version included. Falls back to npm, which is also what a bare `node bin/create-rshono.mjs` gets.
  */ function detectPackageManager(userAgent = process.env.npm_config_user_agent) {
     const [spec] = (userAgent ?? '').split(' ');
     const [name, version] = (spec ?? '').split('/');
@@ -859,9 +820,8 @@ function packageManager(name, version) {
     return packageManager('npm');
 }
 /**
- * Runs the install, streaming its output. `shell: true` on Windows because npm, pnpm and yarn are all
- * `.cmd` shims there, which `spawn` cannot execute directly — and with a shell involved the arguments
- * are all fixed strings from the tables above, never anything the user typed.
+ * Runs the install, streaming its output. `shell: true` on Windows, where npm, pnpm and yarn are `.cmd` shims
+ * `spawn` cannot execute directly — safe because every argument is a fixed string from the tables above.
  */ function runInstall(pm, cwd) {
     return run(pm, pm.install, cwd);
 }
@@ -877,10 +837,7 @@ function run(pm, args, cwd) {
 ;// CONCATENATED MODULE: ./src/write.ts
 
 
-/**
- * Files that do not make a directory "occupied". A user who ran `git init` or opened the folder in an
- * editor before scaffolding has not put anything in it that we would overwrite.
- */ const IGNORED_ENTRIES = new Set([
+/** Files that do not make a directory "occupied": a `git init` or an editor has put nothing there to overwrite. */ const IGNORED_ENTRIES = new Set([
     '.git',
     '.DS_Store',
     '.idea',
@@ -888,12 +845,9 @@ function run(pm, args, cwd) {
     'Thumbs.db'
 ]);
 /**
- * What is already at the target path, ignoring the entries a fresh clone or an editor leaves behind —
- * which is what decides whether scaffolding into it is safe.
- *
- * A path that does not exist yet is no conflict. A path that exists and is *not* a directory throws
- * rather than reporting an empty list, since `--force` should not write into one either — otherwise
- * `create-rshono README.md` gets as far as `mkdir` before failing on a raw ENOTDIR.
+ * What is already at the target path, ignoring the entries a fresh clone or an editor leaves behind — which is
+ * what decides whether scaffolding into it is safe. A path that does not exist yet is no conflict; one that
+ * exists and is not a directory throws, since `--force` should not write into it either.
  */ function conflictingEntries(dir) {
     const stats = statSync(dir, {
         throwIfNoEntry: false
@@ -903,8 +857,8 @@ function run(pm, args, cwd) {
     return readdirSync(dir).filter((entry)=>!IGNORED_ENTRIES.has(entry));
 }
 /**
- * Writes the plan. Directories are created as needed, and files are written with the plan's own
- * ordering so a failure part-way through leaves something a person can make sense of.
+ * Writes the plan, creating directories as needed and keeping the plan's own ordering — so a failure part-way
+ * through leaves something a person can make sense of.
  */ function writePlan(plan, targetDir) {
     mkdirSync(targetDir, {
         recursive: true

package/dist/cli.mjs

@@ -2906,8 +2906,8 @@ function hasGit(cwd) {
     ], cwd).ok;
 }
 /**
- * Whether the new project already sits inside somebody's repository — scaffolding into a monorepo or an
- * existing checkout, where a nested repo would be a surprise rather than a convenience.
+ * Whether the new project already sits inside somebody's repository — a monorepo or an existing checkout, where
+ * a nested repo would be a surprise rather than a convenience.
  */ function isInsideRepo(cwd) {
     const { ok, stdout } = git_git([
         'rev-parse',
@@ -2916,11 +2916,9 @@ function hasGit(cwd) {
     return ok && stdout === 'true';
 }
 /**
- * Initializes a repository and makes the first commit.
- *
- * `initialized` rather than `committed` is the honest answer when the commit itself fails, which it does
- * on a machine with no `user.email` configured. That is not a reason to fail the scaffold — the files
- * are all there and staged — so the caller reports it and moves on.
+ * Initializes a repository and makes the first commit. `initialized` is the honest answer when the commit itself
+ * fails, as it does with no `user.email` configured — the files are all there and staged, so the caller reports
+ * it and moves on rather than failing the scaffold.
  */ function initRepo(cwd) {
     const init = git_git([
         'init',
@@ -2943,15 +2941,14 @@ function hasGit(cwd) {
 
 ;// CONCATENATED MODULE: ./src/generated/framework.ts
 // GENERATED by scripts/codegen.mjs from packages/core — do not edit. Run `pnpm --filter @rshono/create codegen`.
-/** The framework release a scaffolded app is pinned to: this package and rshono ship together. */ const RSHONO_VERSION = '1.0.0-rc.12';
+/** The framework release a scaffolded app is pinned to: this package and rshono ship together. */ const RSHONO_VERSION = '1.0.0-rc.14';
 /**
- * The Node range rshono itself declares, restated in every scaffolded app's `engines` — so a CI image
- * or a contributor on an older Node hears it from their package manager rather than from a stack trace.
+ * The Node range rshono declares, restated in every scaffolded app's `engines` — so a CI image or a contributor
+ * on an older Node hears it from their package manager rather than from a stack trace.
  */ const NODE_ENGINE = '>=22.18.0';
 /**
- * The dependency versions rshono is tested against, copied from its own manifest. Exact where it is
- * exact — React's RSC internals are coupled across builds, and a generated app has no workspace
- * overrides to fall back on.
+ * The dependency versions rshono is tested against, copied from its own manifest. Exact where it is exact:
+ * React's RSC internals are coupled across builds, and a generated app has no workspace overrides.
  */ const FRAMEWORK_DEPS = {
     hono: '^4.12.31',
     react: '19.2.8',
@@ -2982,9 +2979,8 @@ function hasGit(cwd) {
 ;// CONCATENATED MODULE: ./src/options.ts
 
 /*
- * The names each option accepts, spelled once. The types below are derived from them, the CLI validates
- * its flags against them and prints them in `--help`, and `pm.ts` recognises a package manager by them
- * — so a name added here reaches all three without a second list to remember.
+ * The names each option accepts, spelled once: the types below are derived from them, the CLI validates its
+ * flags against them and prints them in `--help`, and `pm.ts` recognises a package manager by them.
  */ const FORMATTER_NAMES = [
     'prettier',
     'biome',
@@ -3045,14 +3041,13 @@ const QUALITY_PRESETS = [
     }
 ];
 /**
- * Turns whatever the user typed into a name npm will accept, or returns `null` when nothing usable is
- * left. Lowercasing and replacing runs of invalid characters covers the ordinary cases (`My App`,
- * `my_app`); a scoped name is kept intact, since `@scope/name` is legal.
+ * Turns whatever the user typed into a name npm will accept, or `null` when nothing usable is left.
+ * Lowercasing and replacing runs of invalid characters covers the ordinary cases (`My App`, `my_app`).
  */ function toPackageName(input) {
     const trimmed = input.trim().replace(/^\.\/+/, '').replace(/\/+$/, '');
     if (!trimmed || trimmed === '.') return null;
-    // A scoped name is a name, not a path: `@scope/pkg` stays whole rather than becoming `pkg`. Anything
-    // else is a path, and the last segment is the one that names the project.
+    // A scoped name is a name, not a path: `@scope/pkg` stays whole. Anything else is a path, whose last
+    // segment names the project.
     const scoped = /^@[^\\/]+[\\/][^\\/]+$/.test(trimmed);
     const base = scoped ? trimmed : trimmed.split(/[\\/]/).filter(Boolean).pop() ?? '';
     if (!base) return null;
@@ -3066,12 +3061,12 @@ const QUALITY_PRESETS = [
 
 ;// CONCATENATED MODULE: ./src/features/combinations.ts
 /**
- * Biome's CSS parser rejects Tailwind's syntax — `@apply` and a `@layer` block are parse errors, not
- * unknown-at-rule warnings — so a project with both needs Biome pointed away from stylesheets. The
- * overlay is a second `biome.json` listed after the first, which is all "later overlay wins" means.
+ * Biome's CSS parser rejects Tailwind's syntax — `@apply` is a parse error, not an unknown-at-rule warning — so
+ * a project with both needs Biome pointed away from stylesheets. The overlay is a second `biome.json` listed
+ * after the first.
  *
- * Narrow on purpose: the alternative was excluding CSS for everybody, which would quietly give up
- * formatting the plain-CSS template that Biome handles perfectly well.
+ * Narrow on purpose: excluding CSS for everybody would give up formatting the plain-CSS template that Biome
+ * handles perfectly well.
  */ const BIOME_TAILWIND = {
     id: 'biome-tailwind',
     overlays: [
@@ -3097,14 +3092,12 @@ const QUALITY_PRESETS = [
 /**
  * The scripts every app gets, whatever it targets.
  *
- * `start`, `preview` and `deploy` are deliberately not here: each one means something different per
- * platform, so the deploy target contributes its own. The three names are a contract the targets keep,
- * and the reason the README can describe an app it was not written for:
+ * `start`, `preview` and `deploy` are not here: each means something different per platform, so the deploy
+ * target contributes its own. The three names are a contract the targets keep, which is what lets the README
+ * describe an app it was not written for:
  *
- * - **`start`** runs a build that already exists and never makes one — what a host's own start command
- *   calls. Only the target whose build is a server has one.
- * - **`preview`** builds, then runs the result here — for the targets where that is not the same two
- *   commands, because otherwise the production build is unanswerable without deploying it.
+ * - **`start`** runs a build that already exists and never makes one — what a host's own start command calls.
+ * - **`preview`** builds, then runs the result here, so the production build is answerable without deploying.
  * - **`deploy`** builds, then ships it — where the platform has one command that does the shipping.
  */ const BASE_SCRIPTS = {
     dev: 'rshono dev',
@@ -3112,9 +3105,8 @@ const QUALITY_PRESETS = [
     typecheck: 'tsc --noEmit'
 };
 /**
- * Every script the app gets, in the order they are written: the base ones, then each feature's, in the order
- * the features were selected. The manifest and the README's command table are both this, so neither can
- * document a script the other does not have.
+ * Every script the app gets, in the order they are written: the base ones, then each feature's. The manifest and
+ * the README's command table are both this, so neither can document a script the other lacks.
  */ function buildScripts(features) {
     const scripts = {
         ...BASE_SCRIPTS
@@ -3130,9 +3122,8 @@ const QUALITY_PRESETS = [
     };
 }
 /**
- * Script names a package manager has a command of its own for. `pnpm deploy` runs pnpm's workspace-deploy
- * command and never looks at the manifest, so printing it would hand somebody a line that quietly does
- * something else. The explicit `run` form is what all four managers accept, so those names get it.
+ * Script names a package manager has a command of its own for: `pnpm deploy` runs pnpm's workspace-deploy and
+ * never looks at the manifest. These get the explicit `run` form, which all four managers accept.
  */ const SHADOWED = new Set([
     'deploy'
 ]);
@@ -3140,10 +3131,9 @@ const QUALITY_PRESETS = [
     return `${SHADOWED.has(script) ? `${pm.name} run` : pm.run} ${script}`;
 }
 /**
- * The README's command table: one line per script, with the command to type and a one-line gloss.
- *
- * A script whose feature supplies no `scriptHelp` is left out and covered by the "package.json has the
- * rest" line — that is how a formatter's `format:check` stays out of a table about running the app.
+ * The README's command table: one line per script, with the command to type and a one-line gloss. A script whose
+ * feature supplies no `scriptHelp` is left out — that is how `format:check` stays out of a table about running
+ * the app — and covered by the line pointing at `package.json`.
  */ function scriptTable(answers, features, pm) {
     const help = baseScriptHelp(answers.deploy);
     for (const feature of features)Object.assign(help, feature.scriptHelp);
@@ -3152,16 +3142,14 @@ const QUALITY_PRESETS = [
     return documented.map((name)=>`${invoke(pm, name).padEnd(width)}  # ${help[name]}`).join('\n');
 }
 /**
- * The command that gets this app into production, as a sentence — the README's deploy step, and the same
- * choice the closing summary makes, so the two cannot name different commands.
+ * The command that gets this app into production, as a sentence — the README's deploy step and the closing
+ * summary's, so the two cannot name different commands.
  *
  * Read off the scripts rather than the target, so a target that gains a `deploy` gains the sentence with it.
- * `start` is the answer where there is no `deploy`: it ships nothing itself, but it is what the host runs.
  */ function deployStep(features, pm) {
     const scripts = buildScripts(features);
     if (scripts.deploy) return `\`${invoke(pm, 'deploy')}\` does the build and the upload in one step.`;
     if (scripts.start) return `\`${invoke(pm, 'start')}\` runs that build wherever you host it, and never makes one.`;
-    // Every branch names a script the app has, so a target that contributes none of the three still reads true.
     if (scripts.preview) return `\`${invoke(pm, 'preview')}\` runs the build here, so you can check it first.`;
     return `\`${invoke(pm, 'build')}\` produces it; getting it there is yours to script.`;
 }
@@ -3171,14 +3159,12 @@ const QUALITY_PRESETS = [
 /** Passed straight through, so everything generated from the framework reaches the rest of the package here. */ 
 /** The framework range a scaffolded app gets. The two packages are released together, so this is ours. */ const RSHONO_RANGE = `^${RSHONO_VERSION}`;
 /**
- * Versions for the optional tooling the features can add — the one place in this package where a
- * dependency range is typed out by hand, because none of these are things the framework itself
- * declares. Everything a *scaffolded app* needs to run rshono comes from {@link FRAMEWORK_DEPS},
- * which is generated from rshono's own manifest and must not be edited here.
+ * Versions for the optional tooling the features can add — the one place in this package where a range is typed
+ * by hand, because the framework declares none of these. Everything a scaffolded app needs to *run* rshono comes
+ * from {@link FRAMEWORK_DEPS}, generated from rshono's own manifest.
  *
- * Ranges are caret, not exact: these are the app's own dev tools, and a scaffold made six months from
- * now should pick up their patch releases rather than pinning whatever was current the day this file
- * was last touched.
+ * Caret ranges, not exact: these are the app's own dev tools, and a scaffold made six months from now should
+ * pick up their patch releases.
  */ const TOOL_VERSIONS = {
     tailwindcss: '^4.3.3',
     '@tailwindcss/postcss': '^4.3.3',
@@ -3190,23 +3176,20 @@ const QUALITY_PRESETS = [
     oxlint: '^1.76.0',
     oxfmt: '^0.61.0',
     eslint: '^10.8.0',
-    // ESLint's own recommended JavaScript rules, which typescript-eslint layers on top of rather than
-    // replaces, and the rules of hooks — the one class of React mistake no type checker sees.
+    // ESLint's recommended JavaScript rules, which typescript-eslint layers on rather than replaces, and the rules
+    // of hooks — the one class of React mistake no type checker sees.
     '@eslint/js': '^10.0.1',
     'typescript-eslint': '^8.65.0',
     'eslint-plugin-react-hooks': '^7.1.1',
     wrangler: '^4.115.0'
 };
 /**
- * The TypeScript an ESLint app pins, in place of the framework's own — the one deliberate exception to
+ * The TypeScript an ESLint app pins in place of the framework's own — the one deliberate exception to
  * {@link FRAMEWORK_DEPS}.
  *
- * typescript-eslint reads TypeScript's compiler API directly rather than through a stable interface,
- * so it accepts `typescript >=4.8.4 <6.1.0` and nothing above; `~6.0.3` is the newest that satisfies
- * it. rshono's declarations compile the same under either, which is what makes this an app's business
- * and not the framework's.
- *
- * When upstream widens the range, this constant and the ESLint feature's use of it are what to delete.
+ * typescript-eslint reads TypeScript's compiler API directly, so it accepts `>=4.8.4 <6.1.0` and nothing above;
+ * `~6.0.3` is the newest that satisfies it. rshono's declarations compile the same under either, which is what
+ * makes this the app's business. When upstream widens its range, this constant is what to delete.
  */ const ESLINT_TYPESCRIPT = '~6.0.3';
 
 ;// CONCATENATED MODULE: ./src/features/deploy.ts
@@ -3215,22 +3198,17 @@ const QUALITY_PRESETS = [
 /**
  * What a deploy target adds beyond the `deploy` line in `rshono.config.ts`, which the template carries.
  *
- * Deliberately thin: the framework arranges its own output for every platform, and `rshono build`
- * writes the one platform config that has to exist (`wrangler.jsonc`) if the project has none — a second
- * copy generated here would only go stale. So a target contributes the commands that run and ship the
- * build, the CLI they need, the directories to gitignore, and a note for the step no command covers.
+ * Thin on purpose: the framework arranges its own output for every platform, and `rshono build` writes the one
+ * platform config that has to exist. So a target contributes the commands that run and ship the build, the CLI
+ * they need, the directories to gitignore, and a note for the step no command covers.
  *
- * What the three script names promise is documented once, above `BASE_SCRIPTS` in `scripts.ts`. Only `node`
- * has a `start`, because `rshono start` refuses a bundle built for anywhere else, and it needs no `preview`:
- * `build` then `start` already is one.
- *
- * `pm` is here because two things have to be spelled for the app's package manager — the runner that fetches
- * the uninstalled Vercel CLI ({@link PackageManager.dlx}), and every command in {@link Feature.platformSetup}.
+ * What the three script names promise is documented above `BASE_SCRIPTS` in `scripts.ts`. Only `node` has a
+ * `start` — `rshono start` refuses a bundle built for anywhere else — and it needs no `preview`, since `build`
+ * then `start` already is one.
  */ function deployFeatures(pm) {
     const build = invoke(pm, 'build');
     return {
-        // Where a Node build goes from here is a Dockerfile or a process manager, neither of which this can
-        // guess — so the target contributes only the command that runs what was built.
+        // Where a Node build goes next is a Dockerfile or a process manager, neither of which this can guess.
         node: {
             id: 'deploy-node',
             scripts: {
@@ -3253,16 +3231,14 @@ const QUALITY_PRESETS = [
             devDependencies: {
                 wrangler: TOOL_VERSIONS.wrangler
             },
-            // The only two install scripts a scaffolded app can end up with, and wrangler brings both. Each
-            // one merely picks the platform binary out of the optional dependency that already carries it, so
-            // neither needs to run — `workerd --version` and `esbuild --version` both answer without it.
+            // The only two install scripts a scaffolded app can end up with, and wrangler brings both. Each merely
+            // picks the platform binary out of the optional dependency already carrying it, so neither needs to run.
             allowBuilds: {
                 esbuild: false,
                 workerd: false
             },
-            // `wrangler dev` is the one preview that runs the code in the runtime it will actually run in:
-            // workerd, not Node, serving the assets the build assembled. Both scripts read the wrangler.jsonc the
-            // build wrote, so nothing here has to know where the bundle or the assets went.
+            // `wrangler dev` is the one preview that runs the code in workerd rather than Node. Both scripts read the
+            // wrangler.jsonc the build wrote, so nothing here has to know where the bundle went.
             scripts: {
                 preview: 'rshono build && wrangler dev',
                 deploy: 'rshono build && wrangler deploy'
@@ -3284,9 +3260,8 @@ const QUALITY_PRESETS = [
         },
         vercel: {
             id: 'deploy-vercel',
-            // `--prod` because the script is called `deploy`: without it the CLI uploads to a throwaway preview
-            // URL, which is a useful thing to have but not what the word means. The local `preview` is a Node
-            // build run here — the platform has no way to run its own prebuilt output on your machine.
+            // `--prod` because the script is called `deploy`: without it the CLI uploads to a throwaway preview URL.
+            // `preview` is a Node build run here — the platform cannot run its own prebuilt output on your machine.
             scripts: {
                 preview: 'rshono build --deploy node && rshono start',
                 deploy: `rshono build && ${pm.dlx} vercel deploy --prebuilt --prod`
@@ -3312,8 +3287,7 @@ const QUALITY_PRESETS = [
         },
         'aws-lambda': {
             id: 'deploy-aws-lambda',
-            // No CLI to wrap, and no upload this could guess at. `preview` still applies — the bundle is a Node
-            // handler, so it runs here.
+            // No CLI to wrap and no upload to guess at, but `preview` still applies: the bundle is a Node handler.
             scripts: {
                 preview: 'rshono build --deploy node && rshono start'
             },
@@ -3325,8 +3299,9 @@ const QUALITY_PRESETS = [
             ],
             platformSetup: [
                 `There is no settings page here; the upload is yours to script. A job needs \`${pm.name} install && ${build}\`,`,
-                'then the function package: `dist/`, plus `node_modules` for any dependency of your own, which the server',
-                'bundle leaves external.'
+                'then the function package: `dist/` and nothing else, with the handler at `dist/server/main.mjs`. Your',
+                'dependencies are compiled into the bundle for this target, so no `node_modules` is uploaded — which also',
+                'means a native addon fails the build here rather than the deploy.'
             ].join('\n')
         }
     };
@@ -3338,14 +3313,11 @@ function deployFeature(target, pm) {
 ;// CONCATENATED MODULE: ./src/features/quality.ts
 
 /**
- * The formatter and linter features. Biome answers to both slots and appears once — `selectFeatures`
- * deduplicates by `id`, so `formatter: 'biome', linter: 'biome'` contributes one set of files, one
- * dependency and one pair of scripts.
+ * The formatter and linter features. Biome answers to both slots and appears once, because `selectFeatures`
+ * deduplicates by `id`.
  *
- * A formatter brings `format:check` beside `format`, because the writing half and the CI half want
- * different exit-code behaviour: `format` rewrites files, `format:check` fails instead. A linter brings
- * `lint:fix` beside `lint`, for the same reason in the other direction — `lint` is already the failing
- * one. Biome adds a `check` of its own, which is the pair of them in a single pass.
+ * Each brings a pair of scripts, since the writing half and the CI half want different exit codes: `format`
+ * rewrites and `format:check` fails, `lint:fix` rewrites and `lint` fails. Biome's `check` is both in one pass.
  */ const PRETTIER = {
     id: 'prettier',
     overlays: [
@@ -3386,11 +3358,10 @@ const OXLINT = {
     }
 };
 /**
- * The one feature that changes a dependency the framework otherwise decides: typescript-eslint cannot
- * be installed alongside the TypeScript rshono is tested against, so an ESLint app pins the newest one
- * its peer range accepts (see {@link ESLINT_TYPESCRIPT}). Its rules are type-aware — the reason to
- * reach for ESLint over a syntax-only linter — so the config it ships hands the parser the whole
- * program rather than linting file by file.
+ * The one feature that changes a dependency the framework otherwise decides: typescript-eslint cannot be
+ * installed alongside the TypeScript rshono is tested against, so an ESLint app pins the newest its peer range
+ * accepts (see {@link ESLINT_TYPESCRIPT}). Its rules are type-aware — the reason to reach for ESLint at all —
+ * so the config it ships hands the parser the whole program.
  */ const ESLINT = {
     id: 'eslint',
     overlays: [
@@ -3406,6 +3377,12 @@ const OXLINT = {
     scripts: {
         lint: 'eslint .',
         'lint:fix': 'eslint . --fix'
+    },
+    // The pin is invisible from the command line, and its consequence is not: the rules reason about the
+    // program through an older compiler than the one that builds it, so a fix can produce code `tsc` rejects.
+    // The generated eslint.config.mjs explains why; the README's table is where someone reads what to type.
+    scriptHelp: {
+        'lint:fix': 'apply what it can — then run typecheck, see eslint.config.mjs'
     }
 };
 const BIOME = {
@@ -3446,13 +3423,12 @@ function linterFeature(linter) {
 ;// CONCATENATED MODULE: ./src/features/styling.ts
 
 /**
- * Tailwind is a PostCSS plugin and nothing more, which is the whole of this feature: four packages,
- * plus an overlay carrying `postcss.config.mjs`, an `rshono.config.ts` whose `rspack` hook puts
- * postcss-loader in front of the CSS parser, a Tailwind entry stylesheet, and the two views rewritten
- * in utilities.
+ * Tailwind is a PostCSS plugin and nothing more, which is the whole of this feature: four packages, plus an
+ * overlay carrying `postcss.config.mjs`, an `rshono.config.ts` whose `rspack` hook puts postcss-loader in front
+ * of the CSS parser, a Tailwind entry stylesheet, and the two views rewritten in utilities.
  *
- * `postcss` and `postcss-loader` are the app's dependencies rather than the framework's — rshono
- * compiles CSS natively, so an app that does not want a plugin chain does not install one.
+ * `postcss` is the app's dependency rather than the framework's: rshono compiles CSS natively, so an app that
+ * wants no plugin chain installs none.
  */ const TAILWIND = {
     id: 'tailwind',
     overlays: [
@@ -3475,12 +3451,11 @@ function stylingFeature(styling) {
 
 
 /**
- * The features a set of answers selects, in application order — so an overlay listed later wins a file
- * both of them ship. Deduplicated by `id`, which is what lets one feature answer two questions (Biome
- * is both the formatter and the linter) without contributing twice.
+ * The features a set of answers selects, in application order — so an overlay listed later wins a file both
+ * ship. Deduplicated by `id`, which is what lets one feature answer two questions (Biome is both formatter and
+ * linter) without contributing twice.
  *
- * `pm` reaches the deploy target because one script has to name the runner that fetches an uninstalled
- * CLI; nothing else here depends on which package manager the app is for.
+ * `pm` reaches the deploy target because one script has to name the runner that fetches an uninstalled CLI.
  */ function selectFeatures(answers, pm) {
     const selected = [
         deployFeature(answers.deploy, pm),
@@ -3517,15 +3492,11 @@ function sorted(record) {
     return Object.fromEntries(Object.entries(record).sort(([a], [b])=>a < b ? -1 : 1));
 }
 /**
- * pnpm's settings for the new app, written only when a feature has something to put in them. `null`
- * means there is nothing to say, so no file is written.
- *
- * It exists for one field, `allowBuilds`. pnpm fails an install — and every `pnpm dev` after it —
- * until the project has said whether a dependency's install script should run. Nothing rshono itself
- * installs has one, so most apps get no file; the packages that do (wrangler's esbuild and workerd)
- * declare their answer on the feature that brings them.
+ * pnpm's settings for the new app, or `null` when no feature has anything to put in them.
  *
- * A file rather than a `pnpm` key in `package.json`, which pnpm 11 no longer reads.
+ * It exists for one field, `allowBuilds`: pnpm fails an install until the project has said whether a
+ * dependency's install script should run. Nothing rshono installs has one, so most apps get no file. A file
+ * rather than a `pnpm` key in `package.json`, which pnpm 11 no longer reads.
  */ function buildPnpmSettings(features) {
     const allowBuilds = {};
     for (const feature of features)Object.assign(allowBuilds, feature.allowBuilds);
@@ -3541,10 +3512,8 @@ function sorted(record) {
     ].join('\n');
 }
 /**
- * Assembles `package.json` from the answers and whatever the selected features contribute.
- *
- * Dependencies are sorted by name and scripts keep the order {@link buildScripts} gives them — so two runs
- * with the same answers produce byte-identical output, which is what makes the manifest snapshot-testable.
+ * Assembles `package.json` from the answers and whatever the selected features contribute. Dependencies are
+ * sorted and scripts keep {@link buildScripts}'s order, so two runs with the same answers are byte-identical.
  */ function buildPackageJson(answers, features, pm) {
     const dependencies = {
         '@rshono/core': RSHONO_RANGE,
@@ -3574,8 +3543,8 @@ function sorted(record) {
         dependencies: sorted(dependencies),
         devDependencies: sorted(devDependencies)
     };
-    // Only when the environment told us the exact version: `packageManager` pins the tool for Corepack,
-    // and a guess at the version is worse than leaving the field out.
+    // Only when the environment told us the exact version: this field pins the tool for Corepack, and a guess is
+    // worse than leaving it out.
     if (pm.version) manifest.packageManager = `${pm.name}@${pm.version}`;
     const ordered = Object.fromEntries(FIELD_ORDER.filter((field)=>field in manifest).map((field)=>[
             field,
@@ -3587,25 +3556,22 @@ function sorted(record) {
 ;// CONCATENATED MODULE: ./src/render.ts
 
 /**
- * `{{NAME}}`, deliberately not `__NAME__`: templates are real files that real tools run over, and in
- * markdown `__NAME__` *is* strong emphasis — Prettier rewrites it to `**NAME**` and the token stops
- * matching. `{{…}}` means nothing to any format these templates are written in.
+ * `{{NAME}}`, not `__NAME__`: in markdown the latter is strong emphasis, so Prettier rewrites it to `**NAME**`
+ * and the token stops matching. `{{…}}` means nothing to any format these templates are written in.
  */ const TOKEN_PATTERN = /\{\{[A-Z][A-Z\d_]*\}\}/g;
 function tokensFor(answers, features, pm) {
     return {
         '{{PROJECT_NAME}}': answers.packageName,
         '{{DEPLOY_TARGET}}': answers.deploy,
-        // Derived from the features rather than the answers, because all three are about the scripts the app
-        // actually got: its command table, the one command that ships it, and what its platform asks for.
+        // From the features rather than the answers, because all three are about the scripts the app actually got.
         '{{SCRIPT_TABLE}}': scriptTable(answers, features, pm),
         '{{DEPLOY_STEP}}': deployStep(features, pm),
         '{{PLATFORM_SETUP}}': features.map((feature)=>feature.platformSetup ?? '').join('')
     };
 }
 /**
- * Substitutes tokens, and throws on one it doesn't know — a typo in a template would otherwise ship a
- * literal `{{PORJECT_NAME}}` into somebody's new app, which no test of the generator's logic would
- * catch.
+ * Substitutes tokens, and throws on one it does not know — a typo in a template would otherwise ship a literal
+ * `{{PORJECT_NAME}}` into somebody's new app, which no test of the generator's logic would catch.
  */ function render(contents, tokens, source) {
     return contents.replace(TOKEN_PATTERN, (token)=>{
         const value = tokens[token];
@@ -3635,11 +3601,9 @@ function readTemplateDir(dir) {
     return files;
 }
 /**
- * `_gitignore` → `.gitignore`, and so on for every dotfile.
- *
- * npm strips a literal `.gitignore` out of a published tarball, so a template cannot contain one — it
- * would exist in the repo, pass every local test, and be missing from the package everybody installs.
- * Applies to the basename only, so `src/lib/_x.ts` is a dotfile but `templates/_x/y.ts` is not.
+ * `_gitignore` → `.gitignore`, and so on for every dotfile: npm strips a literal `.gitignore` out of a
+ * published tarball, so a template that contained one would pass every local test and be missing from the
+ * package everybody installs. The basename only, so `templates/_x/y.ts` is left alone.
  */ function undotted(path) {
     const segments = path.split(posix.sep);
     const name = segments.pop();
@@ -3648,19 +3612,16 @@ function readTemplateDir(dir) {
         name.startsWith('_') ? `.${name.slice(1)}` : name
     ].join(posix.sep);
 }
-/**
- * A feature's `.gitignore` lines, appended under a heading naming it — so somebody reading the file six
- * months later can tell why `.wrangler/` is in there.
- */ function appendGitignore(existing, features) {
+/** A feature's `.gitignore` lines, under a heading naming it — so a reader can tell why `.wrangler/` is there. */ function appendGitignore(existing, features) {
     const additions = features.filter((feature)=>feature.gitignore?.length);
     if (additions.length === 0) return existing;
     const blocks = additions.map((feature)=>`\n# ${feature.id}\n${feature.gitignore.join('\n')}\n`);
     return existing + blocks.join('');
 }
 /**
- * Turns answers into the exact set of files to write, without touching the target directory — the
- * decisions and the I/O are separated so the whole matrix of answers can be asserted on in a test, and
- * so `--dry-run` is the same code path minus the last step.
+ * Turns answers into the exact set of files to write, without touching the target directory. Separating the
+ * decisions from the I/O is what lets a test assert on the whole matrix of answers, and makes `--dry-run` the
+ * same code path minus the last step.
  */ function plan_plan(answers, pm) {
     const features = selectFeatures(answers, pm);
     const tokens = tokensFor(answers, features, pm);
@@ -3732,11 +3693,9 @@ function packageManager(name, version) {
     };
 }
 /**
- * Which package manager invoked us. Every one of them sets `npm_config_user_agent` on the process it
- * spawns — `pnpm/11.9.0 npm/? node/v22.14.0 darwin arm64` — so `pnx @rshono/create` scaffolds a pnpm
- * project without asking, and the exact version comes along for the `packageManager` field.
- *
- * Falls back to npm, which is also what a bare `node bin/create-rshono.mjs` gets.
+ * Which package manager invoked us. All four set `npm_config_user_agent` on the process they spawn — `pnpm/11.9.0
+ * npm/? node/v22.14.0 darwin arm64` — so `pnx @rshono/create` scaffolds a pnpm project without asking, exact
+ * version included. Falls back to npm, which is also what a bare `node bin/create-rshono.mjs` gets.
  */ function detectPackageManager(userAgent = process.env.npm_config_user_agent) {
     const [spec] = (userAgent ?? '').split(' ');
     const [name, version] = (spec ?? '').split('/');
@@ -3744,9 +3703,8 @@ function packageManager(name, version) {
     return packageManager('npm');
 }
 /**
- * Runs the install, streaming its output. `shell: true` on Windows because npm, pnpm and yarn are all
- * `.cmd` shims there, which `spawn` cannot execute directly — and with a shell involved the arguments
- * are all fixed strings from the tables above, never anything the user typed.
+ * Runs the install, streaming its output. `shell: true` on Windows, where npm, pnpm and yarn are `.cmd` shims
+ * `spawn` cannot execute directly — safe because every argument is a fixed string from the tables above.
  */ function runInstall(pm, cwd) {
     return run(pm, pm.install, cwd);
 }
@@ -3764,9 +3722,8 @@ function run(pm, args, cwd) {
 
 
 /**
- * The two halves of the closing line, in the words of the app's own scripts: what produces something
- * shippable, and where it goes from there. The target with no command to give keeps the framework's hint,
- * which is a sentence about the platform rather than something to type.
+ * The two halves of the closing line, in the words of the app's own scripts: what produces something shippable,
+ * and where it goes from there. A target with no command to give falls back to the framework's hint.
  */ function productionSteps(answers, plan, pm) {
     const scripts = buildScripts(plan.features);
     const check = scripts.preview ? `${invoke(pm, 'preview')} to run the production build` : `${pm.run} build`;
@@ -3774,8 +3731,8 @@ function run(pm, args, cwd) {
     return `${check}, and ${ship}`;
 }
 /**
- * What to do next, in the order to do it — the last thing the user reads, and for most people the only
- * documentation they will read today. `installed` decides whether the install step is still theirs.
+ * What to do next, in the order to do it — the last thing the user reads. `installed` decides whether the install
+ * step is still theirs.
  */ function nextSteps(answers, plan, pm, options) {
     const steps = [];
     if (options.directory !== '.') steps.push(`cd ${options.directory}`);
@@ -3810,10 +3767,7 @@ function run(pm, args, cwd) {
 ;// CONCATENATED MODULE: ./src/write.ts
 
 
-/**
- * Files that do not make a directory "occupied". A user who ran `git init` or opened the folder in an
- * editor before scaffolding has not put anything in it that we would overwrite.
- */ const IGNORED_ENTRIES = new Set([
+/** Files that do not make a directory "occupied": a `git init` or an editor has put nothing there to overwrite. */ const IGNORED_ENTRIES = new Set([
     '.git',
     '.DS_Store',
     '.idea',
@@ -3821,12 +3775,9 @@ function run(pm, args, cwd) {
     'Thumbs.db'
 ]);
 /**
- * What is already at the target path, ignoring the entries a fresh clone or an editor leaves behind —
- * which is what decides whether scaffolding into it is safe.
- *
- * A path that does not exist yet is no conflict. A path that exists and is *not* a directory throws
- * rather than reporting an empty list, since `--force` should not write into one either — otherwise
- * `create-rshono README.md` gets as far as `mkdir` before failing on a raw ENOTDIR.
+ * What is already at the target path, ignoring the entries a fresh clone or an editor leaves behind — which is
+ * what decides whether scaffolding into it is safe. A path that does not exist yet is no conflict; one that
+ * exists and is not a directory throws, since `--force` should not write into it either.
  */ function conflictingEntries(dir) {
     const stats = statSync(dir, {
         throwIfNoEntry: false
@@ -3836,8 +3787,8 @@ function run(pm, args, cwd) {
     return external_node_fs_readdirSync(dir).filter((entry)=>!IGNORED_ENTRIES.has(entry));
 }
 /**
- * Writes the plan. Directories are created as needed, and files are written with the plan's own
- * ordering so a failure part-way through leaves something a person can make sense of.
+ * Writes the plan, creating directories as needed and keeping the plan's own ordering — so a failure part-way
+ * through leaves something a person can make sense of.
  */ function writePlan(plan, targetDir) {
     mkdirSync(targetDir, {
         recursive: true
@@ -3969,10 +3920,9 @@ function fail(message) {
 async function main() {
     const { values, positionals } = parse();
     if (values.help) return console.log(HELP);
-    if (values.version) return console.log("1.0.0-rc.12");
-    // A pipe, a CI job or an agent gets the defaults rather than a prompt nothing can answer. Both
-    // streams have to be a terminal: the prompts draw on stdout but *read from stdin*, so
-    // `echo | npx @rshono/create` would otherwise ask a question with nothing behind the keyboard.
+    if (values.version) return console.log("1.0.0-rc.14");
+    // A pipe, a CI job or an agent gets the defaults rather than a prompt nothing can answer. Both streams have to
+    // be a terminal: the prompts draw on stdout but read from stdin.
     const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY) && !values.yes;
     const pmFlag = oneOf(values.pm, PACKAGE_MANAGERS, 'pm');
     const pm = pmFlag ? packageManager(pmFlag) : detectPackageManager();
@@ -3983,8 +3933,7 @@ async function main() {
     const tailwindFlag = tristate(values.tailwind, values['no-tailwind'], 'tailwind');
     const installFlag = tristate(values.install, values['no-install'], 'install');
     const gitFlag = tristate(values.git, values['no-git'], 'git');
-    // The framework version, not this package's: it is the one the app will be pinned to, and the one
-    // worth reading here. `--version` reports create-rshono's own.
+    // The framework version, not this package's: it is the one the app gets pinned to. `--version` reports ours.
     intro(`create-rshono  ·  rshono ${RSHONO_VERSION}`);
     // ── Where ───────────────────────────────────────────────────────────────────────────────────────
     let directory = positionals[0];
@@ -4044,8 +3993,8 @@ async function main() {
             ]
         }));
     }
-    // One question instead of two. The axes stay independent underneath: a `--formatter` or `--linter`
-    // flag addresses either on its own, and skips the question entirely.
+    // One question instead of two; the axes stay independent underneath, and a `--formatter` or `--linter` flag
+    // addresses either on its own.
     let preset = QUALITY_PRESETS.find((candidate)=>candidate.id === qualityFlag);
     if (!preset && !formatterFlag && !linterFlag) {
         const fallback = QUALITY_PRESETS["0"];

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@rshono/create",
-  "version": "1.0.0-rc.12",
+  "version": "1.0.0-rc.14",
   "description": "Scaffold a new rshono app — Hono + Rspack + React Server Components",
   "author": "Lasse <lasse@lassetange.com> (https://www.lassetange.com)",
-  "license": "ISC",
+  "license": "MIT",
   "keywords": [
     "create",
     "scaffold",
@@ -46,7 +46,7 @@
     "@rspack/core": "2.1.7",
     "@types/node": "^26.1.1",
     "typescript": "^7.0.2",
-    "@rshono/core": "1.0.0-rc.12"
+    "@rshono/core": "1.0.0-rc.14"
   },
   "scripts": {
     "build": "node scripts/codegen.mjs && node scripts/build.mjs",

package/templates/eslint/eslint.config.mjs

@@ -1,9 +1,24 @@
+/**
+ * ESLint with type-aware rules, which is the reason to reach for it over a linter that only reads syntax.
+ *
+ * **This app's `typescript` is pinned below the one rshono is built with.** typescript-eslint reads the
+ * compiler API directly and accepts nothing from TypeScript 6.1 up, so `package.json` holds the newest
+ * version it takes. Your editor and `tsc` are unaffected — rshono's declarations compile the same under
+ * either — but the rules below reason about your program through the *older* compiler.
+ *
+ * The practical consequence: `lint:fix` can rewrite code that `tsc` then rejects. Run `typecheck` after it,
+ * not instead of it. When typescript-eslint widens its peer range, drop the `typescript` pin from
+ * `package.json` and this note with it.
+ */
 import js from '@eslint/js';
 import reactHooks from 'eslint-plugin-react-hooks';
 import tseslint from 'typescript-eslint';
 
 export default tseslint.config(
-  { ignores: ['dist/**', '.wrangler/**', '.vercel/**', '.netlify/**'] },
+  // Build output, all of it generated: `dist/` from `rshono build`, `.rshono/` from `rshono dev`, and
+  // whatever the deploy target assembles beside them. Without this, linting after a dev run reports on
+  // bundles rather than on anything you wrote.
+  { ignores: ['dist/**', '.rshono/**', '.wrangler/**', '.vercel/**', '.netlify/**'] },
   js.configs.recommended,
   tseslint.configs.recommendedTypeChecked,
   reactHooks.configs.flat['recommended-latest'],