create-procode 0.0.0-stage → 1.0.0

package/src/scaffold.mjs

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const TEMPLATES_DIR = path.resolve(__dirname, "..", "templates");
+export const BASE_DIR = path.join(TEMPLATES_DIR, "base");
+
+/**
+ * Template naming conventions, applied when a template file lands on disk:
+ *   foo.ts.tmpl      -> foo.ts        (token substitution runs)
+ *   _dotgitignore    -> .gitignore    (leading `_dot` becomes `.`)
+ *   anything else    -> copied byte-for-byte, no substitution
+ */
+export function targetName(name) {
+  let out = name;
+  if (out.startsWith("_dot")) out = "." + out.slice(4);
+  if (out.endsWith(".tmpl")) out = out.slice(0, -5);
+  return out;
+}
+
+const TOKEN_RE = /__([A-Z0-9_]+)__/g;
+
+export function substitute(text, tokens) {
+  return text.replace(TOKEN_RE, (match, key) =>
+    Object.prototype.hasOwnProperty.call(tokens, key) ? String(tokens[key]) : match,
+  );
+}
+
+/** Files that must never be substituted even though they are text. */
+const isTemplated = (name) => name.endsWith(".tmpl");
+
+/**
+ * Recursively copy `from` into `to`, renaming and substituting as it goes.
+ * Returns the list of created project-relative paths.
+ */
+export function copyTree(from, to, tokens, created = [], rootTo = to) {
+  fs.mkdirSync(to, { recursive: true });
+  for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+    const src = path.join(from, entry.name);
+    const dest = path.join(to, targetName(entry.name));
+    if (entry.isDirectory()) {
+      copyTree(src, dest, tokens, created, rootTo);
+    } else {
+      if (isTemplated(entry.name)) {
+        const text = fs.readFileSync(src, "utf8");
+        fs.writeFileSync(dest, substitute(text, tokens), "utf8");
+      } else {
+        fs.copyFileSync(src, dest);
+      }
+      created.push(path.relative(rootTo, dest).split(path.sep).join("/"));
+    }
+  }
+  return created;
+}
+
+/** A directory is usable as a target if it does not exist, or is empty, or
+ *  holds only benign files a user tends to create first. */
+const BENIGN = new Set([".git", ".gitignore", ".idea", ".vscode", "README.md", "LICENSE", ".DS_Store"]);
+
+export function inspectTarget(dir) {
+  if (!fs.existsSync(dir)) return { exists: false, empty: true, conflicts: [] };
+  const stat = fs.statSync(dir);
+  if (!stat.isDirectory()) return { exists: true, empty: false, notADirectory: true, conflicts: [dir] };
+  const entries = fs.readdirSync(dir);
+  const conflicts = entries.filter((e) => !BENIGN.has(e));
+  return { exists: true, empty: conflicts.length === 0, conflicts };
+}
+
+export function writeJson(file, value) {
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + "\n", "utf8");
+}
+
+/** npm forbids uppercase and a few characters in a package name. */
+export function toPackageName(input) {
+  return (
+    input
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9._~-]+/g, "-")
+      .replace(/^[-_.]+|[-_.]+$/g, "")
+      .slice(0, 214) || "procode-app"
+  );
+}
+
+/** `myapp` / `my-app/` / `/my-app` all normalise to `/my-app` (no trailing slash). */
+export function toBasePath(input) {
+  const raw = String(input).trim();
+
+  // Git Bash / MSYS rewrites a leading-slash argument into a Windows path before
+  // node ever sees it, so `--base /myapp` arrives as
+  // `C:/Program Files/Git/myapp`. Silently accepting that produces a Vite base
+  // nobody can serve, and the mistake only shows up as a 404 at dev time.
+  if (/^\/?[A-Za-z]:[\\/]/.test(raw)) {
+    throw new Error(
+      `--base "${raw}" looks like a Windows path, not a URL path.\n` +
+        "  Git Bash rewrites a leading-slash argument into a filesystem path. Either drop the\n" +
+        "  leading slash (--base myapp), or prefix the command with MSYS_NO_PATHCONV=1.",
+    );
+  }
+
+  const trimmed = raw.replace(/^\/+|\/+$/g, "");
+  return "/" + trimmed;
+}

