create-astrale-domain 0.3.0-beta.2 → 0.3.0-beta.20

package/README.md

@@ -2,7 +2,7 @@
 
 Official scaffolder for a new Astrale Domain project.
 
-During the SDK beta program, generate a project from the beta cohort explicitly:
+During the SDK beta program, generate a project from the beta package set explicitly:
 
 ```bash
 npx -y create-astrale-domain@beta my-domain --yes
@@ -10,3 +10,13 @@ npx -y create-astrale-domain@beta my-domain --yes
 
 The generated project must resolve the SDK and deployment adapters from npm; it must not retain
 workspace links or repository-only source paths.
+
+Generated projects have one package journey:
+
+```bash
+pnpm pack
+```
+
+The existing `astrale-domain package` command compiles the public Schema and independently loadable
+Runtime, normalizes emitted declarations to semantic SDK facades, and verifies the archive boundary.
+Deployment adapters remain development dependencies and are not part of the published Domain runtime.

package/dist/index.js

@@ -6,7 +6,11 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __commonJS = (cb, mod) => function __require() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e2) {
+    throw mod = 0, e2;
+  }
 };
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
@@ -364,7 +368,7 @@ function BD(e2, u2) {
   return s;
 }
 var AD = globalThis.process.platform.startsWith("win");
-var S = Symbol("clack:cancel");
+var S = /* @__PURE__ */ Symbol("clack:cancel");
 function pD(e2) {
   return e2 === S;
 }
@@ -780,6 +784,7 @@ import { existsSync as existsSync2 } from "node:fs";
 import { delimiter, join as join2, relative as relative2, resolve as resolve2 } from "node:path";
 
 // src/scaffold/index.ts
+import { signingIdentity } from "@astrale-os/adapter-cloudflare/build";
 import { existsSync, readFileSync } from "node:fs";
 import { cp, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
@@ -794,9 +799,7 @@ var INSTANCE_PLACEHOLDER = "my-instance-slug";
 var LINK_PACKAGES = /* @__PURE__ */ new Set([
   "@astrale-os/sdk",
   "@astrale-os/adapter-cloudflare",
-  "@astrale-os/adapter-astrale",
-  "@astrale-os/shell",
-  "@astrale-os/shell-react"
+  "@astrale-os/adapter-astrale"
 ]);
 var ADAPTER_PACKAGES = {
   astrale: "@astrale-os/adapter-astrale",
@@ -928,7 +931,11 @@ async function writeProject(opts) {
   await stampOrigin(opts.dir, opts.origin);
   await rewritePackageJson(opts.dir, opts.name, opts.link);
   if (opts.link) await writeLinkedZodOverride(opts.dir);
-  else await writeReleaseAgePolicy(opts.dir);
+  await signingIdentity({
+    projectDir: opts.dir,
+    origin: opts.origin,
+    mode: "local"
+  });
   await writeFile(
     join(opts.dir, ".env.dev"),
     "# Dev secrets \u2014 the ENTIRE file is injected into the local runtime by `pnpm dev`.\n# Gitignored. See .env.example.\n"
@@ -943,42 +950,41 @@ async function materializeGitignores(dir, frontend) {
       throw new Error(`Template is missing packaged Git ignore file ${packagedPath}.`);
     }
   }
-  if (frontend === "react") {
-    const path = join(dir, ".gitignore");
-    const current = await readFile(path, "utf-8");
-    await writeFile(
-      path,
-      `${current.trimEnd()}
-
-# SDK-managed React bootstrap (regenerated before every frontend build)
-/views/app/index.html
-/views/app/astrale.generated.tsx
-`
-    );
-  }
+  void frontend;
 }
 async function materializeFrontend(opts, template) {
   const variant = join(template, ".variants", opts.frontend);
   if (!existsSync(variant)) throw new Error(`Frontend template not found at ${variant}.`);
-  await cp(variant, opts.dir, { recursive: true });
+  await cp(variant, opts.dir, {
+    recursive: true,
+    filter: (source) => relative(variant, source) !== "implementation.ts"
+  });
   const path = join(opts.dir, "package.json");
   const pkg = JSON.parse(await readFile(path, "utf-8"));
   pkg.dependencies ??= {};
   pkg.devDependencies ??= {};
+  pkg.scripts ??= {};
   if (opts.frontend === "react") {
     Object.assign(pkg.dependencies, {
-      "@astrale-os/shell": ">=0.3.8-beta.2 <1.0.0",
-      "@astrale-os/shell-react": ">=0.2.10-beta.2 <1.0.0",
+      "@tanstack/react-router": "1.170.17",
       react: "^19.2.0",
       "react-dom": "^19.2.0"
     });
     Object.assign(pkg.devDependencies, {
+      "@tailwindcss/vite": "^4.0.6",
+      "@tanstack/router-plugin": "1.168.19",
       "@types/react": "^19.2.0",
       "@types/react-dom": "^19.2.0",
-      vite: "^7.1.7"
+      "@vitejs/plugin-react": "^6.0.5",
+      tailwindcss: "^4.0.6",
+      vite: "^8.2.1"
     });
   } else if (opts.frontend === "custom") {
-    pkg.devDependencies.vite = "^7.1.7";
+    pkg.devDependencies.vite = "^8.2.1";
+  }
+  if (opts.frontend !== "none") {
+    pkg.scripts["frontend:dev"] = "vite";
+    pkg.scripts["frontend:build"] = "vite build";
   }
   pkg.dependencies = sorted(pkg.dependencies);
   pkg.devDependencies = sorted(pkg.devDependencies);
@@ -1014,16 +1020,16 @@ async function materializeAdapter(opts) {
 async function addManagedAdapterDep(dir) {
   const path = join(dir, "package.json");
   const pkg = JSON.parse(await readFile(path, "utf-8"));
-  if (!pkg.dependencies || !("@astrale-os/adapter-cloudflare" in pkg.dependencies)) {
+  if (!pkg.devDependencies || !("@astrale-os/adapter-cloudflare" in pkg.devDependencies)) {
     throw new Error(
       "Could not materialize @astrale-os/adapter-astrale: the scaffold body does not declare its @astrale-os/adapter-cloudflare Worker runtime dependency."
     );
   }
-  pkg.dependencies["@astrale-os/adapter-astrale"] = installedPackageRange(
+  pkg.devDependencies["@astrale-os/adapter-astrale"] = installedPackageRange(
     "@astrale-os/adapter-astrale"
   );
-  pkg.dependencies = Object.fromEntries(
-    Object.entries(pkg.dependencies).sort(([a], [b3]) => a.localeCompare(b3))
+  pkg.devDependencies = Object.fromEntries(
+    Object.entries(pkg.devDependencies).sort(([a], [b3]) => a.localeCompare(b3))
   );
   await writeFile(path, JSON.stringify(pkg, null, 2) + "\n");
 }
@@ -1031,9 +1037,23 @@ async function rewritePackageJson(dir, name, link) {
   const path = join(dir, "package.json");
   const pkg = JSON.parse(await readFile(path, "utf-8"));
   pkg.name = name;
+  if (pkg.imports !== void 0) {
+    pkg.publishConfig ??= {};
+    pkg.publishConfig.imports = publishedImports(pkg.imports);
+  }
   rewriteAstraleDeps(pkg, link);
   await writeFile(path, JSON.stringify(pkg, null, 2) + "\n");
 }
+function publishedImports(imports) {
+  return Object.fromEntries(
+    Object.entries(imports).map(([specifier, target]) => {
+      if (!/^\.\/.*\.ts$/u.test(target)) {
+        throw new TypeError(`Package import ${specifier} must target one project TypeScript file.`);
+      }
+      return [specifier, `./dist/${target.slice(2, -3)}.js`];
+    })
+  );
+}
 function rewriteAstraleDeps(pkg, link) {
   if (!link) return false;
   let changed = false;
@@ -1050,7 +1070,6 @@ function rewriteAstraleDeps(pkg, link) {
   }
   return changed;
 }
-var FIRST_PARTY_SCOPES = ["@astrale-domains/*", "@astrale-os/*"];
 async function writeLinkedZodOverride(dir) {
   const workspace = join(dir, "pnpm-workspace.yaml");
   if (!existsSync(workspace)) return;
@@ -1066,21 +1085,6 @@ ${end}
   const pattern = new RegExp(`\\n?${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}\\n?`);
   await writeFile(workspace, text.replace(pattern, "\n").trimEnd() + block);
 }
-async function writeReleaseAgePolicy(dir) {
-  const workspace = join(dir, "pnpm-workspace.yaml");
-  if (!existsSync(workspace)) return;
-  const start = "# create-astrale-domain: first-party scopes";
-  const end = "# /create-astrale-domain";
-  const block = `
-${start}
-minimumReleaseAgeExclude:
-` + FIRST_PARTY_SCOPES.map((scope) => `  - '${scope}'`).join("\n") + `
-${end}
-`;
-  const text = await readFile(workspace, "utf-8");
-  const pattern = new RegExp(`\\n?${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}\\n?`);
-  await writeFile(workspace, text.replace(pattern, "\n").trimEnd() + block);
-}
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -1115,13 +1119,6 @@ function localPackageRoot(dependency) {
     const installed = dirname(resolved.path);
     if (!installed.split(sep).includes("node_modules")) return installed;
   }
-  if ((dependency === "@astrale-os/shell" || dependency === "@astrale-os/shell-react") && SDK_ROOT !== void 0) {
-    const packageDirectory = dependency === "@astrale-os/shell" ? "shell" : "shell-react";
-    for (const base of [dirname(SDK_ROOT), dirname(dirname(SDK_ROOT))]) {
-      const candidate = join(base, "shell", "packages", packageDirectory);
-      if (existsSync(join(candidate, "package.json"))) return candidate;
-    }
-  }
   throw new Error(`No active source package is available for ${dependency}.`);
 }
 
@@ -1175,6 +1172,10 @@ async function main() {
   const headless = flags.yes || !process.stdin.isTTY;
   Ie("Astrale \u2014 new domain");
   let slug = flags.positional[0];
+  if (flags.positional.length > 1) {
+    xe(`Unexpected positional argument "${flags.positional[1]}".`);
+    return 1;
+  }
   if (!slug) {
     if (headless) {
       xe("A domain slug is required in non-interactive mode (pass it as the first argument).");
@@ -1249,6 +1250,10 @@ async function main() {
       pm = answer;
     }
   }
+  if (!PMS.includes(pm)) {
+    xe(`Unknown package manager "${pm}" \u2014 use ${PMS.join(", ")}.`);
+    return 1;
+  }
   const dir = resolve2(flags.dir ?? slug);
   if (existsSync2(dir) && !flags.force) {
     if (headless) {
@@ -1259,8 +1264,10 @@ async function main() {
     if (pD(go) || !go) return bail();
   }
   const link = flags.link ?? workspaceAvailable();
-  if (flags.origin !== void 0 && !isValidSlug(flags.origin)) {
-    xe(`Invalid --origin "${flags.origin}". Use lowercase letters, digits, dots and dashes.`);
+  if (flags.origin !== void 0 && !isValidOrigin(flags.origin)) {
+    xe(
+      `Invalid --origin "${flags.origin}". Use a lowercase dotted domain with valid DNS labels.`
+    );
     return 1;
   }
   const origin = flags.origin ?? (slug.includes(".") ? slug : `${slug}.example.dev`);
@@ -1341,16 +1348,24 @@ function parseFlags(argv) {
     else if (a === "--force") flags.force = true;
     else if (a === "--link") flags.link = true;
     else if (a === "--no-link") flags.link = false;
-    else if (a === "--adapter") flags.adapter = argv[++i];
-    else if (a === "--frontend") flags.frontend = argv[++i];
-    else if (a === "--pm") flags.pm = argv[++i];
-    else if (a === "--dir") flags.dir = argv[++i];
-    else if (a === "--origin") flags.origin = argv[++i];
-    else if (a === "--instance") flags.instance = argv[++i];
+    else if (a === "--adapter") flags.adapter = flagValue(argv, ++i, a);
+    else if (a === "--frontend") flags.frontend = flagValue(argv, ++i, a);
+    else if (a === "--pm") flags.pm = flagValue(argv, ++i, a);
+    else if (a === "--dir") flags.dir = flagValue(argv, ++i, a);
+    else if (a === "--origin") flags.origin = flagValue(argv, ++i, a);
+    else if (a === "--instance") flags.instance = flagValue(argv, ++i, a);
+    else if (a.startsWith("-")) throw new TypeError(`Unknown option "${a}".`);
     else if (!a.startsWith("-")) flags.positional.push(a);
   }
   return flags;
 }
+function flagValue(argv, index, flag) {
+  const value = argv[index];
+  if (value === void 0 || value.startsWith("-")) {
+    throw new TypeError(`${flag} requires a value.`);
+  }
+  return value;
+}
 function printHelp() {
   process.stdout.write(
     `
