create-kdna-web-app 0.3.1 → 0.4.0

package/LICENSE

@@ -1,17 +1,202 @@
-Apache License
-Version 2.0, January 2004
-http://www.apache.org/licenses/
 
-Copyright 2026 KDNA Authors
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
-    http://www.apache.org/licenses/LICENSE-2.0
+   1. Definitions.
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025-2026 AIKDNA Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -6,7 +6,7 @@ https://github.com/aikdna/create-kdna-web-app
 
 create-kdna-web-app is a project scaffolding CLI for KDNA-integrated
 web applications. Generated projects include the KDNA packages each
-template imports at runtime, pre-configured with a working validate →
+template imports at runtime, pre-configured with a working inspect →
 plan-load → load → consume flow.
 
 See LICENSE for the full Apache 2.0 license text.

package/README.md

@@ -8,10 +8,10 @@ cd my-app
 npm run dev
 ```
 
-The Next.js templates include `@aikdna/kdna-web-server` and
-`@aikdna/kdna-react` pre-configured with a validate -> inspect ->
-plan-load -> load demo. The Express template includes the server adapter
-and a minimal static HTML demo.
+Node.js 20 or later is required. Every template binds KDNA Core 0.20.0 and
+Web Server 0.3.0. The Next.js templates additionally bind React 0.3.0.
+Generated apps execute the same inspect -> LoadPlan -> load -> Runtime Capsule
+flow; they do not decode `.kdna` containers directly.
 
 [![npm](https://img.shields.io/npm/v/create-kdna-web-app)](https://www.npmjs.com/package/create-kdna-web-app)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
@@ -32,6 +32,11 @@ npx create-kdna-web-app <project-name> [options]
 | `--package-manager` | auto-detected | `npm`, `pnpm`, or `yarn` |
 | `--no-install` | — | Scaffold files without running install |
 
+The release gate verifies npm across all three templates. It also runs the
+packed CLI's real install and Next.js production build with pnpm 11.14.0 and
+Yarn 1.22.22, so the advertised package-manager paths are executable rather
+than parser-only options.
+
 ### Examples
 
 ```bash
@@ -66,7 +71,7 @@ npx create-kdna-web-app my-app --template nextjs-pages
 
 - Express with ESM
 - `src/server.js` — KDNA router mounted at `/api/kdna`
-- `public/index.html` — minimal HTML demo page
+- `public/index.html` — browser demo with the complete LoadPlan flow
 - `.env.example` for local configuration
 
 ---
@@ -75,9 +80,9 @@ npx create-kdna-web-app my-app --template nextjs-pages
 
 | Template | KDNA packages |
 |----------|---------------|
-| `nextjs` | `@aikdna/kdna-core`, `@aikdna/kdna-web-server`, `@aikdna/kdna-react` |
-| `nextjs-pages` | `@aikdna/kdna-core`, `@aikdna/kdna-web-server`, `@aikdna/kdna-react` |
-| `express` | `@aikdna/kdna-core`, `@aikdna/kdna-web-server` |
+| `nextjs` | Core 0.20.0, Web Server 0.3.0, React 0.3.0 |
+| `nextjs-pages` | Core 0.20.0, Web Server 0.3.0, React 0.3.0 |
+| `express` | Core 0.20.0, Web Server 0.3.0 |
 
 ## Pre-configured flow
 
@@ -91,12 +96,14 @@ The Next.js templates provide the full React flow:
 6. The loaded content is displayed.
 
 The Express template mounts the same `/api/kdna` server endpoints and includes
-a minimal HTML page that uploads, inspects, and loads an open `.kdna` asset.
+a static page that explicitly calls inspect, plan-load, and load in order.
+All templates render projected objects with `JSON.stringify`; React objects are
+never passed directly as JSX children.
 
 ### Environment variables
 
 ```bash
-# Optional
+# Optional; the server uses an OS temporary directory when omitted
 KDNA_STORAGE_DIR=/tmp/kdna
 
 # Optional — only needed for licensed-mode assets
@@ -111,7 +118,7 @@ KDNA_ACTIVATION_URL=https://your-activation-server.example.com
 cd my-app
 cp .env.local.example .env.local   # Next.js templates
 # or: cp .env.example .env         # Express template, if you load env files locally
-npm test                           # smoke-test KDNA package imports
+npm test                           # smoke-test exact package entrypoints
 npm run dev
 # Open http://localhost:3000 and drop a .kdna file
 ```