package/templates/base/README.md.tmpl

@@ -0,0 +1,183 @@
+# __APP_NAME__
+
+A ProCode low-code application — React 18 + TypeScript + Vite on `procode-lowcode-core`,
+`procode-lowcode-kendo-widget`, `procode-vs-template` and `procode-vs-theme`.
+
+Scaffolded with `create-procode` v__GENERATOR_VERSION__.
+
+## Quick start
+
+```bash
+npm install
+npm run dev
+```
+
+Then open **http://localhost:5173__BASE_PATH__/sample**
+
+```
+http://localhost:5173__BASE_PATH__/sample
+                    ^^^^^^^^^^^^^^ ^^^^^^
+                    base           slug
+```
+
+The base comes from `vite.config.ts` (and must equal `VITE_HOMEPAGE` in `.env`); the
+slug comes from `src/Module/index.ts`.
+
+## Kendo licence
+
+Without a licence key, Kendo shows a banner and a console warning on every page.
+Put the key in `kendo-ui-license.txt` at the project root (it is gitignored), or set
+the `KENDO_UI_LICENSE` environment variable in CI. Then run `npm install`, or
+`npx kendo-ui-license activate`.
+
+## Before it will load real data
+
+1. Point `VITE_CENTRAL_SERVICE_BASE_URL` in `.env` at your environment.
+2. Copy `.env.local.example` to `.env.local` and put a dev token in
+   `VITE_HARDCODED_TOKEN` — or sign in so the `AuthToken` cookie is set.
+   **`.env.local` is gitignored. Never commit a token to `.env`.**
+3. Follow the `_readme` at the top of `src/Module/Sample/Contacts.json`: add an
+   `apiConfig`, bind `LOAD_SCREEN_DATA`, and swap the `CUS_SAMPLE_*` stand-ins for
+   `DELETE_ASYNC` / `UPDATE_ASYNC` / `FORMSUBMIT_CREATE_ASYNC`.
+
+## Scripts
+
+| Script | What it does |
+|---|---|
+| `npm run dev` | Vite dev server on port 5173 |
+| `npm run build` | `tsc` then `vite build` |
+| `npm run preview` | Serve the built bundle |
+| `npm run lint` | ESLint over `src/` |
+
+## Layout
+
+```
+src/
+├── main.tsx                      the SINGLE integration point — every <Core> prop, typed
+├── constant.ts                   APPLICATION_CODE, AuthToken, WidgetTypes, ValidationTypes, RuleEffectTypes
+├── CustomAction.ts               (4) custom actions, keyed CUS_*
+├── CustomAuthorizationProvider.ts   screen / widget / action gates
+├── localizationResolver.ts       date pattern, currency symbol, … for vs-template widgets
+├── icons.ts                      app SVG icons, registered with registerIcons
+├── routes.ts                     extra routes (customRoute)
+├── Screens/index.tsx             loader, error and 404 screens
+├── Utils/
+│   ├── responseFormatter.ts      reshapes every response body before adapters see it
+│   ├── fieldErrorMapper.ts       422 body -> per-field messages
+│   ├── errorMessages.ts          fallback toast text per verb and status
+│   ├── storages.ts               extra STORAGE:: stores (MEMORY)
+│   └── logger.ts                 one log sink for the core and the widget library
+├── Module/
+│   ├── index.ts                  (1) slug -> schema
+│   └── Sample/Contacts.json          the sample screen — grid, bulk actions, editor, dialogs, rules
+├── AdapterProvider/
+│   ├── AdapterFactory.ts         (2) screenId -> adapter
+│   └── SampleContacts.ts             a pure translator, no HTTP; seeds the sample rows
+├── Factory/
+│   ├── CustomWidgetFactory.tsx   (3) custom widgets, keyed by WidgetTypes
+│   ├── CustomValidationFactory.tsx (5) custom validations, keyed by ValidationTypes
+│   ├── CustomRuleEffectFactory.ts    custom rule effects, keyed by RuleEffectTypes
+│   ├── RuleEffects/readOnlyEffect.ts CUS_READONLY — read-only while a condition holds
+│   ├── Widgets/MyWidget/             a presentation-only widget, composed from library widgets
+│   ├── Widgets/Notification/         the app's one toast host
+│   ├── Actions/setField.ts           CUS_SET_FIELD — lets a button reach MODIFY_MODEL
+│   ├── Actions/myAction.ts           the custom widget's two actions
+│   ├── Actions/sampleContacts.ts     the sample's stand-ins for the API-backed standard actions
+│   └── Validations/myValidation.ts
+└── assets/styles/index.scss      the SCSS cascade — import order matters
+public/                           copied verbatim to the build, served from the base path
+.env / .env.local.example         every variable the core reads, documented
+.eslintrc.cjs                     the framework's import boundary, enforced at lint time
+.vscode/extensions.json           recommends the ESLint extension
+```
+
+Reference files in `public/` root-relative — `/favicon.svg`, not
+`__BASE_PATH_SLASH__favicon.svg`. Vite prepends `base` itself, so writing it
+yourself doubles it.
+
+## The sample screen
+
+It demonstrates all five extension points at once, and its four coordinates must agree:
+
+| Coordinate | Value | File |
+|---|---|---|
+| slug | `sample` | `src/Module/index.ts` |
+| schema | — | `src/Module/Sample/Contacts.json` |
+| screenId | `sample-contacts` | inside that JSON |
+| adapter | `SampleContacts` | `src/AdapterProvider/AdapterFactory.ts` |
+
+One JSON document, no backend, and everything on the page is declared in it:
+
+- a heading, a subtitle and an **Add contact** button gated by a permission key;
+- three `BLOCK` summary tiles that stay live;
+- a `GRID` with sorting, column search, checkbox selection and three bulk actions
+  (Deactivate / Activate / Delete) that open the confirmation dialog with the
+  selection count in the text — sorting and searching go through the grid's
+  `onScreenDataLoad` event exactly as they would against a server;
+- a click on a name that opens the inline editor for that row;
+- an editor with `TEXTBOX`, `DROPDOWN`, `DATE`, `SWITCH`, `TEXTAREA` and the custom
+  `MY_WIDGET`, standard validators, and a *Sales region* field that a rule shows only
+  for the Sales department;
+- a custom rule effect, `CUS_READONLY`, that makes *Notes* read-only while the
+  contact is inactive;
+- a **Save** that validates with the framework's validators, adds or updates the row
+  in the grid and opens the information dialog.
+
+The rows are seeded by the adapter. The `CUS_SAMPLE_*` actions stand in for the
+API-backed standard actions and say so in their headers; the schema's `_readme`
+lists the three swaps that take the screen live.
+
+## The one rule worth knowing up front
+
+**All application data access is `apiConfig` plus a standard action bound to a schema
+event.** An `import axios` or a bare `fetch(` anywhere under `src/` outside `main.tsx`
+silently forfeits the loading counter and skeletons, status-code toasts, 422 →
+field-error routing, action chainability, a schema-visible endpoint, and
+per-environment retargeting without a code change.
+
+A widget renders; it does not fetch.
+
+## The second rule: custom code is still made of library parts
+
+A custom widget renders the library's `TextBox` / `Dropdown` / `Button` from
+`procode-lowcode-kendo-widget/widgets` — never `import { … } from "@progress/kendo-react-*"`
+and never a raw `<input>`. Icons go through `loadIcon` / `registerIcons`; navigation is
+`NAVIGATE` / `MENUNAVIGATE`; a toast is `responseConfig` or the Notification host; the
+store is `props.viewModel`. `react-redux`, `react-router-dom`, `react-toastify` and
+`procode-*/src/…` deep paths are library internals. `npm run lint` refuses code that
+breaks this; the one exception — a control the library genuinely does not wrap — is
+marked with a `// procode-escalation: …` comment so it can be found with `grep`.
+
+## Localization
+
+vs-template widgets ask the app for per-user values — date pattern, date
+placeholder, currency symbol and decimals — through `src/localizationResolver.ts`,
+which `main.tsx` registers with `registerLocalization()` before render. It returns
+`undefined` for every key out of the box, so each widget uses its own default. Answer
+a key there (from a token claim, a cached settings payload, or a constant) and every
+widget that asks for it picks the value up on its next render.
+
+## Versions
+
+The newest ProCode releases when this app was scaffolded, with the React, Kendo,
+router and axios ranges those releases declare as peers:
+
+| Package | Version |
+|---|---|
+__PROCODE_VERSIONS__
+
+Node 24, React __REACT_RANGE__. **Keep React on the major the ProCode libraries declare as
+a peer** — a newer major installs cleanly, then fails at runtime.
+
+To move to newer ProCode releases later, upgrade the four together, then check for
+peer warnings:
+
+```bash
+npm install procode-lowcode-core@latest procode-lowcode-kendo-widget@latest procode-vs-template@latest procode-vs-theme@latest
+npm ls --depth=0
+```
+
+**Do not add `react-redux`** to `package.json`. It is bundled inside
+`procode-lowcode-core` (on 8.x); a second copy gives two Provider contexts and every
+screen renders blank with nothing in the console. The `_procodeBundled` block in
+`package.json` lists every package bundled this way.