@@ -1384,6 +1399,12 @@ Non-interactive (also auto-enabled without a TTY, e.g. CI):
 function isValidSlug(v2) {
   return /^[a-z][a-z0-9.-]*$/.test(v2);
 }
+function isValidOrigin(value) {
+  if (value.length > 253 || !value.includes(".")) return false;
+  return value.split(".").every(
+    (label) => label.length > 0 && label.length <= 63 && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/u.test(label)
+  );
+}
 function bail() {
   xe("Cancelled.");
   return 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astrale-domain",
-  "version": "0.3.0-beta.2",
+  "version": "0.3.0-beta.20",
   "description": "Scaffold a standalone Astrale domain — npm create astrale-domain",
   "keywords": [
     "astrale",
@@ -10,38 +10,43 @@
   ],
   "license": "Apache-2.0",
   "author": "Astrale",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/astrale-os/sdk.git"
+  },
   "bin": {
     "create-astrale-domain": "./dist/index.js"
   },
   "files": [
     "dist",
+    "!dist/**/*.map",
     "template",
-    "!template/node_modules",
-    "!template/pnpm-lock.yaml"
+    "!template/**/node_modules",
+    "!template/**/node_modules/**",
+    "!template/**/pnpm-lock.yaml"
   ],
   "type": "module",
   "dependencies": {
     "@clack/prompts": "^0.11.0",
-    "@astrale-os/adapter-cloudflare": "^0.5.0-beta.9",
-    "@astrale-os/adapter-astrale": "^0.5.0-beta.2"
+    "@astrale-os/adapter-astrale": "^0.5.0-beta.20",
+    "@astrale-os/adapter-cloudflare": "^0.5.0-beta.27"
   },
   "devDependencies": {
     "@astrale-os/ox": ">=0.1.0 <1.0.0",
     "@types/node": "^22.0.0",
-    "@typescript/native-preview": "latest",
-    "esbuild": "^0.25.4",
-    "oxfmt": "0.52.0",
-    "oxlint": "latest",
-    "typescript": "~6.0.1-rc",
-    "vitest": "^3.0.0",
-    "@astrale-os/sdk": "^0.5.0-beta.6"
+    "esbuild": "^0.28.2",
+    "oxfmt": "0.63.0",
+    "oxlint": "1.78.0",
+    "typescript": "7.0.2",
+    "vitest": "^4.1.10",
+    "@astrale-os/sdk": "^0.5.0-beta.24"
   },
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "build": "node scripts/build.mjs",
-    "typecheck": "tsgo --noEmit",
+    "build": "rm -rf dist && node scripts/build.mjs && node ../scripts/verify-no-source-maps.mjs dist",
+    "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:generated": "node scripts/verify-generated.mjs",
     "lint": "oxlint .",