@@ -119,7 +126,7 @@ npm run dev
 To get a `.kdna` file for testing:
 
 ```bash
-npm install -g @aikdna/kdna-cli
+npm install -g @aikdna/kdna-cli@0.34.0
 kdna demo judgment ./demo-judgment
 kdna pack ./demo-judgment ./demo-judgment.kdna
 ```
@@ -134,6 +141,14 @@ kdna pack ./demo-judgment ./demo-judgment.kdna
 | [`@aikdna/kdna-web-server`](https://github.com/aikdna/kdna-web-server) | Server-side adapter |
 | [`@aikdna/kdna-react`](https://github.com/aikdna/kdna-react) | React components and hooks |
 
+## What this release verifies
+
+The scaffolder release gate packs the CLI, generates each template from that
+archive into an empty directory, performs a clean install, starts the actual
+production server, and uses Chromium with the accepted public Laozi asset to
+observe successful `/inspect`, `/plan-load`, and `/load` responses. A template
+is not accepted by import-only smoke tests.
+
 ---
 
 ## License

package/SECURITY.md

@@ -20,9 +20,10 @@ pre-release and the canonical KDNA protocol/runtime surfaces.
 
 | Component | Supported Versions |
 |-----------|-------------------|
-| KDNA Protocol | Latest tagged release |
-| kdna-cli | Latest minor release |
-| create-kdna-web-app | Latest mainline pre-release |
+| KDNA Core | 0.20.0 |
+| KDNA Web Server | 0.3.0 |
+| KDNA React | 0.3.0 |
+| create-kdna-web-app | 0.4.0 |
 
 Older pre-release versions may receive critical security patches on a
 case-by-case basis.
@@ -33,6 +34,12 @@ case-by-case basis.
 templates must consume the public KDNA package contracts rather than define
 protocol validity, access modes, LoadPlan states, or crypto policy.
 
+The selected `.kdna` file exists briefly in browser memory while it is
+uploaded. Validation, authorization, decryption, profile selection, and
+Runtime Capsule projection happen on the server. Password and license inputs
+may exist briefly in browser form state; generated code must not log, persist,
+or reflect them. Raw license keys go to `/activate`, not `/load`.
+
 For the KDNA Protocol security architecture, see
 [GOVERNANCE.md](https://github.com/aikdna/kdna/blob/main/docs/GOVERNANCE.md)
 in the main protocol repository.

package/docs/getting-started.md

@@ -20,7 +20,8 @@ cd my-app
 cp .env.local.example .env.local
 ```
 
-Open `.env.local`. The only required variable is `KDNA_STORAGE_DIR`:
+`KDNA_STORAGE_DIR` is optional; set it when you want a stable upload directory
+instead of the operating-system temporary directory:
 
 ```bash
 KDNA_STORAGE_DIR=/tmp/kdna
@@ -46,7 +47,7 @@ Open [http://localhost:3000](http://localhost:3000).
 Install the KDNA CLI and generate a current example asset:
 
 ```bash
-npm install -g @aikdna/kdna-cli
+npm install -g @aikdna/kdna-cli@0.34.0
 kdna demo judgment ./demo-judgment
 kdna pack ./demo-judgment ./demo-judgment.kdna
 ```
@@ -54,8 +55,12 @@ kdna pack ./demo-judgment ./demo-judgment.kdna
 Drop the file onto the page. You should see:
 
 1. The manifest metadata (domain, version, title).
-2. A "Load" button or automatic loading for public assets.
-3. The formatted payload content.
+2. The LoadPlan state produced before loading.
+3. The formatted Runtime Capsule context after a public asset loads.
+
+The browser demo does not parse the container. The selected file is uploaded
+to Web Server 0.3.0, and KDNA Core 0.20.0 performs validation, planning,
+authorization, and projection on the server.
 
 ---
 

package/docs/template-checklist.md

@@ -11,6 +11,8 @@ template.
 - Environment example file for storage and activation settings.
 - `scripts/smoke.mjs` that imports the KDNA package entrypoints used by
   the generated project.
+- A generated-project `README.md` that names the exact KDNA coordinates and
+  the inspect -> LoadPlan -> load boundary.
 
 ## Runtime boundaries
 
@@ -23,8 +25,16 @@ template.
 
 ## Verification
 
-- `npm test` passes in this repository.
+- `npm run ci:static` passes in this repository.
 - A generated project includes the expected route, page, env example, and
   smoke script.
 - The generated template package uses bounded dependency ranges.
 - Public docs and package metadata mention only templates that exist.
+- The packed CLI cold-generates all three templates; each clean install starts
+  its real production server and completes inspect -> plan-load -> load in
+  Chromium with both an accepted public asset and the pinned Core password
+  test vector.
+- The advertised npm, pnpm, and Yarn paths execute a real packed-CLI install;
+  the reference non-npm versions also complete a Next.js production build.
+- Browser output contains structured Runtime Capsule context, never
+  `[object Object]` or a server filesystem path.

package/docs/templates.md

@@ -9,14 +9,14 @@
 **When to use:** You are starting a new Next.js project or want the
 most up-to-date template.
 
-**Framework:** Next.js 14+ (App Router)
+**Framework:** Next.js 16+ (App Router)
 
 **What it includes:**
 
 | File | Purpose |
 |------|---------|
 | `app/api/kdna/[...route]/route.js` | All KDNA endpoints (catch-all App Router route) |
-| `app/page.jsx` | Demo page: file drop, inspect, load, display |
+| `app/page.jsx` | Demo page: file drop, inspect, LoadPlan, load, display |
 | `.env.local.example` | Environment variable template |
 
 **Start:**
@@ -40,7 +40,7 @@ Router project, or prefer the Pages Router.
 | File | Purpose |
 |------|---------|
 | `pages/api/kdna/[...route].js` | All KDNA endpoints |
-| `pages/index.jsx` | Demo page |
+| `pages/index.jsx` | Demo page with the same complete Runtime Capsule flow |
 | `.env.local.example` | Environment variable template |
 
 **Start:**
@@ -64,7 +64,7 @@ Next.js, or are integrating into an existing Express application.
 | File | Purpose |
 |------|---------|
 | `src/server.js` | Express server with KDNA router at `/api/kdna` |
-| `public/index.html` | Minimal HTML demo page |
+| `public/index.html` | Static demo with explicit inspect, plan-load, and load calls |
 | `.env.example` | Environment variable template |
 
 **Start:**
@@ -82,8 +82,9 @@ cd my-app && npm start
 | | `nextjs` | `nextjs-pages` | `express` |
 |-|----------|----------------|-----------|
 | KDNA API route included | Yes | Yes | Yes |
-| Edge runtime (Vercel) | No* | No* | No |
+| Edge runtime | No | No | No |
 | Browser demo included | React page | React page | Static HTML |
 | React dependency included | Yes | Yes | No |
 
-\* Use `@aikdna/kdna-web-server/cloudflare` for edge deployments.
+Web Server 0.3.0 is verified on Node.js runtimes. These templates do not claim
+an Edge or Worker adapter.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kdna-web-app",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Scaffold a KDNA-integrated web application with Next.js App Router, Next.js Pages Router, or Express templates.",
   "type": "commonjs",
   "bin": {
@@ -17,16 +17,24 @@
     "SECURITY.md"
   ],
   "scripts": {
-    "ci": "npm test && npm run test:templates && npm run lint && npm pack --dry-run --json",
-    "test": "node --test tests/scaffold.test.js",
+    "ci": "npm run ci:static && npm run test:templates && npm pack --dry-run --json",
+    "ci:static": "npm test && npm run lint && npm run public:check && npm run naming:check && npm run package:check",
+    "test": "node --test tests/scaffold.test.js tests/release-context.test.cjs tests/dco.test.cjs",
     "test:templates": "node scripts/test-templates.js",
     "lint": "node scripts/lint.js",
+    "public:check": "node scripts/check-public-surface.js",
+    "naming:check": "node scripts/check-naming-integrity.js",
+    "package:check": "node scripts/check-packed-boundary.js",
+    "release:context": "node scripts/verify-release-context.cjs",
     "prepublishOnly": "npm run ci"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "dependencies": {},
+  "devDependencies": {
+    "playwright": "1.61.1"
+  },
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/src/scaffold.js

@@ -32,15 +32,33 @@ function parseArgs(args) {
     if (arg === '--help' || arg === '-h') {
       options.help = true;
     } else if (arg === '--template') {
-      options.template = args[++index];
+      const value = args[index + 1];
+      if (!value || value.startsWith('-')) {
+        const error = new Error('--template requires a value.');
+        error.exitCode = 1;
+        throw error;
+      }
+      options.template = value;
+      index += 1;
     } else if (arg.startsWith('--template=')) {
       options.template = arg.slice('--template='.length);
     } else if (arg === '--package-manager') {
-      options.packageManager = args[++index];
+      const value = args[index + 1];
+      if (!value || value.startsWith('-')) {
+        const error = new Error('--package-manager requires a value.');
+        error.exitCode = 1;
+        throw error;
+      }
+      options.packageManager = value;
+      index += 1;
     } else if (arg.startsWith('--package-manager=')) {
       options.packageManager = arg.slice('--package-manager='.length);
     } else if (arg === '--no-install') {
       options.install = false;
+    } else if (arg.startsWith('-')) {
+      const error = new Error(`Unknown option: ${arg}\n\n${usage()}`);
+      error.exitCode = 1;
+      throw error;
     } else if (!options.projectName) {
       options.projectName = arg;
     } else {
@@ -60,6 +78,14 @@ function validateOptions(options) {
     error.exitCode = 1;
     throw error;
   }
+  const packageName = path.basename(path.resolve(options.projectName));
+  if (!/^[a-z0-9][a-z0-9._-]{0,213}$/u.test(packageName)) {
+    const error = new Error(
+      'Project directory name must be a lowercase npm package name (letters, numbers, dots, hyphens, or underscores).',
+    );
+    error.exitCode = 1;
+    throw error;
+  }
   if (!VALID_TEMPLATES.has(options.template)) {
     const error = new Error(`Unknown template: ${options.template}`);
     error.exitCode = 1;

package/templates/express/README.md

@@ -0,0 +1,18 @@
+# KDNA Express starter
+
+This generated Node.js 20+ application binds KDNA Core 0.20.0 and Web Server
+0.3.0. The static browser page uploads a selected `.kdna` file and explicitly
+executes inspect, plan-load, and load before rendering Runtime Capsule context.
+If LoadPlan requires a password, the page clears the password field around the
+request and renders the authorized Runtime context only after unlock succeeds.
+
+```bash
+cp .env.example .env
+npm test
+npm start
+```
+
+Open `http://localhost:3000` and choose a `.kdna` file. The sample server reads
+environment variables from its process; use your deployment environment or a
+local environment loader if you need `.env` file loading. Do not log or persist
+passwords, license keys, signed entitlements, or server error internals.

package/templates/express/package.json

@@ -7,9 +7,12 @@
     "start": "node src/server.js",
     "test": "node scripts/smoke.mjs"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
-    "@aikdna/kdna-core": "0.17.0",
-    "@aikdna/kdna-web-server": "0.2.3",
+    "@aikdna/kdna-core": "0.20.0",
+    "@aikdna/kdna-web-server": "0.3.0",
     "express": "^5.2.1"
   }
 }

package/templates/express/pnpm-workspace.yaml

@@ -0,0 +1,5 @@
+allowBuilds:
+  cbor-extract: true
+minimumReleaseAgeExclude:
+  - '@aikdna/kdna-core@0.20.0'
+  - '@aikdna/kdna-web-server@0.3.0'

package/templates/express/public/index.html

@@ -7,22 +7,108 @@
   </head>
   <body>
     <main>
+      <h1>KDNA Runtime Capsule viewer</h1>
       <input id="file" type="file" accept=".kdna">
+      <p id="kdna-status">Choose a .kdna file</p>
       <pre id="output">Choose a .kdna file</pre>
+      <form id="kdna-password-form" hidden>
+        <label for="kdna-password">Password</label>
+        <input id="kdna-password" type="password" autocomplete="current-password">
+        <button type="submit">Unlock</button>
+      </form>
     </main>
     <script>
       const file = document.querySelector('#file')
+      const status = document.querySelector('#kdna-status')
       const output = document.querySelector('#output')
+      const passwordForm = document.querySelector('#kdna-password-form')
+      const passwordInput = document.querySelector('#kdna-password')
+      let pendingUnlock = null
+
+      async function readJson(response) {
+        const body = await response.json()
+        if (!response.ok) {
+          throw new Error(body?.error?.message || `KDNA request failed (${response.status})`)
+        }
+        return body
+      }
+
       file.addEventListener('change', async () => {
-        const form = new FormData()
-        form.set('file', file.files[0])
-        const inspect = await fetch('/api/kdna/inspect', { method: 'POST', body: form }).then((r) => r.json())
-        const loaded = await fetch('/api/kdna/load', {
-          method: 'POST',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({ fileId: inspect.fileId, profile: 'compact' }),
-        }).then((r) => r.json())
-        output.textContent = loaded.content || JSON.stringify(loaded, null, 2)
+        try {
+          pendingUnlock = null
+          passwordInput.value = ''
+          passwordForm.hidden = true
+          output.id = 'output'
+          status.textContent = 'inspecting'
+          const form = new FormData()
+          form.set('file', file.files[0])
+          const inspect = await readJson(await fetch('/api/kdna/inspect', {
+            method: 'POST',
+            body: form,
+          }))
+
+          status.textContent = 'planning'
+          const plan = await readJson(await fetch('/api/kdna/plan-load', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ fileId: inspect.fileId, context: {} }),
+          }))
+          if (!plan.canProceed) {
+            status.textContent = 'locked'
+            output.textContent = JSON.stringify({ inspect, plan }, null, 2)
+            if (plan.plan?.state === 'needs_password' || plan.plan?.required_action === 'enter_password') {
+              pendingUnlock = { fileId: inspect.fileId, inspect, plan }
+              passwordForm.hidden = false
+            }
+            return
+          }
+
+          status.textContent = 'loading'
+          const loaded = await readJson(await fetch('/api/kdna/load', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ fileId: inspect.fileId, profile: 'compact' }),
+          }))
+          status.textContent = 'loaded'
+          output.id = 'kdna-runtime-capsule'
+          output.textContent = JSON.stringify({ inspect, plan: plan.plan, content: loaded.content }, null, 2)
+        } catch (error) {
+          status.textContent = 'error'
+          output.textContent = error.message
+        }
+      })
+
+      passwordForm.addEventListener('submit', async (event) => {
+        event.preventDefault()
+        if (!pendingUnlock) return
+        const password = passwordInput.value
+        passwordInput.value = ''
+        try {
+          status.textContent = 'loading'
+          const loaded = await readJson(await fetch('/api/kdna/load', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+              fileId: pendingUnlock.fileId,
+              profile: 'compact',
+              password,
+            }),
+          }))
+          status.textContent = 'loaded'
+          passwordForm.hidden = true
+          output.id = 'kdna-runtime-capsule'
+          output.textContent = JSON.stringify({
+            inspect: pendingUnlock.inspect,
+            plan: pendingUnlock.plan.plan,
+            content: loaded.content,
+          }, null, 2)
+          pendingUnlock = null
+        } catch (error) {
+          status.textContent = 'locked'
+          output.textContent = error.message
+        } finally {
+          passwordInput.value = ''
+        }
       })
     </script>
   </body>