package/templates/base/_dotenv.local.example.tmpl

@@ -0,0 +1,8 @@
+# Copy to .env.local (gitignored) and fill in.
+#
+# AuthToken = VITE_HARDCODED_TOKEN ?? the AuthToken cookie. Without one of the
+# two, every request 401s and every screen is empty.
+VITE_HARDCODED_TOKEN=""
+
+# Point at a local API without touching the committed .env:
+# VITE_CENTRAL_SERVICE_BASE_URL="https://localhost:7016/lowcodev2/api/__APP_CODE__/"

package/templates/base/_dotenv.tmpl

@@ -0,0 +1,41 @@
+# ---------------------------------------------------------------------------
+# __APP_NAME__ — committed defaults.
+#
+# procode-lowcode-core reads every one of these directly. A missing value does
+# NOT throw: it produces a wrong URL or an empty screen, so treat a blank here
+# as a bug rather than a default.
+#
+# Machine-specific values and ANY token belong in .env.local (gitignored).
+# ---------------------------------------------------------------------------
+
+# Where application data comes from. The <APP_CODE> segment is part of the path.
+VITE_CENTRAL_SERVICE_BASE_URL="__API_BASE_URL__"
+
+# Must equal the code main.tsx builds the adapter global from. The core resolves
+# that global by name as "getAdapter" + VITE_APPLICATION_CODE — if the two
+# diverge, EVERY adapter silently falls back to a dummy and no screen has data.
+VITE_APPLICATION_CODE="__APP_CODE__"
+
+# Must match `base` in vite.config.ts.
+VITE_HOMEPAGE="__BASE_PATH__"
+
+# InDraft | Published
+VITE_PROJECT_ENVIROMENT="__PROJECT_ENV__"
+
+# The low-code tool that stores and serves schemas.
+VITE_TOOL_BASE_URL="__TOOL_BASE_URL__"
+VITE_TOOL_SCHEMA_FETCH="https://lowcodeapi-399313.uc.r.appspot.com/api/screenRetriever/getScreenBySlug"
+
+# Auth
+VITE_AUTH_URL="__AUTH_URL__"
+# VITE_BASE_LOGOUT_URL=""
+
+# Slugs for the shared header and footer schemas.
+VITE_HEADER_SLUG="header"
+VITE_FOOTER_SLUG="footer"
+
+# How long a notification stays up, in ms.
+# VITE_NOTIFICATION_VISIBLE_DURATION="3000"
+
+# A personal dev token belongs in .env.local, NOT here:
+# VITE_HARDCODED_TOKEN="eyJhbGciOi..."