package/template/.env.example

@@ -4,6 +4,10 @@
 # prod. These files are gitignored — copy this to `.env.dev` and fill in.
 #
 # Add one line per secret required by an Integration. Declare the corresponding
-# binding on `ApplicationEnvironment` in `implementation.ts`. For example:
+# binding returned by `runtime.ts` initialization. For example:
 #
 # EXAMPLE_API_KEY=sk-...
+
+# The Cloudflare adapter's execution identity is separate from Integration
+# secrets. The scaffold creates `.astrale/identity.json`; retain and restore
+# that file for production rather than copying its value into this dotenv file.

package/template/.variants/custom/README.md

@@ -1,17 +1,18 @@
 # Astrale Domain
 
-This project uses the framework-neutral frontend escape hatch. `views/routes.ts` binds declared
-Views to a `frontendArtifact`; `views/app/` is an ordinary Vite root you can replace with any
+This project uses the framework-neutral frontend escape hatch. `views/application/routes.ts` binds
+declared Views to `defineFrontend`; `vite.config.ts` owns the ordinary Vite root you can replace with any
 framework; `ui/` owns presentation assets. The starter route uses `handshake: 'none'`, so it mounts
 as a plain hosted app. Change that route to `handshake: 'shell'` only after your browser entrypoint
 boots the Shell protocol.
 
 ```text
 schema/             public Domain contract, including View declarations
-implementation.ts   schema, callable handlers, and frontend composition
-views/routes.ts      framework-neutral artifact and routes
-views/app/           fully author-owned browser application
-ui/                  presentation tokens and styles
+runtime.ts          Actions, Workflows, Integrations, Providers, and initialization
+application.ts      Schema, Runtime, and frontend composition
+views/              framework-neutral frontend declaration
+views/application/   application View, route, and browser entrypoint
+ui/application/      application presentation, tokens, and styles
 tests/               cross-layer executable journeys
 ```
 

