@akanjs/cli 3.0.0-alpha.4 → 3.0.0-alpha.40

package/{quality.command-hy5vt1bh.js → quality.command-g1s2wt8b.js}

@@ -7,18 +7,454 @@ import {
   command,
   runner,
   script
-} from "./index-jk9q6pse.js";
-import"./index-jtm86byd.js";
-import"./index-6pz1j0zj.js";
+} from "./index-n706txcv.js";
+import {
+  appRootAllowedFiles,
+  libFacetRootAllowedFiles
+} from "./index-8vkkm7v0.js";
+import"./index-mxvakhsm.js";
+import"./index-1577bej2.js";
 import"./index-67546d0j.js";
-import"./index-r24hmh0q.js";
+import"./index-yb2wsc7f.js";
 
 // pkgs/@akanjs/devkit/qualityScanner.ts
 import { createHash } from "crypto";
 import { readdir, readFile, stat } from "fs/promises";
 import path from "path";
+import { RESERVED_ROUTE_CONFIG_EXPORTS } from "akanjs/common";
 import ignore from "ignore";
+import ts3 from "typescript";
+
+// pkgs/@akanjs/devkit/formSetterScanner.ts
 import ts from "typescript";
+
+class FormSetterScanner {
+  static #fieldSetter = /^set[A-Za-z0-9_$]*On[A-Za-z0-9_$]*$/;
+  scan(sourceFiles) {
+    return sourceFiles.filter((sourceFile) => sourceFile.file.endsWith(".tsx")).flatMap((f) => this.#scanFile(f));
+  }
+  #scanFile({ file, sourceFile }) {
+    const wrapped = [];
+    const visit = (node) => {
+      if (ts.isJsxAttribute(node)) {
+        const setter = FormSetterScanner.#wrappedSetterOf(node);
+        if (setter)
+          wrapped.push({ setter, line: FormSetterScanner.#lineOf(sourceFile, node) });
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    if (!wrapped.length)
+      return [];
+    const setters = [...new Set(wrapped.map((entry) => entry.setter))].sort();
+    return [
+      {
+        rule: "akan.agent.unpublished-form-setter",
+        scope: "agent",
+        severity: "warning",
+        message: setters.length === 1 ? `${setters[0]} is reached through a wrapper, so that field publishes no agent tool and carries no data-akan-action.` : `${setters.length} field setters are reached through a wrapper, so those fields publish no agent tool and carry no data-akan-action: ${setters.join(", ")}.`,
+        file,
+        line: wrapped[0]?.line,
+        locations: wrapped.map(({ line }) => ({ file, line }))
+      }
+    ];
+  }
+  static #wrappedSetterOf(attribute) {
+    if (!ts.isIdentifier(attribute.name) || !/^on[A-Z]/.test(attribute.name.text))
+      return null;
+    const initializer = attribute.initializer;
+    if (!initializer || !ts.isJsxExpression(initializer) || !initializer.expression)
+      return null;
+    const handler = initializer.expression;
+    if (!ts.isArrowFunction(handler) && !ts.isFunctionExpression(handler))
+      return null;
+    if (!handler.parameters.length)
+      return null;
+    return FormSetterScanner.#setterCallIn(handler.body);
+  }
+  static #setterCallIn(node) {
+    let found = null;
+    const visit = (current) => {
+      if (found)
+        return;
+      if (ts.isCallExpression(current) && ts.isPropertyAccessExpression(current.expression)) {
+        const { expression, name } = current.expression;
+        if (ts.isPropertyAccessExpression(expression) && ts.isIdentifier(expression.expression) && expression.expression.text === "st" && expression.name.text === "do" && FormSetterScanner.#fieldSetter.test(name.text)) {
+          found = name.text;
+          return;
+        }
+      }
+      ts.forEachChild(current, visit);
+    };
+    visit(node);
+    return found;
+  }
+  static #lineOf(sourceFile, node) {
+    return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+  }
+}
+
+// pkgs/@akanjs/devkit/ssrScanner.ts
+import ts2 from "typescript";
+var STATIC_COMPONENT_MIN_MASS = 4;
+var MIXED_COMPONENT_MIN_MASS = 10;
+var MIXED_COMPONENT_MAX_TOUCHES = 2;
+var MODULE_SERVER_VIEW_MIN_CLIENT_MASS = 12;
+
+class SsrScanner {
+  static #serverSafeCalls = new Set(["usePage", "getSelf", "useServer"]);
+  static #clientGlobals = new Set([
+    "window",
+    "document",
+    "navigator",
+    "localStorage",
+    "sessionStorage",
+    "location",
+    "history",
+    "screen",
+    "matchMedia",
+    "IntersectionObserver",
+    "ResizeObserver",
+    "MutationObserver",
+    "requestAnimationFrame",
+    "WebSocket"
+  ]);
+  static #clientRuntimeImports = new Set(["st", "fetch"]);
+  scan(sourceFiles) {
+    const componentFiles = sourceFiles.filter((sourceFile) => this.#isBalancedFile(sourceFile.file));
+    return {
+      warnings: [
+        ...componentFiles.flatMap((sourceFile) => this.#scanFile(sourceFile)),
+        ...this.#scanModules(componentFiles)
+      ],
+      balance: this.#measureBalance(componentFiles)
+    };
+  }
+  #scanFile(sourceFile) {
+    if (!this.#hasUseClient(sourceFile.sourceFile))
+      return [];
+    const vendorNames = this.#getVendorNames(sourceFile.sourceFile);
+    const hasVendorImport = this.#hasVendorImport(sourceFile.sourceFile);
+    const importsClientRuntime = this.#importsClientRuntime(sourceFile.sourceFile);
+    const components = this.#getComponents(sourceFile, vendorNames);
+    const warnings = [];
+    if (!hasVendorImport && !importsClientRuntime && this.#getTouches(sourceFile.sourceFile, sourceFile.sourceFile).length === 0 && !this.#isConventionClientFile(sourceFile.file)) {
+      warnings.push({
+        rule: "akan.ssr.unnecessary-use-client",
+        scope: "ssr",
+        severity: "warning",
+        file: sourceFile.file,
+        line: 1,
+        message: `"use client" is declared but the file uses no client-only capability (hook, event handler, store, or browser API).`
+      });
+    }
+    for (const component of components) {
+      if (component.vendorTags)
+        continue;
+      if (component.touches.length === 0 && component.mass >= STATIC_COMPONENT_MIN_MASS) {
+        warnings.push({
+          rule: "akan.ssr.client-static-component",
+          scope: "ssr",
+          severity: "warning",
+          file: sourceFile.file,
+          line: component.line,
+          message: `Client component "${component.name}" renders ${component.mass} JSX elements with no client-only capability. It is server-renderable markup sitting in the client bundle.`
+        });
+        continue;
+      }
+      if (component.touches.length >= 1 && component.touches.length <= MIXED_COMPONENT_MAX_TOUCHES && component.mass >= MIXED_COMPONENT_MIN_MASS) {
+        warnings.push({
+          rule: "akan.ssr.client-static-markup",
+          scope: "ssr",
+          severity: "warning",
+          file: sourceFile.file,
+          line: component.line,
+          message: `Client component "${component.name}" renders ${component.mass} JSX elements around only ${component.touches.length} client-only touch (${[...new Set(component.touches)].join(", ")}). Most of this subtree does not need the client bundle.`
+        });
+      }
+    }
+    warnings.push(...this.#getMountLoadWarnings(sourceFile));
+    warnings.push(...this.#getTemplateStateWarnings(sourceFile));
+    return warnings;
+  }
+  #scanModules(sourceFiles) {
+    const modules = new Map;
+    for (const sourceFile of sourceFiles) {
+      const moduleDir = this.#getModuleDir(sourceFile.file);
+      if (!moduleDir)
+        continue;
+      const entry = modules.get(moduleDir) ?? { clientMass: 0, serverFiles: 0, line: sourceFile.file };
+      if (this.#hasUseClient(sourceFile.sourceFile))
+        entry.clientMass += this.#getMass(sourceFile.sourceFile);
+      else if (/\.(Unit|View)\.tsx$/.test(sourceFile.file))
+        entry.serverFiles += 1;
+      modules.set(moduleDir, entry);
+    }
+    return [...modules].filter(([, entry]) => entry.serverFiles === 0 && entry.clientMass >= MODULE_SERVER_VIEW_MIN_CLIENT_MASS).map(([moduleDir, entry]) => ({
+      rule: "akan.ssr.module-missing-server-view",
+      scope: "ssr",
+      severity: "warning",
+      file: entry.line,
+      message: `Module "${moduleDir}" renders ${entry.clientMass} JSX elements from client files only; it declares no Unit or View server component.`
+    }));
+  }
+  #getMountLoadWarnings(sourceFile) {
+    const warnings = [];
+    const visit = (node) => {
+      if (this.#isMountEffect(sourceFile.sourceFile, node)) {
+        for (const load of this.#getLoadCalls(sourceFile.sourceFile, node)) {
+          warnings.push({
+            rule: "akan.ssr.client-mount-load",
+            scope: "ssr",
+            severity: "warning",
+            file: sourceFile.file,
+            line: this.#getLine(sourceFile.sourceFile, load.node),
+            message: `Mount-only effect loads server data with ${load.callee}(). The route can fetch this before the first byte instead.`
+          });
+        }
+      }
+      ts2.forEachChild(node, visit);
+    };
+    ts2.forEachChild(sourceFile.sourceFile, visit);
+    return warnings;
+  }
+  #isMountEffect(sourceFile, node) {
+    if (!ts2.isCallExpression(node))
+      return false;
+    const callee = node.expression.getText(sourceFile);
+    if (callee !== "useEffect" && callee !== "useLayoutEffect")
+      return false;
+    const deps = node.arguments[1];
+    return !!deps && ts2.isArrayLiteralExpression(deps) && deps.elements.length === 0;
+  }
+  #getLoadCalls(sourceFile, node) {
+    const calls = [];
+    const visit = (child) => {
+      if (ts2.isCallExpression(child)) {
+        const callee = child.expression.getText(sourceFile);
+        if (/^fetch\.[a-z]/.test(callee) || /^st\.do\.(init|get|view|load|list|count|insight)[A-Z]/.test(callee))
+          calls.push({ callee, node: child });
+      }
+      ts2.forEachChild(child, visit);
+    };
+    ts2.forEachChild(node, visit);
+    return calls;
+  }
+  #getTemplateStateWarnings(sourceFile) {
+    if (!sourceFile.file.endsWith(".Template.tsx"))
+      return [];
+    const warnings = [];
+    const visit = (node) => {
+      if (ts2.isCallExpression(node) && node.expression.getText(sourceFile.sourceFile) === "useState") {
+        warnings.push({
+          rule: "akan.ssr.template-client-state",
+          scope: "ssr",
+          severity: "warning",
+          file: sourceFile.file,
+          line: this.#getLine(sourceFile.sourceFile, node),
+          message: "Template holds form state in useState. Templates are store-driven and carry no local state."
+        });
+      }
+      ts2.forEachChild(node, visit);
+    };
+    ts2.forEachChild(sourceFile.sourceFile, visit);
+    return warnings;
+  }
+  #measureBalance(sourceFiles) {
+    const scopes = new Map;
+    for (const sourceFile of sourceFiles) {
+      const segments = sourceFile.file.split("/");
+      const scope = `${segments[0]}/${segments[1]}`;
+      const entry = scopes.get(scope) ?? { serverMass: 0, clientMass: 0 };
+      const mass = this.#getMass(sourceFile.sourceFile);
+      if (this.#hasUseClient(sourceFile.sourceFile))
+        entry.clientMass += mass;
+      else
+        entry.serverMass += mass;
+      scopes.set(scope, entry);
+    }
+    const entries = [...scopes].map(([scope, mass]) => ({ scope, ...mass, serverShare: getShare(mass.serverMass, mass.clientMass) })).sort((a, b) => a.scope.localeCompare(b.scope));
+    if (entries.length < 2)
+      return entries;
+    const serverMass = entries.reduce((sum, entry) => sum + entry.serverMass, 0);
+    const clientMass = entries.reduce((sum, entry) => sum + entry.clientMass, 0);
+    return [...entries, { scope: "workspace", serverMass, clientMass, serverShare: getShare(serverMass, clientMass) }];
+  }
+  #getComponents(sourceFile, vendorNames) {
+    const components = [];
+    for (const statement of sourceFile.sourceFile.statements) {
+      for (const { name, node } of this.#getComponentNodes(statement)) {
+        if (!/^[A-Z]/.test(name))
+          continue;
+        components.push({
+          name,
+          line: this.#getLine(sourceFile.sourceFile, node),
+          mass: this.#getMass(node),
+          touches: this.#getTouches(sourceFile.sourceFile, node),
+          vendorTags: [...this.#getTagNames(sourceFile.sourceFile, node)].some((tag) => vendorNames.has(tag))
+        });
+      }
+    }
+    return components;
+  }
+  #getComponentNodes(statement) {
+    if (ts2.isFunctionDeclaration(statement) && statement.body)
+      return [{ name: statement.name?.text ?? "default", node: statement.body }];
+    if (!ts2.isVariableStatement(statement))
+      return [];
+    return statement.declarationList.declarations.flatMap((declaration) => {
+      if (!ts2.isIdentifier(declaration.name) || !declaration.initializer)
+        return [];
+      if (!ts2.isArrowFunction(declaration.initializer) && !ts2.isFunctionExpression(declaration.initializer))
+        return [];
+      return [{ name: declaration.name.text, node: declaration.initializer }];
+    });
+  }
+  #getTouches(sourceFile, node) {
+    const touches = [];
+    const visit = (child) => {
+      if (ts2.isCallExpression(child)) {
+        const callee = child.expression.getText(sourceFile);
+        const bareName = callee.split(".").pop() ?? callee;
+        if (callee === "createContext" || callee === "lazy")
+          touches.push(callee);
+        else if (/^use[A-Z]/.test(bareName) && !SsrScanner.#serverSafeCalls.has(bareName))
+          touches.push(bareName);
+      }
+      if (ts2.isJsxAttribute(child) && /^on[A-Z]/.test(child.name.getText(sourceFile)))
+        touches.push(child.name.getText(sourceFile));
+      if (ts2.isPropertyAccessExpression(child)) {
+        const root = getAccessRoot(child);
+        if (root === "st")
+          touches.push("st");
+        else if (SsrScanner.#clientGlobals.has(root))
+          touches.push(root);
+      }
+      ts2.forEachChild(child, visit);
+    };
+    ts2.forEachChild(node, visit);
+    return touches;
+  }
+  #getTagNames(sourceFile, node) {
+    const tags = new Set;
+    const visit = (child) => {
+      if (ts2.isJsxOpeningElement(child) || ts2.isJsxSelfClosingElement(child))
+        tags.add(child.tagName.getText(sourceFile).split(".")[0]);
+      ts2.forEachChild(child, visit);
+    };
+    ts2.forEachChild(node, visit);
+    return tags;
+  }
+  #getMass(node) {
+    let mass = 0;
+    const visit = (child) => {
+      if (ts2.isJsxOpeningElement(child) || ts2.isJsxSelfClosingElement(child))
+        mass += 1;
+      ts2.forEachChild(child, visit);
+    };
+    ts2.forEachChild(node, visit);
+    return mass;
+  }
+  #hasUseClient(sourceFile) {
+    const first = sourceFile.statements[0];
+    if (!first || !ts2.isExpressionStatement(first) || !ts2.isStringLiteral(first.expression))
+      return false;
+    return first.expression.text === "use client";
+  }
+  #hasVendorImport(sourceFile) {
+    return sourceFile.statements.some((statement) => ts2.isImportDeclaration(statement) && isVendorSpecifier(getSpecifier(statement)));
+  }
+  #getVendorNames(sourceFile) {
+    const names = new Set;
+    for (const statement of sourceFile.statements) {
+      if (!ts2.isImportDeclaration(statement) || !isVendorSpecifier(getSpecifier(statement)))
+        continue;
+      const clause = statement.importClause;
+      if (clause?.name)
+        names.add(clause.name.text);
+      if (clause?.namedBindings && ts2.isNamespaceImport(clause.namedBindings))
+        names.add(clause.namedBindings.name.text);
+      if (clause?.namedBindings && ts2.isNamedImports(clause.namedBindings))
+        for (const element of clause.namedBindings.elements)
+          names.add(element.name.text);
+    }
+    return names;
+  }
+  #importsClientRuntime(sourceFile) {
+    for (const statement of sourceFile.statements) {
+      if (!ts2.isImportDeclaration(statement))
+        continue;
+      const bindings = statement.importClause?.namedBindings;
+      if (!bindings || !ts2.isNamedImports(bindings))
+        continue;
+      if (bindings.elements.some((element) => SsrScanner.#clientRuntimeImports.has(element.name.text)))
+        return true;
+    }
+    return false;
+  }
+  #isConventionClientFile(file) {
+    if (file.endsWith("/index_.tsx"))
+      return true;
+    return /\.(Zone|Template|Util)\.tsx$/.test(file) && this.#getModuleDir(file) !== null;
+  }
+  #isBalancedFile(file) {
+    if (!file.endsWith(".tsx") || file.endsWith(".test.tsx") || file.endsWith(".spec.tsx"))
+      return false;
+    const segments = file.split("/");
+    if (segments[0] !== "apps" && segments[0] !== "libs")
+      return false;
+    return segments[2] === "ui" || segments[2] === "lib";
+  }
+  #getModuleDir(file) {
+    const segments = file.split("/");
+    const libIndex = segments.indexOf("lib");
+    if (libIndex < 1 || segments.length <= libIndex + 2)
+      return null;
+    const moduleName = segments[libIndex + 1];
+    if (moduleName.startsWith("_"))
+      return null;
+    return segments.slice(0, libIndex + 2).join("/");
+  }
+  #getLine(sourceFile, node) {
+    return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+  }
+}
+var SSR_SERVER_SHARE_TARGET = 0.5;
+function formatSsrBalance(balance) {
+  if (balance.length === 0)
+    return ["No component files found."];
+  return balance.map((entry) => {
+    const total = entry.serverMass + entry.clientMass;
+    const share = `${Math.round(entry.serverShare * 100)}% server`;
+    const counts = `${entry.serverMass} of ${total} JSX elements, ${entry.clientMass} client`;
+    const flag = entry.serverShare < SSR_SERVER_SHARE_TARGET ? `  <- below the ${Math.round(SSR_SERVER_SHARE_TARGET * 100)}% target` : "";
+    return `  ${entry.scope}: ${share} (${counts})${flag}`;
+  });
+}
+function getShare(serverMass, clientMass) {
+  const total = serverMass + clientMass;
+  return total === 0 ? 1 : serverMass / total;
+}
+function getSpecifier(statement) {
+  return ts2.isStringLiteral(statement.moduleSpecifier) ? statement.moduleSpecifier.text : "";
+}
+function isVendorSpecifier(specifier) {
+  if (specifier === "" || specifier.startsWith(".") || specifier.startsWith("/"))
+    return false;
+  if (specifier === "react" || specifier === "react-dom" || specifier.startsWith("react/"))
+    return false;
+  if (specifier.startsWith("node:"))
+    return false;
+  return !/^(akanjs|@akanjs|@libs|@apps|@contract)(\/|$)/.test(specifier);
+}
+function getAccessRoot(node) {
+  let current = node;
+  while (ts2.isPropertyAccessExpression(current))
+    current = current.expression;
+  return ts2.isIdentifier(current) ? current.text : "";
+}
+
+// pkgs/@akanjs/devkit/qualityScanner.ts
 var MAX_FILE_LINES = 2000;
 var PLACEHOLDER_EXPORT_NAMES = new Set([
   "aa",
@@ -39,30 +475,10 @@ var SUGGESTED_RULES = [
   "Keep apps/*/lib and libs/*/lib root files limited to generated support facets such as cnst.ts, db.ts, dict.ts, sig.ts, srv.ts, st.ts, useClient.ts, and useServer.ts.",
   "Use domain module folders consistently: lib/<model> for database modules, lib/_<service> for service modules, and lib/__scalar/<scalar> for scalar modules.",
   "Keep module UI filenames predictable: database modules use <Model>.Template/Unit/Util/View/Zone.tsx, service modules use <Service>.Util/Zone.tsx, and scalar modules use <Scalar>.Template/Unit.tsx.",
+  "Hand a form control its store setter by reference so the field publishes an agent tool; put normalization in the control's transform prop and a multi-write in a _postSet<Field> hook on the store.",
   "Move shared app utilities to apps/*/common instead of creating apps/*/base.",
   "Avoid large mixed-purpose class files; class export files should import helpers from neighboring utility files instead of declaring them inline."
 ];
-var APP_ROOT_FILES = new Set([
-  "akan.app.json",
-  "akan.config.ts",
-  "capacitor.config.ts",
-  "client.ts",
-  "main.ts",
-  "package.json",
-  "server.ts",
-  "tsconfig.json"
-]);
-var LIB_ROOT_FILES = new Set([
-  "cnst.ts",
-  "db.ts",
-  "dict.ts",
-  "option.ts",
-  "sig.ts",
-  "srv.ts",
-  "st.ts",
-  "useClient.ts",
-  "useServer.ts"
-]);
 var CONVENTION_SUFFIXES = [
   ".constant.ts",
   ".dictionary.ts",
@@ -71,20 +487,6 @@ var CONVENTION_SUFFIXES = [
   ".signal.ts",
   ".store.ts"
 ];
-var PAGE_RESERVED_EXPORTS = new Set([
-  "pageConfig",
-  "head",
-  "metadata",
-  "generateHead",
-  "generateMetadata",
-  "fonts",
-  "manifest",
-  "theme",
-  "reconnect",
-  "wsConnect",
-  "layoutStyle",
-  "gaTrackingId"
-]);
 var RULE_FIXES = {
   "akan.global.duplicate-exported-function-name": "Rename one of the exports, or if they are the same thing, extract it into one shared module and import it in both places.",
   "akan.global.duplicate-exported-function-body": "Extract the shared implementation into a single exported helper and import it, instead of copying the body.",
@@ -97,11 +499,18 @@ var RULE_FIXES = {
   "akan.file.window-augmentation": "Move the Window augmentation into an approved browser integration file and keep it isolated.",
   "akan.file.prototype-mutation": "Avoid prototype mutation, or isolate it in an approved low-level integration file.",
   "akan.file.class-export-global-declaration": "Move the helper to a sibling file and import it into the class module.",
+  "akan.agent.unpublished-form-setter": "Pass the setter by reference where the wrapper only forwards (onChange={st.do.setTitleOnTask}); move normalization into the control's own transform prop; move a multi-write into a _postSet<Field> hook on the store, keeping the generated setter on the control.",
   "akan.file.component-internal-declaration": "Move the type or helper to a type/util file in ui/, webkit/, or common/ by purpose. If it is the component's props, declare it as `interface <Component>Props`.",
   "akan.file.component-export": "Move the value or type to a util/constant/type file in ui/, webkit/, or common/ and import it. Adding `export` is not a valid fix \u2014 only PascalCase components and their `<Component>Props` interface belong here.",
   "akan.layout.app-root-file": "Move the file into a conventional app folder (common, env, lib, page, private, public, script, srvkit, ui, or webkit).",
   "akan.layout.lib-root-file": "Move the file into a domain module folder under lib/; keep lib root limited to generated support facets.",
-  "akan.layout.module-ui-file": "Rename the file to an allowed module UI name, or move it to ui/ if it is not a module component."
+  "akan.layout.module-ui-file": "Rename the file to an allowed module UI name, or move it to ui/ if it is not a module component.",
+  "akan.ssr.unnecessary-use-client": 'Delete the "use client" directive so the file renders on the server. If it exists only to wrap one client child, drop the wrapper and use the child directly.',
+  "akan.ssr.client-static-component": "Move the component to a server file \u2014 a <Model>.Unit.tsx / <Model>.View.tsx for a module, or a ui/ file with no directive \u2014 and reference it from the client file.",
+  "akan.ssr.client-static-markup": "Keep the interactive element in the client component and hoist the static subtree into a server component, then accept it as `children` or render it through a Unit/View reference.",
+  "akan.ssr.client-mount-load": "Load the data in the route with `fetch.initX(...)` / `fetch.viewX(...)` and pass the init/view object down as a prop; the client store hydrates from it and the effect goes away.",
+  "akan.ssr.module-missing-server-view": "Add a <Model>.Unit.tsx for list/card rendering and a <Model>.View.tsx for the detail surface, then have the Zone delegate to them.",
+  "akan.ssr.template-client-state": "Bind the field to the store instead: `value={xForm.field}` with `onChange={st.do.setFieldOnX}`."
 };
 function getRuleFix(rule) {
   if (rule.startsWith("akan.convention"))
@@ -114,18 +523,22 @@ class AkanQualityScanner {
     const targetFiles = await this.#collectTargetFiles(workspaceRoot);
     const sourceFiles = await Promise.all(targetFiles.filter((file) => !AbstractDoc.isAbstractPath(file)).map((file) => this.#readSourceFile(workspaceRoot, file)));
     const abstractFiles = await Promise.all(targetFiles.filter((file) => AbstractDoc.isAbstractPath(file)).map((file) => this.#readTextFile(workspaceRoot, file)));
+    const ssr = new SsrScanner().scan(sourceFiles);
     const warnings = [
       ...this.#scanGlobalQuality(sourceFiles),
       ...sourceFiles.flatMap((sourceFile) => this.#scanSingleFileQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanComponentQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanConventionQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
-      ...abstractFiles.flatMap((abstractFile) => this.#scanAbstractQuality(abstractFile))
+      ...abstractFiles.flatMap((abstractFile) => this.#scanAbstractQuality(abstractFile)),
+      ...new FormSetterScanner().scan(sourceFiles),
+      ...ssr.warnings
     ];
     return {
       workspaceRoot,
       scannedFiles: sourceFiles.length + abstractFiles.length,
       warnings: warnings.map((warning) => ({ ...warning, fix: warning.fix ?? getRuleFix(warning.rule) })).sort(compareWarnings),
+      ssrBalance: ssr.balance,
       suggestedRules: SUGGESTED_RULES
     };
   }
@@ -171,7 +584,7 @@ class AkanQualityScanner {
       file,
       absolutePath,
       content,
-      sourceFile: ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, getScriptKind(file))
+      sourceFile: ts3.createSourceFile(file, content, ts3.ScriptTarget.Latest, true, getScriptKind(file))
     };
   }
   async#readTextFile(workspaceRoot, file) {
@@ -332,7 +745,7 @@ class AkanQualityScanner {
   #scanLayoutQuality(sourceFile) {
     const segments = sourceFile.file.split("/");
     const warnings = [];
-    if (segments[0] === "apps" && segments.length === 3 && !APP_ROOT_FILES.has(segments[2])) {
+    if (segments[0] === "apps" && segments.length === 3 && !appRootAllowedFiles.has(segments[2])) {
       warnings.push({
         rule: "akan.layout.app-root-file",
         scope: "layout",
@@ -342,7 +755,7 @@ class AkanQualityScanner {
       });
     }
     const libRootFile = getLibRootFile(sourceFile.file);
-    if (libRootFile && !LIB_ROOT_FILES.has(libRootFile)) {
+    if (libRootFile && !libFacetRootAllowedFiles.has(libRootFile)) {
       warnings.push({
         rule: "akan.layout.lib-root-file",
         scope: "layout",
@@ -368,6 +781,10 @@ function formatQualityScanResult(result) {
     "",
     ...formatQualityWarnings(result.warnings),
     "",
+    "SSR balance (component files, JSX elements rendered per side):",
+    "",
+    ...formatSsrBalance(result.ssrBalance),
+    "",
     "Suggested quality rules:",
     "",
     ...result.suggestedRules.map((rule) => `  - ${rule}`)
@@ -375,6 +792,24 @@ function formatQualityScanResult(result) {
   return sections.join(`
 `);
 }
+function formatSsrScanResult(result) {
+  const sections = [
+    "Akan SSR Balance Scan",
+    `workspace: ${result.workspaceRoot}`,
+    `scanned files: ${result.scannedFiles}`,
+    `ssr warnings: ${result.warnings.length}`,
+    "",
+    "Server render share (component files, JSX elements rendered per side):",
+    "",
+    ...formatSsrBalance(result.ssrBalance),
+    "",
+    "Warnings:",
+    "",
+    ...formatQualityWarnings(result.warnings)
+  ];
+  return sections.join(`
+`);
+}
 function formatQualityWarnings(warnings) {
   if (warnings.length === 0)
     return ["No warnings found."];
@@ -396,7 +831,7 @@ function getExportedFunctionLikes(sourceFile) {
   const declarations = [];
   const nameExempt = isPageRouteFile(sourceFile.file) || isUiComponentFile(sourceFile.file);
   for (const statement of sourceFile.sourceFile.statements) {
-    if (ts.isFunctionDeclaration(statement) && statement.name && isExported(statement)) {
+    if (ts3.isFunctionDeclaration(statement) && statement.name && isExported(statement)) {
       declarations.push({
         name: statement.name.text,
         kind: "function",
@@ -406,7 +841,7 @@ function getExportedFunctionLikes(sourceFile) {
         duplicateNameExempt: nameExempt || isConventionDuplicateNameExempt(sourceFile.file, false)
       });
     }
-    if (ts.isClassDeclaration(statement) && statement.name && isExported(statement)) {
+    if (ts3.isClassDeclaration(statement) && statement.name && isExported(statement)) {
       declarations.push({
         name: statement.name.text,
         kind: "class",
@@ -416,9 +851,9 @@ function getExportedFunctionLikes(sourceFile) {
         duplicateNameExempt: nameExempt || isConventionDuplicateNameExempt(sourceFile.file, isEnumClassStatement(sourceFile.sourceFile, statement))
       });
     }
-    if (ts.isVariableStatement(statement) && isExported(statement)) {
+    if (ts3.isVariableStatement(statement) && isExported(statement)) {
       for (const declaration of statement.declarationList.declarations) {
-        if (!ts.isIdentifier(declaration.name) || !isFunctionLikeInitializer(declaration.initializer))
+        if (!ts3.isIdentifier(declaration.name) || !isFunctionLikeInitializer(declaration.initializer))
           continue;
         declarations.push({
           name: declaration.name.text,
@@ -457,14 +892,14 @@ function isInLibModule(file) {
   return (segments[0] === "apps" || segments[0] === "libs") && segments.includes("lib");
 }
 function isEnumClassStatement(sourceFile, statement) {
-  if (!ts.isClassDeclaration(statement))
+  if (!ts3.isClassDeclaration(statement))
     return false;
-  const heritageClause = statement.heritageClauses?.find((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword);
+  const heritageClause = statement.heritageClauses?.find((clause) => clause.token === ts3.SyntaxKind.ExtendsKeyword);
   const expression = heritageClause?.types[0]?.expression;
   return !!expression && expression.getText(sourceFile).startsWith("enumOf(");
 }
 function getExportedClassNames(sourceFile) {
-  return sourceFile.statements.filter((statement) => ts.isClassDeclaration(statement) && !!statement.name).filter((statement) => isExported(statement)).map((statement) => statement.name.text);
+  return sourceFile.statements.filter((statement) => ts3.isClassDeclaration(statement) && !!statement.name).filter((statement) => isExported(statement)).map((statement) => statement.name.text);
 }
 function isComponentDeclarationFile(file) {
   if (!file.endsWith(".tsx"))
@@ -480,7 +915,7 @@ function isComponentDeclarationFile(file) {
 function getComponentFileDeclarations(sourceFile) {
   const reExportedNames = new Set;
   for (const statement of sourceFile.statements) {
-    if (ts.isExportDeclaration(statement) && statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+    if (ts3.isExportDeclaration(statement) && statement.exportClause && ts3.isNamedExports(statement.exportClause)) {
       for (const element of statement.exportClause.elements)
         reExportedNames.add((element.propertyName ?? element.name).text);
     }
@@ -490,19 +925,19 @@ function getComponentFileDeclarations(sourceFile) {
     const isDefaultExport = isDefaultExportStatement(statement);
     const inlineExported = isExported(statement);
     const add = (name, kind, line) => declarations.push({ name, kind, line, exported: inlineExported || reExportedNames.has(name), isDefaultExport });
-    if (ts.isInterfaceDeclaration(statement))
+    if (ts3.isInterfaceDeclaration(statement))
       add(statement.name.text, "interface", getLine(sourceFile, statement));
-    else if (ts.isTypeAliasDeclaration(statement))
+    else if (ts3.isTypeAliasDeclaration(statement))
       add(statement.name.text, "type", getLine(sourceFile, statement));
-    else if (ts.isEnumDeclaration(statement))
+    else if (ts3.isEnumDeclaration(statement))
       add(statement.name.text, "enum", getLine(sourceFile, statement));
-    else if (ts.isFunctionDeclaration(statement) && statement.name)
+    else if (ts3.isFunctionDeclaration(statement) && statement.name)
       add(statement.name.text, "function", getLine(sourceFile, statement));
-    else if (ts.isClassDeclaration(statement) && statement.name)
+    else if (ts3.isClassDeclaration(statement) && statement.name)
       add(statement.name.text, "class", getLine(sourceFile, statement));
-    else if (ts.isVariableStatement(statement)) {
+    else if (ts3.isVariableStatement(statement)) {
       for (const declaration of statement.declarationList.declarations) {
-        if (!ts.isIdentifier(declaration.name))
+        if (!ts3.isIdentifier(declaration.name))
           continue;
         const kind = isFunctionLikeInitializer(declaration.initializer) ? "function" : "variable";
         add(declaration.name.text, kind, getLine(sourceFile, declaration));
@@ -514,15 +949,15 @@ function getComponentFileDeclarations(sourceFile) {
 function getCompoundComponentNames(sourceFile) {
   const names = new Set;
   for (const statement of sourceFile.statements) {
-    if (!ts.isExpressionStatement(statement))
+    if (!ts3.isExpressionStatement(statement))
       continue;
     const { expression } = statement;
-    if (!ts.isBinaryExpression(expression) || expression.operatorToken.kind !== ts.SyntaxKind.EqualsToken)
+    if (!ts3.isBinaryExpression(expression) || expression.operatorToken.kind !== ts3.SyntaxKind.EqualsToken)
       continue;
-    if (!ts.isPropertyAccessExpression(expression.left) || !isPascalCaseName(expression.left.name.text))
+    if (!ts3.isPropertyAccessExpression(expression.left) || !isPascalCaseName(expression.left.name.text))
       continue;
     names.add(expression.left.name.text);
-    if (ts.isIdentifier(expression.right) && isPascalCaseName(expression.right.text))
+    if (ts3.isIdentifier(expression.right) && isPascalCaseName(expression.right.text))
       names.add(expression.right.text);
   }
   return names;
@@ -536,15 +971,15 @@ function isRestrictedInternalKind(kind) {
 function isAllowedComponentExport(declaration, isPage) {
   if (isComponentValueKind(declaration.kind) && isPascalCaseName(declaration.name))
     return true;
-  return isPage && PAGE_RESERVED_EXPORTS.has(declaration.name);
+  return isPage && RESERVED_ROUTE_CONFIG_EXPORTS.has(declaration.name);
 }
 function isPascalCaseName(name) {
   return /^[A-Z]/.test(name) && !/^[A-Z0-9_]+$/.test(name);
 }
 function isDefaultExportStatement(statement) {
-  if (ts.isExportAssignment(statement))
+  if (ts3.isExportAssignment(statement))
     return !statement.isExportEquals;
-  return !!(ts.getCombinedModifierFlags(statement) & ts.ModifierFlags.Default);
+  return !!(ts3.getCombinedModifierFlags(statement) & ts3.ModifierFlags.Default);
 }
 function getPlaceholderExportWarnings(sourceFile) {
   if (!sourceFile.file.endsWith("/index.ts") && !sourceFile.file.endsWith("/index.tsx"))
@@ -574,7 +1009,7 @@ function getDictionaryTextWarnings(sourceFile) {
 function getGlobalMutationWarnings(sourceFile) {
   const warnings = [];
   for (const statement of sourceFile.sourceFile.statements) {
-    if (ts.isModuleDeclaration(statement) && statement.name.getText(sourceFile.sourceFile) === "global") {
+    if (ts3.isModuleDeclaration(statement) && statement.name.getText(sourceFile.sourceFile) === "global") {
       warnings.push({
         rule: "akan.file.global-declaration",
         scope: "file",
@@ -584,7 +1019,7 @@ function getGlobalMutationWarnings(sourceFile) {
         message: "Global declarations require an explicit low-level integration allowlist."
       });
     }
-    if (ts.isInterfaceDeclaration(statement) && statement.name.text === "Window") {
+    if (ts3.isInterfaceDeclaration(statement) && statement.name.text === "Window") {
       warnings.push({
         rule: "akan.file.window-augmentation",
         scope: "file",
@@ -594,7 +1029,7 @@ function getGlobalMutationWarnings(sourceFile) {
         message: "Window augmentation should be isolated to approved browser integration files."
       });
     }
-    if (ts.isExpressionStatement(statement) && statement.expression.getText(sourceFile.sourceFile).includes(".prototype.")) {
+    if (ts3.isExpressionStatement(statement) && statement.expression.getText(sourceFile.sourceFile).includes(".prototype.")) {
       warnings.push({
         rule: "akan.file.prototype-mutation",
         scope: "file",
@@ -612,23 +1047,23 @@ function getTopLevelDeclarations(sourceFile) {
 }
 function getTopLevelDeclaration(sourceFile, statement) {
   const line = getLine(sourceFile, statement);
-  if (ts.isClassDeclaration(statement) && statement.name) {
+  if (ts3.isClassDeclaration(statement) && statement.name) {
     return [{ name: statement.name.text, kind: "class", line, exported: isExported(statement), node: statement }];
   }
-  if (ts.isFunctionDeclaration(statement) && statement.name) {
+  if (ts3.isFunctionDeclaration(statement) && statement.name) {
     return [{ name: statement.name.text, kind: "function", line, exported: isExported(statement), node: statement }];
   }
-  if (ts.isInterfaceDeclaration(statement)) {
+  if (ts3.isInterfaceDeclaration(statement)) {
     return [{ name: statement.name.text, kind: "interface", line, exported: isExported(statement), node: statement }];
   }
-  if (ts.isTypeAliasDeclaration(statement)) {
+  if (ts3.isTypeAliasDeclaration(statement)) {
     return [{ name: statement.name.text, kind: "type", line, exported: isExported(statement), node: statement }];
   }
-  if (ts.isEnumDeclaration(statement)) {
+  if (ts3.isEnumDeclaration(statement)) {
     return [{ name: statement.name.text, kind: "enum", line, exported: isExported(statement), node: statement }];
   }
-  if (ts.isVariableStatement(statement)) {
-    return statement.declarationList.declarations.filter((declaration) => ts.isIdentifier(declaration.name)).map((declaration) => ({
+  if (ts3.isVariableStatement(statement)) {
+    return statement.declarationList.declarations.filter((declaration) => ts3.isIdentifier(declaration.name)).map((declaration) => ({
       name: declaration.name.text,
       kind: "variable",
       line: getLine(sourceFile, declaration),
@@ -636,7 +1071,7 @@ function getTopLevelDeclaration(sourceFile, statement) {
       node: statement
     }));
   }
-  if (ts.isExportDeclaration(statement)) {
+  if (ts3.isExportDeclaration(statement)) {
     return [{ name: "export declaration", kind: "export", line, exported: true, node: statement }];
   }
   return [];
@@ -661,9 +1096,9 @@ function isAllowedConstantDeclaration(modelName, declaration) {
     return false;
   if ([`${modelName}Input`, `${modelName}Object`, modelName, `Light${modelName}`, `${modelName}Insight`].includes(declaration.name))
     return true;
-  if (!ts.isClassDeclaration(declaration.node))
+  if (!ts3.isClassDeclaration(declaration.node))
     return false;
-  const heritageClause = declaration.node.heritageClauses?.find((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword);
+  const heritageClause = declaration.node.heritageClauses?.find((clause) => clause.token === ts3.SyntaxKind.ExtendsKeyword);
   const expression = heritageClause?.types[0]?.expression;
   return !!expression && expression.getText().startsWith("enumOf(");
 }
@@ -729,13 +1164,13 @@ function getModuleInfo(file) {
   return { moduleName, fileName, kind: "database" };
 }
 function isExportedConst(declaration) {
-  return declaration.exported && ts.isVariableStatement(declaration.node) && (declaration.node.declarationList.flags & ts.NodeFlags.Const) !== 0;
+  return declaration.exported && ts3.isVariableStatement(declaration.node) && (declaration.node.declarationList.flags & ts3.NodeFlags.Const) !== 0;
 }
 function isExported(node) {
-  return !!ts.getCombinedModifierFlags(node) && !!(ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Export);
+  return !!ts3.getCombinedModifierFlags(node) && !!(ts3.getCombinedModifierFlags(node) & ts3.ModifierFlags.Export);
 }
 function isFunctionLikeInitializer(node) {
-  return !!node && (ts.isArrowFunction(node) || ts.isFunctionExpression(node));
+  return !!node && (ts3.isArrowFunction(node) || ts3.isFunctionExpression(node));
 }
 function getBodyFingerprint(sourceFile, node) {
   if (!node)
@@ -757,7 +1192,7 @@ async function isDirectory(absolutePath) {
   }
 }
 function getScriptKind(file) {
-  return file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+  return file.endsWith(".tsx") ? ts3.ScriptKind.TSX : ts3.ScriptKind.TS;
 }
 function getLine(sourceFile, node) {
   return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
@@ -810,6 +1245,13 @@ class QualityScript extends script("quality", [QualityRunner]) {
     spinner.succeed(`Quality scan completed (${result.scannedFiles} files, ${result.warnings.length} warnings)`);
     Logger.rawLog(format === "json" ? JSON.stringify(result, null, 2) : formatQualityScanResult(result));
   }
+  async ssr(workspace, format = "text") {
+    const spinner = workspace.spinning("Measuring Akan server/client render balance...");
+    const scanned = await this.qualityRunner.scan(workspace);
+    const result = { ...scanned, warnings: scanned.warnings.filter((warning) => warning.scope === "ssr") };
+    spinner.succeed(`SSR scan completed (${result.scannedFiles} files, ${result.warnings.length} warnings)`);
+    Logger.rawLog(format === "json" ? JSON.stringify(result, null, 2) : formatSsrScanResult(result));
+  }
 }
 
 // pkgs/@akanjs/cli/quality/quality.command.ts
@@ -817,15 +1259,18 @@ class QualityCommand extends command("quality", [QualityScript], ({ public: targ
   quality: target({ desc: "Scan apps and libs for Akan code quality warnings" }).arg("action", String, {
     desc: "quality action",
     default: "scan",
-    enum: ["scan"]
+    enum: ["scan", "ssr"]
   }).option("format", String, {
     desc: "output format",
     default: "text",
     enum: ["text", "json"]
   }).with(Workspace).exec(async function(action, format, workspace) {
-    if (action !== "scan")
-      throw new Error(`Unknown quality action: ${action}. Use "scan".`);
-    await this.qualityScript.scan(workspace, format);
+    if (action === "scan")
+      await this.qualityScript.scan(workspace, format);
+    else if (action === "ssr")
+      await this.qualityScript.ssr(workspace, format);
+    else
+      throw new Error(`Unknown quality action: ${action}. Use "scan" or "ssr".`);
   })
 })) {
 }