package/templates/base/_doteslintrc.cjs.tmpl

@@ -0,0 +1,125 @@
+// ---------------------------------------------------------------------------
+// The `no-restricted-imports` block below enforces the framework's import
+// boundary: custom code is built from library parts, never from the packages
+// those parts wrap.
+//
+// Every entry has one legitimate exception: a control the library genuinely
+// does not wrap. Disable the line with the escalation marker in the
+// description, naming the module and the limitation:
+//
+//   // eslint-disable-next-line no-restricted-imports -- procode-escalation: @progress/kendo-react-layout — L4 cannot compose this because the catalog has no stepper widget.
+//   import { Stepper } from "@progress/kendo-react-layout";
+//
+// `grep -rn "procode-escalation:" src` then lists every exception in the app.
+// ---------------------------------------------------------------------------
+
+const KENDO = {
+  group: ["@progress/kendo-react-*", "@progress/kendo-svg-icons"],
+  message:
+    "Library boundary: render the library's widget from procode-lowcode-kendo-widget/widgets, or loadIcon()/registerIcons for a glyph. A control the catalog does not wrap: `-- procode-escalation: <module> — L4 cannot compose this because <limitation>`.",
+};
+
+const ICON_SETS = {
+  group: ["@fortawesome/*", "react-icons", "react-icons/*", "lucide-react", "@heroicons/*", "@tabler/icons*"],
+  message:
+    "A second icon set is parallel infrastructure. Use the ICON widget, loadIcon(\"name\"), or registerIcons({ name: svg }) once for a glyph Kendo lacks.",
+};
+
+const LIBRARY_INTERNALS = {
+  group: ["react-redux", "react-router-dom"],
+  message:
+    "Library internals, not app imports. A widget reads props.viewModel; an action uses props.navigate / props.eventService; navigation is NAVIGATE / NAVIGATE_BACK / MENUNAVIGATE.",
+};
+
+const TOAST = {
+  group: ["react-toastify"],
+  message:
+    "One toast host: use responseConfig on the verb block, or the helper in src/Factory/Widgets/Notification/notifiFunc.ts.",
+};
+
+const HTTP = {
+  group: ["axios"],
+  message:
+    "All data access is apiConfig + a standard action bound to a schema event. Only src/main.tsx imports axios.",
+};
+
+const DEEP_PATHS = {
+  group: [
+    "procode-lowcode-core/src/*",
+    "procode-lowcode-core/dist/*",
+    "procode-lowcode-kendo-widget/src/*",
+    "procode-lowcode-kendo-widget/dist/*",
+    "procode-vs-template/src/*",
+    "procode-vs-template/dist/*",
+    "procode-vs-theme/src/*",
+    "procode-vs-theme/dist/*",
+  ],
+  message:
+    "Deep import into a package internal. Import only the declared exports subpaths.",
+};
+
+const OTHER_TOOLKITS = {
+  group: ["@mui/*", "antd", "antd/*", "react-bootstrap", "@chakra-ui/*", "primereact/*", "styled-components", "@emotion/*", "@radix-ui/*", "@headlessui/*"],
+  message:
+    "A second UI toolkit or styling system is parallel infrastructure. Widgets come from procode-lowcode-kendo-widget; styling from procode-vs-theme utilities and widgetStyle.",
+};
+
+const ALL = [KENDO, ICON_SETS, LIBRARY_INTERNALS, TOAST, HTTP, DEEP_PATHS, OTHER_TOOLKITS];
+const without = (...skip) => ALL.filter((rule) => !skip.includes(rule));
+
+const WINDOW_LOCATION = [
+  "error",
+  {
+    object: "window",
+    property: "location",
+    message:
+      "Navigation is NAVIGATE / NAVIGATE_BACK, MENUNAVIGATE EXTERNAL to leave the SPA, or props.navigate in an action; a query/route param is a QUERYPARAMS / ROUTEPARAMS policy.",
+  },
+];
+
+module.exports = {
+  root: true,
+  env: { browser: true, es2020: true },
+  extends: [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:react-hooks/recommended",
+  ],
+  ignorePatterns: ["dist", ".eslintrc.cjs"],
+  parser: "@typescript-eslint/parser",
+  plugins: ["react-refresh"],
+  rules: {
+    "react-refresh/only-export-components": [
+      "warn",
+      { allowConstantExport: true },
+    ],
+    // Widget, action and adapter props cross a schema boundary that TypeScript
+    // cannot see, so `any` is the honest type at those seams.
+    "@typescript-eslint/no-explicit-any": "off",
+    // The framework fixes several signatures — getSchemaBySlugService(slug, appCode),
+    // a validator's (value, props, viewModel), an adapter hook's (props) — so an
+    // implementation that needs only the first argument still has to declare the
+    // rest. A leading underscore marks them as deliberately unused.
+    "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_", varsIgnorePattern: "^_" }],
+    "no-restricted-imports": ["error", { patterns: ALL }],
+    "no-restricted-properties": WINDOW_LOCATION,
+  },
+  overrides: [
+    {
+      // The single integration point: the one `import axios` (validateStatus)
+      // and the one place the Kendo/router/redux packages may be touched.
+      files: ["src/main.tsx"],
+      rules: {
+        "no-restricted-imports": ["error", { patterns: without(HTTP, LIBRARY_INTERNALS) }],
+        "no-restricted-properties": "off",
+      },
+    },
+    {
+      // The app's ONE toast host.
+      files: ["src/Factory/Widgets/Notification/**"],
+      rules: {
+        "no-restricted-imports": ["error", { patterns: without(TOAST) }],
+      },
+    },
+  ],
+};