package/template/.variants/custom/__tests__/variant.test.ts

@@ -0,0 +1,13 @@
+import { application } from '../application.js'
+
+describe('custom frontend variant', () => {
+  /** @evidence SDK-V1-SCAFFOLD-CUSTOM */
+  it('rejects missing authored frontend composition', () => {
+    expect(application.frontend).toBeDefined()
+    expect(application.frontend?.source.kind).toBe('vite')
+    expect(application.frontend?.routes.application).toMatchObject({
+      path: '/application',
+      handshake: 'none',
+    })
+  })
+})

package/template/.variants/custom/application.ts

@@ -0,0 +1,9 @@
+import { defineApplication } from '@astrale-os/sdk/application'
+
+import { schema } from '#schema'
+import { frontend } from '#views'
+
+import runtime from './runtime.js'
+
+/** Build and publication composition; provider effects live in astrale.config.ts. */
+export const application = defineApplication({ schema, runtime, frontend })

package/template/.variants/custom/schema/application/index.ts

@@ -1,10 +1,8 @@
 import { defineSchema, view } from '@astrale-os/sdk/schema'
 
 export const schema = defineSchema('astrale-domain.example.dev', {
-  interfaces: {},
   classes: {},
-  functions: {},
   views: {
-    application: view({ target: 'domain' }),
+    application: view({}),
   },
 })