package/templates/nextjs/README.md

@@ -0,0 +1,16 @@
+# KDNA Next.js App Router starter
+
+This generated Node.js 20+ application binds KDNA Core 0.20.0, Web Server
+0.3.0, and React 0.3.0. The browser uploads a selected `.kdna` file; the server
+then performs inspect, LoadPlan evaluation, authorization, and Runtime Capsule
+projection.
+
+```bash
+cp .env.local.example .env.local
+npm test
+npm run dev
+```
+
+Open `http://localhost:3000` and choose a `.kdna` file. Storage and activation
+configuration are documented in `.env.local.example`. Do not log or persist
+passwords, license keys, signed entitlements, or server error internals.

package/templates/nextjs/app/page.jsx

@@ -8,31 +8,54 @@ import {
 } from '@aikdna/kdna-react'
 import { useState } from 'react'
 
+function AssetFlow({ fileId, inspect }) {
+  const [unlockedContent, setUnlockedContent] = useState(null)
+
+  return (
+    <section>
+      <KDNAAssetInspector inspect={inspect} />
+      <KDNALoadPlanGate fileId={fileId} endpoint="/api/kdna">
+        {({ status, content, error }) => {
+          if (status === 'locked' && !unlockedContent) {
+            return (
+              <KDNAPasswordUnlockDialog
+                fileId={fileId}
+                endpoint="/api/kdna"
+                onUnlock={(result) => setUnlockedContent(result.content)}
+              />
+            )
+          }
+          const visibleContent = unlockedContent ?? content
+          return (
+            <>
+              <p id="kdna-status">{visibleContent ? 'loaded' : status}</p>
+              {error ? <p role="alert">{error.message}</p> : null}
+              {visibleContent ? (
+                <pre id="kdna-runtime-capsule">
+                  {JSON.stringify(visibleContent, null, 2)}
+                </pre>
+              ) : null}
+            </>
+          )
+        }}
+      </KDNALoadPlanGate>
+    </section>
+  )
+}
+
 export default function Page() {
-  const [unlock, setUnlock] = useState(null)
+  const [uploadError, setUploadError] = useState(null)
 
   return (
     <main>
-      <KDNAFileDropzone endpoint="/api/kdna" onError={console.error}>
+      <h1>KDNA Runtime Capsule viewer</h1>
+      <KDNAFileDropzone endpoint="/api/kdna" onError={setUploadError}>
         {({ fileId, inspect, loading }) => (
           <section>
             <p>{loading ? 'Uploading...' : 'Drop or choose a .kdna file'}</p>
-            {inspect ? <KDNAAssetInspector inspect={inspect} /> : null}
-            {fileId ? (
-              <KDNALoadPlanGate fileId={fileId} endpoint="/api/kdna">
-                {({ status, content }) => {
-                  if (status === 'locked') {
-                    return (
-                      <KDNAPasswordUnlockDialog
-                        fileId={fileId}
-                        endpoint="/api/kdna"
-                        onUnlock={(result) => setUnlock(result.content)}
-                      />
-                    )
-                  }
-                  return <pre>{unlock || content || status}</pre>
-                }}
-              </KDNALoadPlanGate>
+            {uploadError ? <p role="alert">{uploadError.message}</p> : null}
+            {fileId && inspect ? (
+              <AssetFlow key={fileId} fileId={fileId} inspect={inspect} />
             ) : null}
           </section>
         )}

package/templates/nextjs/package.json

@@ -8,23 +8,21 @@
     "start": "next start",
     "test": "node scripts/smoke.mjs"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
-    "@aikdna/kdna-core": "0.17.0",
-    "@aikdna/kdna-react": "0.2.0",
-    "@aikdna/kdna-web-server": "0.2.3",
+    "@aikdna/kdna-core": "0.20.0",
+    "@aikdna/kdna-react": "0.3.0",
+    "@aikdna/kdna-web-server": "0.3.0",
     "next": "^16.2.10",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   },
   "overrides": {
-    "postcss": "^8.5.10"
-  },
-  "pnpm": {
-    "overrides": {
-      "postcss": "^8.5.10"
-    }
+    "postcss": "8.5.10"
   },
   "resolutions": {
-    "postcss": "^8.5.10"
+    "postcss": "8.5.10"
   }
 }

package/templates/nextjs/pnpm-workspace.yaml

@@ -0,0 +1,10 @@
+overrides:
+  postcss: 8.5.10
+allowBuilds:
+  cbor-extract: true
+  sharp: true
+minimumReleaseAgeExclude:
+  - '@aikdna/kdna-core@0.20.0'
+  - '@aikdna/kdna-react@0.3.0'
+  - '@aikdna/kdna-web-client@0.2.2'
+  - '@aikdna/kdna-web-server@0.3.0'

package/templates/nextjs-pages/README.md

@@ -0,0 +1,16 @@
+# KDNA Next.js Pages Router starter
+
+This generated Node.js 20+ application binds KDNA Core 0.20.0, Web Server
+0.3.0, and React 0.3.0. The browser uploads a selected `.kdna` file; the server
+then performs inspect, LoadPlan evaluation, authorization, and Runtime Capsule
+projection.
+
+```bash
+cp .env.local.example .env.local
+npm test
+npm run dev
+```
+
+Open `http://localhost:3000` and choose a `.kdna` file. Storage and activation
+configuration are documented in `.env.local.example`. Do not log or persist
+passwords, license keys, signed entitlements, or server error internals.

package/templates/nextjs-pages/package.json

@@ -8,23 +8,21 @@
     "start": "next start",
     "test": "node scripts/smoke.mjs"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
-    "@aikdna/kdna-core": "0.17.0",
-    "@aikdna/kdna-react": "0.2.0",
-    "@aikdna/kdna-web-server": "0.2.3",
+    "@aikdna/kdna-core": "0.20.0",
+    "@aikdna/kdna-react": "0.3.0",
+    "@aikdna/kdna-web-server": "0.3.0",
     "next": "^16.2.10",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   },
   "overrides": {
-    "postcss": "^8.5.10"
-  },
-  "pnpm": {
-    "overrides": {
-      "postcss": "^8.5.10"
-    }
+    "postcss": "8.5.10"
   },
   "resolutions": {
-    "postcss": "^8.5.10"
+    "postcss": "8.5.10"
   }
 }