package/templates/base/_dotgitignore.tmpl

@@ -0,0 +1,32 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Local env — this is where a personal dev token belongs. Never .env.
+.env.local
+.env.*.local
+
+# Kendo UI licence key. @progress/kendo-licensing activates it on npm install
+# from this file or the KENDO_UI_LICENSE environment variable.
+kendo-ui-license.txt
+kendo-ui-license.js
+
+# Editor
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

package/templates/base/_dotnvmrc.tmpl

@@ -0,0 +1 @@
+24

package/templates/base/_dotvscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["dbaeumer.vscode-eslint"]
+}

package/templates/base/index.html.tmpl

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <!-- Root-relative: Vite prepends `base` at build time, so public/favicon.svg
+         is served at __BASE_PATH_SLASH__favicon.svg. Writing the base here
+         yourself would double it. -->
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <!-- Overwritten at runtime: procode-lowcode-core's Screen sets
+         document.title from the rendered schema's screenName. -->
+    <title>__APP_NAME__</title>
+  </head>
+  <body>
+    <div id="root" style="height: 100dvh"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/base/package.json.tmpl

@@ -0,0 +1,15 @@
+{
+  "name": "__PKG_NAME__",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "homepage": "__BASE_PATH_SLASH__",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}

package/templates/base/public/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="7" fill="#1261e8"/>
+  <path d="M11 24V8h6.2c3.6 0 5.8 2 5.8 5.1s-2.2 5.1-5.8 5.1H14.4V24z M14.4 15.3h2.6c1.7 0 2.6-.8 2.6-2.2s-.9-2.2-2.6-2.2h-2.6z" fill="#fff"/>
+</svg>

package/templates/base/src/AdapterProvider/AdapterFactory.ts.tmpl

@@ -0,0 +1,21 @@
+import { SampleContacts } from "./SampleContacts";
+
+/**
+ * Extension point 2 of 5: screenId -> adapter.
+ *
+ * Keyed by the `screenId` INSIDE the schema JSON — NOT by the slug. Read the id
+ * out of the file; never guess it.
+ *
+ * main.tsx registers this function onto window as `getAdapter__APP_CODE__`, and
+ * the core resolves that global by name from VITE_APPLICATION_CODE. If the two
+ * ever diverge, EVERY adapter here silently falls back to a dummy and no screen
+ * has data — on every screen at once, with nothing in the console.
+ */
+export const getAdapter = (screenId: string): any => {
+  switch (screenId) {
+    case "sample-contacts":
+      return new SampleContacts();
+    default:
+      return null;
+  }
+};