package/template/.variants/custom/ui/application/__tests__/application.test.ts

@@ -0,0 +1,9 @@
+import { applicationMarkup, applicationTheme } from '../index.js'
+
+describe('application UI', () => {
+  it('owns the framework-neutral presentation', () => {
+    expect(applicationTheme.accent).toBe('#e3b866')
+    expect(applicationMarkup()).toContain('Custom frontend')
+    expect(applicationMarkup()).toContain('Ready to build.')
+  })
+})

package/template/.variants/custom/ui/application/index.ts

@@ -1,2 +1,13 @@
+import './styles.css'
+
 /** Framework-neutral presentation tokens and styles for the application. */
 export const applicationTheme = Object.freeze({ accent: '#e3b866' })
+
+/** Pure presentation owned by the application UI feature. */
+export function applicationMarkup(): string {
+  return `
+  <p class="application-eyebrow">Custom frontend</p>
+  <h1>Ready to build.</h1>
+  <p>Replace the application browser entrypoint while preserving its View route.</p>
+`
+}

package/template/.variants/custom/views/application/__tests__/application.view.test.ts

@@ -0,0 +1,15 @@
+import { mountApplication } from '../application.view.js'
+
+describe('application View', () => {
+  it('mounts the UI owned by the application feature', () => {
+    const application = { innerHTML: '' } as HTMLElement
+
+    mountApplication(application)
+
+    expect(application.innerHTML).toContain('Ready to build.')
+  })
+
+  it('rejects a missing browser root', () => {
+    expect(() => mountApplication(null)).toThrow('Custom frontend root #application is missing.')
+  })
+})