package/templates/nextjs-pages/pages/api/kdna/[...route].js

@@ -12,6 +12,13 @@ const handler = createKDNARouter({
   activationServerUrl: process.env.KDNA_ACTIVATION_URL,
 })
 
-export default function kdna(req, res) {
-  return handler(req, res)
+export default async function kdna(req, res) {
+  const incomingUrl = req.url
+  const route = Array.isArray(req.query.route) ? req.query.route : []
+  req.url = `/${route.join('/')}`
+  try {
+    await handler(req, res)
+  } finally {
+    req.url = incomingUrl
+  }
 }

package/templates/nextjs-pages/pages/index.jsx

@@ -6,31 +6,54 @@ import {
 } from '@aikdna/kdna-react'
 import { useState } from 'react'
 
+function AssetFlow({ fileId, inspect }) {
+  const [unlockedContent, setUnlockedContent] = useState(null)
+
+  return (
+    <section>
+      <KDNAAssetInspector inspect={inspect} />
+      <KDNALoadPlanGate fileId={fileId} endpoint="/api/kdna">
+        {({ status, content, error }) => {
+          if (status === 'locked' && !unlockedContent) {
+            return (
+              <KDNAPasswordUnlockDialog
+                fileId={fileId}
+                endpoint="/api/kdna"
+                onUnlock={(result) => setUnlockedContent(result.content)}
+              />
+            )
+          }
+          const visibleContent = unlockedContent ?? content
+          return (
+            <>
+              <p id="kdna-status">{visibleContent ? 'loaded' : status}</p>
+              {error ? <p role="alert">{error.message}</p> : null}
+              {visibleContent ? (
+                <pre id="kdna-runtime-capsule">
+                  {JSON.stringify(visibleContent, null, 2)}
+                </pre>
+              ) : null}
+            </>
+          )
+        }}
+      </KDNALoadPlanGate>
+    </section>
+  )
+}
+
 export default function Page() {
-  const [unlock, setUnlock] = useState(null)
+  const [uploadError, setUploadError] = useState(null)
 
   return (
     <main>
-      <KDNAFileDropzone endpoint="/api/kdna" onError={console.error}>
+      <h1>KDNA Runtime Capsule viewer</h1>
+      <KDNAFileDropzone endpoint="/api/kdna" onError={setUploadError}>
         {({ fileId, inspect, loading }) => (
           <section>
             <p>{loading ? 'Uploading...' : 'Drop or choose a .kdna file'}</p>
-            {inspect ? <KDNAAssetInspector inspect={inspect} /> : null}
-            {fileId ? (
-              <KDNALoadPlanGate fileId={fileId} endpoint="/api/kdna">
-                {({ status, content }) => {
-                  if (status === 'locked') {
-                    return (
-                      <KDNAPasswordUnlockDialog
-                        fileId={fileId}
-                        endpoint="/api/kdna"
-                        onUnlock={(result) => setUnlock(result.content)}
-                      />
-                    )
-                  }
-                  return <pre>{unlock || content || status}</pre>
-                }}
-              </KDNALoadPlanGate>
+            {uploadError ? <p role="alert">{uploadError.message}</p> : null}
+            {fileId && inspect ? (
+              <AssetFlow key={fileId} fileId={fileId} inspect={inspect} />
             ) : null}
           </section>
         )}

package/templates/nextjs-pages/pnpm-workspace.yaml

@@ -0,0 +1,10 @@
+overrides:
+  postcss: 8.5.10
+allowBuilds:
+  cbor-extract: true
+  sharp: true
+minimumReleaseAgeExclude:
+  - '@aikdna/kdna-core@0.20.0'
+  - '@aikdna/kdna-react@0.3.0'
+  - '@aikdna/kdna-web-client@0.2.2'
+  - '@aikdna/kdna-web-server@0.3.0'