package/template/.variants/custom/views/application/app/main.ts

@@ -0,0 +1,3 @@
+import { mountApplication } from '../application.view.js'
+
+mountApplication(document.querySelector<HTMLElement>('#application'))

package/template/.variants/custom/views/application/application.view.ts

@@ -0,0 +1,7 @@
+import { applicationMarkup } from '#ui/application'
+
+/** Mount the application presentation into its browser-owned root. */
+export function mountApplication(application: HTMLElement | null): void {
+  if (application === null) throw new Error('Custom frontend root #application is missing.')
+  application.innerHTML = applicationMarkup()
+}

package/template/.variants/custom/views/application/routes.ts

@@ -1,13 +1,12 @@
-import { frontendArtifact, frontendRoute, viteFrontend } from '@astrale-os/sdk/view'
+import { defineFrontend, vite } from '@astrale-os/sdk/view'
 
 import { schema } from '#schema'
 
 /** Framework-neutral escape hatch: swap Vite or the browser implementation without changing Views. */
-export const frontend = frontendArtifact({
+export const frontend = defineFrontend({
   schema,
-  source: viteFrontend({ root: './views/app' }),
+  source: vite(),
   routes: {
-    application: frontendRoute({ path: '/ui/application', handshake: 'none' }),
+    application: { handshake: 'none' },
   },
-  entrypoint: 'application',
 })

package/template/.variants/custom/vite.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  root: 'views/application/app',
+  build: {
+    outDir: '../../../dist/frontend',
+    emptyOutDir: true,
+  },
+})

package/template/.variants/none/README.md

@@ -4,7 +4,8 @@ This is a callable-only Domain with no frontend artifact or browser assets.
 
 ```text
 schema/             public Domain contract
-implementation.ts   schema and callable handler composition
+runtime.ts          Actions, Workflows, Integrations, Providers, and initialization
+application.ts      Schema and Runtime composition
 tests/               cross-layer executable journeys
 ```
 

package/template/.variants/none/__tests__/variant.test.ts

@@ -0,0 +1,8 @@
+import { application } from '../application.js'
+
+describe('none frontend variant', () => {
+  /** @evidence SDK-V1-SCAFFOLD-NONE */
+  it('rejects an implicit browser frontend by keeping Application headless', () => {
+    expect(application.frontend).toBeUndefined()
+  })
+})

package/template/.variants/none/application.ts

@@ -0,0 +1,8 @@
+import { defineApplication } from '@astrale-os/sdk/application'
+
+import { schema } from '#schema'
+
+import runtime from './runtime.js'
+
+/** Build and publication composition; provider effects live in astrale.config.ts. */
+export const application = defineApplication({ schema, runtime })

package/template/.variants/none/schema/application/index.ts

@@ -1,7 +1,5 @@
 import { defineSchema } from '@astrale-os/sdk/schema'
 
 export const schema = defineSchema('astrale-domain.example.dev', {
-  interfaces: {},
   classes: {},
-  functions: {},
 })

package/template/.variants/react/README.md

@@ -1,23 +1,24 @@
 # Astrale Domain
 
-This project uses the managed React frontend path. `views/routes.ts` is Worker-safe metadata;
-`views/application/application.view.tsx` owns Domain integration; `ui/` owns pure presentation.
-The adapter generates the shell boot module under `views/app/`, builds it, publishes the declared
-route, and serves the immutable static files beside the callable Worker.
+This project is an ordinary Vite React application. `views/routes.ts` is the small Worker-safe
+delivery artifact; `frontend/` owns TanStack Router and browser composition; `ui/` owns reusable
+presentation. It has no mandatory Shell runtime: add `@astrale-os/shell-react` independently when
+the application genuinely needs Shell sessions, graph context, or View-stage integration.
 
 ```text
 schema/             public Domain contract, including View declarations
-implementation.ts   schema, callable handlers, and frontend composition
-views/routes.ts      typed route and browser-module coordinates
-views/application/   Domain-aware React View
-views/app/           managed browser build root
+runtime.ts          Actions, Workflows, Integrations, Providers, and initialization
+application.ts      Schema, Runtime, and frontend composition
+views/              schema-bound frontend declaration
+frontend/            Vite, file-based TanStack Router, and Tailwind entrypoint
 ui/                  styles and pure presentation components
 tests/               cross-layer executable journeys
 ```
 
-Run `pnpm dev` for a local Worker, `pnpm build` to pressure-test Worker and frontend output,
+Run `pnpm dev` for one Worker-facing URL with Vite HMR, `pnpm build` to qualify Worker and frontend output,
 and `pnpm prod` to deploy through the selected adapter. Add semantic `rules/`, `queries/`,
-`mutations/`, and `functions/` modules only when the Domain gains those responsibilities.
+`mutations/`, and `actions/` modules only when the Domain gains those responsibilities.
 
 Domain projects intentionally own no `.spec` trees. Import authoring contracts through semantic
-`@astrale-os/sdk/*` subpaths; never import Kernel Core or DSL directly.
+`@astrale-os/sdk/*` subpaths; never import Kernel Core or DSL directly. Routing remains a normal
+TanStack Router concern; optional Astrale hooks remain normal React hooks inside route components.

package/template/.variants/react/__tests__/variant.test.ts

@@ -0,0 +1,13 @@
+import { application } from '../application.js'
+
+describe('react frontend variant', () => {
+  /** @evidence SDK-V1-SCAFFOLD-REACT */
+  it('rejects missing authored frontend composition', () => {
+    expect(application.frontend).toBeDefined()
+    expect(application.frontend?.source.kind).toBe('vite')
+    expect(application.frontend?.routes.application).toMatchObject({
+      path: '/application',
+      handshake: 'none',
+    })
+  })
+})

package/template/.variants/react/application.ts

@@ -0,0 +1,9 @@
+import { defineApplication } from '@astrale-os/sdk/application'
+
+import { schema } from '#schema'
+import { frontend } from '#views'
+
+import runtime from './runtime.js'
+
+/** Build and publication composition; provider effects live in astrale.config.ts. */
+export const application = defineApplication({ schema, runtime, frontend })

package/template/.variants/react/frontend/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Astrale Domain</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/.variants/react/frontend/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "astrale-frontend",
+  "private": true,
+  "type": "module"
+}