@khester/create-dynamics-app 2.10.0 → 3.1.0

package/templates/pcf-dataset/{{{componentName}}Component.tsx → {{componentName}}/{{componentName}}Component.tsx}

@@ -1,24 +1,18 @@
 import * as React from 'react';
-import { initializeIcons } from '@fluentui/react/lib/Icons';
-import { ReadOnlyGrid, createCellRegistry } from '@dataverse-kit/grid-kit';
-import type { ColumnDef, GridSortState } from '@dataverse-kit/grid-kit';
-
-// Initialize Fluent UI icons — the grid toolbar / column-chooser / filter use them.
-initializeIcons();
+import type { ColumnDef } from '@dataverse-kit/grid-kit';
+import { {{componentName}}App, type Row } from './{{componentName}}App';
 
 export interface I{{componentName}}ComponentProps {
     dataset: ComponentFramework.PropertyTypes.DataSet;
 }
 
-interface Row extends Record<string, unknown> {
-    key: string;
-}
-
+/**
+ * THIN PCF ADAPTER — maps the bound dataset onto the host-agnostic `<{{componentName}}App>`.
+ *
+ * All grid behaviour (search, sort, toolbar, column chooser) lives in the App so the dev
+ * harness renders the exact same component. Keep this file to dataset→props mapping only.
+ */
 export const {{componentName}}Component: React.FC<I{{componentName}}ComponentProps> = ({ dataset }) => {
-    const registry = React.useMemo(() => createCellRegistry(), []);
-    const [search, setSearch] = React.useState('');
-    const [sort, setSort] = React.useState<GridSortState | undefined>(undefined);
-
     // Map the bound dataset's columns → grid-kit ColumnDef[]. Every column renders as
     // `text` (the formatted Dataverse value), so client sort/filter is lexical on the
     // displayed string. For type-aware cells + correct numeric/date ordering, map each
@@ -54,36 +48,5 @@ export const {{componentName}}Component: React.FC<I{{componentName}}ComponentPro
         return row;
     });
 
-    // grid-kit's toolbar `onSearch` only reports the term — the host owns filtering.
-    // Substring-match across every column's formatted value.
-    const q = search.trim().toLowerCase();
-    const filtered = q
-        ? items.filter((row) =>
-              columns.some((c) => String(row[c.fieldName] ?? '').toLowerCase().includes(q)),
-          )
-        : items;
-
-    // grid-kit sort is controlled — `onSortChange` reports the header click; the host
-    // reorders nothing. Sort the (filtered) rows by the formatted string.
-    const sorted = sort
-        ? [...filtered].sort(
-              (a, b) =>
-                  String(a[sort.fieldName] ?? '').localeCompare(String(b[sort.fieldName] ?? '')) *
-                  (sort.direction === 'desc' ? -1 : 1),
-          )
-        : filtered;
-
-    return (
-        <ReadOnlyGrid<Row>
-            items={sorted}
-            columns={columns}
-            registry={registry}
-            getKey={(r) => r.key}
-            sort={sort}
-            onSortChange={(fieldName, direction) => setSort({ fieldName, direction })}
-            columnChooser
-            filterBuilder
-            toolbar={{ showSearch: true, searchPlaceholder: 'Search', onSearch: setSearch }}
-        />
-    );
+    return <{{componentName}}App items={items} columns={columns} />;
 };

package/templates/pcf-field/eslintrc.json

@@ -0,0 +1,11 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2021,
+    "sourceType": "module",
+    "ecmaFeatures": { "jsx": true }
+  },
+  "env": { "browser": true, "es2021": true },
+  "ignorePatterns": ["out/**", "node_modules/**", "**/generated/**"]
+}

package/templates/pcf-field/package.json

@@ -20,6 +20,7 @@
     "@types/node": "^18.16.9",
     "@types/react": "^16.14.34",
     "@types/react-dom": "^16.9.17",
+    "@typescript-eslint/parser": "^6.21.0",
     "eslint-plugin-react-hooks": "^4.6.0",
     "pcf-scripts": "^1",
     "pcf-start": "^1",

package/templates/pcf-field/pcfconfig.json

@@ -0,0 +1,3 @@
+{
+  "outDir": "./out/controls"
+}

package/templates/pcf-field/{{componentName}}/ControlManifest.Input.xml

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<manifest>
+  <control namespace="{{namespace}}" constructor="{{componentName}}" version="1.0.0" display-name-key="{{namespace}}_{{componentName}}" description-key="{{namespace}}_{{componentName}}_Desc" control-type="standard">
+    <property name="value" display-name-key="Value" description-key="Value_Desc" of-type="{{propertyType}}" usage="bound" required="true" />
+    <property name="placeholder" display-name-key="Placeholder" description-key="Placeholder_Desc" of-type="SingleLine.Text" usage="input" required="false" />
+    <property name="disabled" display-name-key="Disabled" description-key="Disabled_Desc" of-type="TwoOptions" usage="input" required="false" default-value="false" />
+    <resources>
+      <code path="index.ts" order="1"/>
+      <!--
+        ★ DELIBERATELY NO <platform-library> HERE. This is a control-type="standard" control.
+
+        Microsoft scopes <platform-library> to "React controls & platform libraries", and
+        defines that feature as control-type="virtual" PLUS the platform-library children —
+        one feature, not two. Declaring them on a standard control is a half-state that
+        builds green and dies at runtime:
+
+          - With pcfReactPlatformLibraries at its shipped default ("off"),
+            platformLibrariesHandler externalises `react` but NOT `react-dom`. So the bundle
+            ships ReactDOM 16.14 wired to a platform React the model-driven host actually
+            loads as 17.0.2 — a cross-major ReactSharedInternals/event-system mismatch.
+          - Turning the flag ON instead externalises react-dom to the `ReactDOMv16` global,
+            which the platform only contracts to supply for VIRTUAL controls. Strictly worse.
+
+        So: bundle our own React 16.14 + Fluent 8. Nothing is externalised, therefore
+        installed == compiled == runtime and no version skew is possible. The bundle grows
+        (~1-1.5 MB minified); the 5 MB cap is enforced in production mode only.
+
+        If this control is ever converted to control-type="virtual", the versions declared
+        must EQUAL a served platform version, not merely fall inside pcf-scripts' matched
+        range — an in-range-but-unequal version builds green and cannot be resolved at
+        runtime ("Error loading control" in every host). Live-diagnosed 2026-07-26 on
+        host-swap: React 18.2.0 + Fluent 8.115.6, 15/15 build gates green, loaded nowhere.
+        Supported then: React 16.14.0 | 18.3.1; @fluentui/react 8.29.0 | 8.121.1;
+        @fluentui/react-components >=9.4.0 <=9.46.2. See src/__tests__/registry.test.ts.
+      -->
+      <resx path="strings/{{componentName}}.1033.resx" version="1.0.0" />
+    </resources>
+    <feature-usage>
+      <uses-feature name="Utility" required="true" />
+    </feature-usage>
+  </control>
+</manifest>

package/templates/power-pages-island/README.md

@@ -0,0 +1,93 @@
+# {{projectName}} — Power Pages island
+
+A React **island** you mount into an **existing traditional (Liquid) Power Pages portal** — React
+hydrates only the nodes you tag in Liquid, leaving the rest of the server-rendered page untouched.
+
+This is the delta Microsoft's Power Pages tooling doesn't cover: the `pac`/plugin **code-site**
+scaffolder builds a whole-page React SPA that *is* the site. It cannot drop a React widget into an
+existing Liquid portal. This template does exactly that.
+
+## Data access — host-portable seam
+
+The widget (`src/Component.tsx`) is written against an injected **`IApiService`** (the create-app
+6-method `dataverse-seam`). In the browser it's given **`PortalSeamService`** from
+[`@dataverse-kit/portal-api-service`](https://www.npmjs.com/package/@dataverse-kit/portal-api-service),
+which talks to the portal Web API (`/_api/`) and handles the anti-forgery token
+(`__RequestVerificationToken`), 403-retry, and idempotency-aware retry for you. On `localhost` it
+falls back to an in-memory `MockApiService`, so it renders with no portal.
+
+Because the widget depends only on the seam, **the same `src/Component.tsx` runs unchanged** as a PCF
+control, a Dynamics custom page, or a web resource (`create-dynamics-app … --artifact host-swap`) — the
+only thing that changes is the host wrapper and the injected service.
+
+| Path | Role |
+|------|------|
+| `src/islands.tsx` | Entry — mounts React into every `[data-dvkit-island]` node (idempotent) |
+| `src/App.tsx` | Picks `MockApiService` (localhost) or `PortalSeamService` (portal); injects it |
+| `src/Component.tsx` | The host-agnostic widget (an accounts `DetailsList`), depends only on `IApiService` |
+| `src/core/services/*` | The data-access seam — `IApiService` + `Xrm`/`Fetch`/`ServiceFactory` injected from `_shared`; `MockApiService` seed is per-project |
+| `src/core/services/portalSeam.assert.ts` | Compile-time drift guard: `PortalSeamService` stays assignable to the seam |
+
+## Build & preview
+
+```bash
+npm install
+npm run dev      # webpack dev server on http://localhost:8080 (renders the island from the mock)
+npm run build    # tsc --noEmit + webpack --mode production → dist/{{projectName}}.js
+```
+
+## Deploy to a traditional portal
+
+1. **Build** → `dist/{{projectName}}.js` (a single, stable-named bundle — no content hash, so the URL
+   is fixed).
+2. **Upload it as a portal Web File** (Power Pages Management app → *Web Files*, or `pac`): set its
+   **Parent Page = Home**, give it a partial URL like `{{projectName}}.js`, set the MIME type to
+   `text/javascript`, and set **Publishing State = Published**. A web file's URL is its parent page's
+   path joined with the partial URL, so parenting to **Home** makes it resolve at the site root:
+   `https://<your-portal>/{{projectName}}.js`. (Parent it elsewhere — e.g. under `/documents` — and the
+   URL becomes `/documents/{{projectName}}.js`, so the root-relative `<script src>` in step 3 won't find
+   it. Either parent to Home, or match the `<script src>` path to the web file's actual URL.)
+3. **Place the island** on any existing page — paste this into a **Web Template** or **Content Snippet**
+   the page renders:
+
+   ```html
+   <div data-dvkit-island="accounts"></div>
+   <script src="/{{projectName}}.js"></script>
+   ```
+
+   Add more `<div data-dvkit-island="…">` nodes to mount the widget in several places; the
+   `data-dvkit-island` value is a hook for routing multiple widgets later.
+
+## Portal requirements (per table you read/write)
+
+The portal Web API is gated per table. For `account` (the sample), configure **Site Settings**:
+
+- `Webapi/account/enabled` = `true`
+- `Webapi/account/fields` = the exact columns you read/write (e.g. `name,telephone1` — list the
+  `_<lookup>_value` read form too), **mandatory**
+- a **Table Permission** for the signed-in user's Web Role (and, for a `@odata.bind`/associate write,
+  **both Append AND AppendTo on both** the source and target permissions)
+
+Notes:
+- **Fluent UI v8** — Fluent v9 is broken on Power Pages portals. This template pins v8.
+- **React 18** — pinned (Fluent v8 peers `<19`).
+- Portals expose **no metadata endpoints** — hard-code any option-set labels at dev time.
+
+## Verification status
+
+This starter is **build-verified** (`tsc` + webpack bundle) and **localhost-mock-verified**
+(`npm run dev`). Live behavior against a real traditional portal (the web-file upload, the Liquid
+snippet, and `PortalSeamService` against live `/_api/`) is the deploy step above — verify it on your
+own portal.
+
+> **The artifact is live-verified (2026-07-26).** This template was deployed to a real traditional
+> (Liquid) Power Pages portal on the **enhanced data model** (`mspp_*` / `powerpagecomponent`): the
+> bundle mounted into a Liquid-placed `[data-dvkit-island]` node and `PortalSeamService` returned
+> **200** from `GET /_api/accounts?fetchXml=…` (the FetchXML read path the MS code-site scaffolder
+> generates none of), rendering live accounts in the DetailsList.
+>
+> **Deploy tip for enhanced-data-model portals:** after uploading the web file + placing the snippet,
+> run **⟳ Purge Cache** (Power Platform admin center → *Resources → Power Pages sites*) — traditional
+> portals serve a precompiled snapshot, so a freshly-added web file **404s** until the cache is purged.
+> The site is private until the signed-in user is a portal contact (first Entra sign-in auto-registers
+> one + attaches the Authenticated Users role).

package/templates/power-pages-island/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "{{projectName}}",
+  "version": "1.0.0",
+  "private": true,
+  "description": "{{projectName}} — React island mounted into an existing traditional Power Pages (Liquid) portal (webpack)",
+  "scripts": {
+    "dev": "webpack serve --mode development",
+    "build": "tsc --noEmit && webpack --mode production",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@dataverse-kit/portal-api-service": "^0.2.0",
+    "@fluentui/react": "^8.120.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "html-webpack-plugin": "^5.5.3",
+    "ts-loader": "^9.5.1",
+    "typescript": "^5.3.3",
+    "webpack": "^5.89.0",
+    "webpack-cli": "^5.1.4",
+    "webpack-dev-server": "^4.15.1"
+  }
+}

package/templates/power-pages-island/public/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{projectName}} — Power Pages island (dev preview)</title>
+  </head>
+  <body>
+    <!-- On a real portal this node lives in a Liquid web template / content snippet.
+         The bundle mounts React into EVERY [data-dvkit-island] node on the page. -->
+    <div data-dvkit-island="accounts"></div>
+  </body>
+</html>

package/templates/power-pages-island/src/App.tsx

@@ -0,0 +1,37 @@
+import * as React from "react";
+import type { IApiService } from "./core/services/IApiService";
+import { MockApiService } from "./core/services/MockApiService";
+import { PortalSeamService } from "@dataverse-kit/portal-api-service";
+import { Component } from "./Component";
+import { useHostWidth } from "./useHostWidth";
+
+// A Power Pages island is served from the portal origin, so a same-origin `/_api`
+// fetch is authenticated by the portal session cookie + anti-forgery token —
+// PortalSeamService handles both (token fetch/cache, 403-retry, idempotency-aware
+// retry). On localhost (the webpack dev server) fall back to the in-memory mock so
+// it renders with no portal.
+//
+// PortalSeamService implements the create-app 6-method `dataverse-seam`, so it is
+// structurally assignable to IApiService with NO cast — and THIS assignment is the
+// load-bearing compile-time drift guard: if the seam shapes ever diverge, this line
+// fails `tsc`. (See core/services/portalSeam.assert.ts for the explicit fixture.)
+export const App: React.FC<{ island?: string }> = () => {
+  // `island` is the `data-dvkit-island` value — a hook for routing multiple widgets
+  // on a page. The starter renders the accounts widget for any island.
+  const api = React.useMemo<IApiService>(() => {
+    const onLocalhost = /^(localhost|127\.0\.0\.1)$/.test(window.location.hostname);
+    return onLocalhost ? new MockApiService() : new PortalSeamService();
+  }, []);
+
+  // An island is mounted into a slot on a portal page, NOT a full-page iframe, so the
+  // viewport is the whole portal and would overstate the space available. Measure the
+  // island's own box instead — portals are heavily mobile, so this matters here most.
+  const hostRef = React.useRef<HTMLDivElement>(null);
+  const width = useHostWidth(hostRef);
+
+  return (
+    <div ref={hostRef}>
+      <Component api={api} width={width} />
+    </div>
+  );
+};

package/templates/power-pages-island/src/Component.tsx

@@ -0,0 +1,136 @@
+import * as React from "react";
+import {
+  DetailsList,
+  SelectionMode,
+  MessageBar,
+  MessageBarType,
+  Spinner,
+  Stack,
+  Text,
+  type IColumn,
+} from "@fluentui/react";
+import { initializeIcons } from "@fluentui/react/lib/Icons";
+import type { IApiService } from "./core/services/IApiService";
+
+// Initialize Fluent UI icons once (DetailsList sort/column glyphs).
+initializeIcons();
+
+/**
+ * The ONE host-agnostic component. It depends on nothing but an injected
+ * `IApiService` and a plain number for its width — no PCF `context`, no Xrm, no
+ * lifecycle, no bundler globals — so the SAME source renders unchanged inside a
+ * PCF control, a web resource, and a model-driven custom page. Each host's thin
+ * wrapper builds the right `IApiService` and supplies the width.
+ */
+export interface ComponentProps {
+  api: IApiService;
+  /**
+   * Width available to the control, in px. Hosts that can measure it should pass it
+   * (the PCF wrapper passes `context.mode.allocatedWidth`); when omitted the layout
+   * falls back to the roomy variant.
+   *
+   * ★ Deliberately a NUMBER, not a form factor. Do NOT branch on
+   * `context.client.getFormFactor()` / `getClient()`: verified live 2026-07-25 on a
+   * physical iPhone in the native Power Apps app, a custom page reports
+   * client "Web" and formFactor 1 (Desktop). Branching on those silently gives every
+   * phone the desktop layout, and passes every test not run on a real device.
+   */
+  width?: number;
+}
+
+/**
+ * Below this the Fluent `DetailsList` stops being usable — columns collapse and
+ * horizontal scrolling takes over — so narrow hosts get a stacked card list instead.
+ */
+const NARROW_BREAKPOINT_PX = 480;
+
+const ACCOUNTS_FETCHXML = [
+  '<fetch top="25">',
+  '  <entity name="account">',
+  '    <attribute name="accountid" />',
+  '    <attribute name="name" />',
+  '    <attribute name="telephone1" />',
+  '    <order attribute="name" />',
+  "  </entity>",
+  "</fetch>",
+].join("\n");
+
+interface AccountRow {
+  accountid: string;
+  name?: string;
+  telephone1?: string;
+}
+
+const COLUMNS: IColumn[] = [
+  { key: "name", name: "Account", fieldName: "name", minWidth: 180, maxWidth: 320, isResizable: true },
+  { key: "telephone1", name: "Phone", fieldName: "telephone1", minWidth: 140, isResizable: true },
+];
+
+export const Component: React.FC<ComponentProps> = ({ api, width }) => {
+  const [rows, setRows] = React.useState<AccountRow[] | null>(null);
+  const [error, setError] = React.useState<string | null>(null);
+
+  // `width === undefined` means the host cannot measure itself; prefer the roomy
+  // layout rather than guessing narrow.
+  const isNarrow = width !== undefined && width < NARROW_BREAKPOINT_PX;
+
+  React.useEffect(() => {
+    let cancelled = false;
+    api
+      .retrieveMultipleRecords("accounts", ACCOUNTS_FETCHXML)
+      .then((res) => {
+        if (!cancelled) setRows(res.entities as AccountRow[]);
+      })
+      .catch((e) => {
+        if (!cancelled) setError(e instanceof Error ? e.message : String(e));
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [api]);
+
+  return (
+    <Stack tokens={{ childrenGap: 12 }} styles={{ root: { padding: 16 } }}>
+      <Text variant="xLarge">Accounts</Text>
+      <Text variant="small">
+        One host-agnostic component — the same source renders in a PCF control, a web
+        resource and a model-driven custom page; only the thin host wrapper changes.
+        {width !== undefined && ` (${isNarrow ? "narrow" : "wide"} layout · ${width}px)`}
+      </Text>
+      {error && <MessageBar messageBarType={MessageBarType.error}>{error}</MessageBar>}
+      {!rows && !error && <Spinner label="Loading accounts…" />}
+      {rows && !isNarrow && (
+        <DetailsList
+          items={rows}
+          columns={COLUMNS}
+          setKey="accounts"
+          getKey={(item: AccountRow) => item.accountid}
+          selectionMode={SelectionMode.none}
+        />
+      )}
+      {rows && isNarrow && (
+        <Stack tokens={{ childrenGap: 8 }}>
+          {rows.map((row) => (
+            <Stack
+              key={row.accountid}
+              tokens={{ childrenGap: 2 }}
+              styles={{
+                root: {
+                  padding: 12,
+                  border: "1px solid #edebe9",
+                  borderRadius: 4,
+                  // Long account names must wrap rather than force the card wider
+                  // than the phone — the failure mode DetailsList has here.
+                  wordBreak: "break-word",
+                },
+              }}
+            >
+              <Text variant="mediumPlus">{row.name ?? "(no name)"}</Text>
+              <Text variant="small">{row.telephone1 ?? "—"}</Text>
+            </Stack>
+          ))}
+        </Stack>
+      )}
+    </Stack>
+  );
+};

package/templates/power-pages-island/src/core/services/MockApiService.ts

@@ -0,0 +1,58 @@
+import { IApiService } from "./IApiService";
+import { logCrud } from "./crudLogging";
+
+// A few seeded in-memory accounts so the control/page renders with no org or
+// token (the PCF test harness and `npm run dev` both land here). Replace this
+// seed as your component grows. The other IApiService impls (Xrm/Fetch) and the
+// shared contract are pulled from templates/_shared/dataverse-seam at scaffold.
+const SEED_ACCOUNTS = [
+  { accountid: "00000000-0000-0000-0000-000000000001", name: "Contoso Ltd", telephone1: "+1 (425) 555-0100" },
+  { accountid: "00000000-0000-0000-0000-000000000002", name: "Fabrikam Inc", telephone1: "+1 (206) 555-0140" },
+  { accountid: "00000000-0000-0000-0000-000000000003", name: "Adventure Works", telephone1: "+1 (312) 555-0190" },
+];
+
+export class MockApiService implements IApiService {
+  private accounts: Record<string, any> = Object.fromEntries(
+    SEED_ACCOUNTS.map((a) => [a.accountid, { ...a }]),
+  );
+  private nextId = SEED_ACCOUNTS.length + 1;
+
+  retrieveMultipleRecords(entity: string): Promise<{ entities: any[] }> {
+    return logCrud(
+      { op: "READ", entity, resultCount: (r) => r?.entities?.length },
+      async () => ({
+        entities: entity === "accounts" ? Object.values(this.accounts) : [],
+      }),
+    );
+  }
+
+  createRecord(entity: string, record: any): Promise<any> {
+    return logCrud({ op: "CREATE", entity, resultId: (r) => r?.id }, async () => {
+      const id = `00000000-0000-0000-0000-${String(this.nextId++).padStart(12, "0")}`;
+      if (entity === "accounts") this.accounts[id] = { accountid: id, ...record };
+      return { id };
+    });
+  }
+
+  updateRecord(entity: string, id: string, record: any): Promise<any> {
+    return logCrud({ op: "UPDATE", entity, id }, async () => {
+      const key = id.replace(/[{}]/g, "");
+      if (this.accounts[key]) this.accounts[key] = { ...this.accounts[key], ...record };
+      return { success: true };
+    });
+  }
+
+  deleteRecord(entity: string, id: string): Promise<void> {
+    return logCrud({ op: "DELETE", entity, id }, async () => {
+      delete this.accounts[id.replace(/[{}]/g, "")];
+    });
+  }
+
+  executeRequest(requestName: string): Promise<any> {
+    return logCrud({ op: "EXECUTE", entity: requestName }, async () => ({}));
+  }
+
+  associateRecord(entity: string, id: string): Promise<void> {
+    return logCrud({ op: "ASSOCIATE", entity, id }, async () => undefined);
+  }
+}

package/templates/power-pages-island/src/core/services/portalSeam.assert.ts

@@ -0,0 +1,14 @@
+// Compile-time drift guard (typechecked by `npm run build` → `tsc --noEmit`, and by
+// the create-dynamics-app power-pages-island template build e2e). `PortalSeamService`
+// — the create-app 6-method `dataverse-seam` adapter shipped in
+// `@dataverse-kit/portal-api-service` — MUST stay structurally assignable to THIS
+// template's local seam `IApiService`, so `App.tsx` can inject it with no cast. That
+// package can't import the create-app template interface, so the assertion lives here,
+// where both types resolve. Type-only — no runtime, tree-shaken from the bundle.
+import type { IApiService } from "./IApiService";
+import type { PortalSeamService } from "@dataverse-kit/portal-api-service";
+
+// If PortalSeamService drifts from the seam shape, `true` is no longer assignable to
+// `never` and this fails to compile.
+type PortalSeamSatisfiesSeam = PortalSeamService extends IApiService ? true : never;
+export const _portalSeamDriftGuard: PortalSeamSatisfiesSeam = true;

package/templates/power-pages-island/src/island-env.d.ts

@@ -0,0 +1,12 @@
+// Webpack/ts-loader builds have no `vite/client` types. The shared data-access seam
+// (templates/_shared/dataverse-seam) includes ServiceFactory, which reads
+// `import.meta.env.VITE_USE_PROXY` for the Vite custom-page host. This Power Pages
+// island does NOT use ServiceFactory (App.tsx builds MockApiService / PortalSeamService
+// directly), so it is tree-shaken from the bundle — but `tsc` / ts-loader still
+// typecheck it. This minimal ambient declaration lets that unused file compile here.
+//
+// NOTE: this file MUST live under src/ — the tsconfig is `include: ["src"]`, so a
+// project-root *.d.ts would be excluded and the shim would be missed.
+interface ImportMeta {
+  readonly env: Record<string, unknown>;
+}

package/templates/power-pages-island/src/islands.tsx

@@ -0,0 +1,38 @@
+import * as React from "react";
+import { createRoot } from "react-dom/client";
+import { initLogging } from "@khester/reusable-components";
+import { App } from "./App";
+
+// Wire up the localhost-only troubleshooting hooks (window.dumpAppLogs()); no-op in a
+// live portal.
+initLogging();
+
+// A traditional Power Pages portal is server-rendered (Liquid). This bundle is an
+// ISLAND: it hydrates React ONLY into the nodes a maker tags in Liquid, leaving the
+// rest of the page untouched — the delta the MS code-site scaffolder (whole-page SPA)
+// can't do. Tag a mount point with `data-dvkit-island="<name>"` (the name is a hook
+// for future per-widget routing) and reference this web file:
+//
+//   <div data-dvkit-island="accounts"></div>
+//   <script src="/{{projectName}}.js"></script>
+//
+const SELECTOR = "[data-dvkit-island]";
+
+function mountIslands(): void {
+  document.querySelectorAll<HTMLElement>(SELECTOR).forEach((node) => {
+    // Idempotent — a partial-page refresh or a duplicated include must not double-mount.
+    if (node.dataset.dvkitMounted === "true") return;
+    node.dataset.dvkitMounted = "true";
+    createRoot(node).render(
+      <React.StrictMode>
+        <App island={node.dataset.dvkitIsland} />
+      </React.StrictMode>,
+    );
+  });
+}
+
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", mountIslands);
+} else {
+  mountIslands();
+}

package/templates/power-pages-island/src/useHostWidth.ts

@@ -0,0 +1,53 @@
+import * as React from "react";
+
+/**
+ * Width available to the component, in px, kept live as the host resizes.
+ *
+ * Two modes, because the browser hosts are not all shaped the same:
+ *
+ *  - **Pass a ref** when the component is mounted into an element on a larger page
+ *    (a Power Pages island). The viewport is then the whole portal page, which may be
+ *    far wider than the slot the island occupies, so it must measure its own box.
+ *  - **Pass nothing** when the component owns a full-page iframe (web resource /
+ *    Vite host). There the viewport *is* the control's width.
+ *
+ * The PCF host uses neither — it gets a properly scoped measurement from
+ * `context.mode.allocatedWidth` after opting in with `trackContainerResize(true)`.
+ *
+ * ★ Why measure at all rather than ask the platform what device this is: verified
+ * live 2026-07-25 on a physical iPhone in the native Power Apps app, a model-driven
+ * custom page reports `client: "Web"` and `formFactor: 1` (Desktop). Form-factor
+ * branching therefore hands every phone the desktop layout — and passes every test
+ * that is not run on a real device.
+ */
+export function useHostWidth(ref?: React.RefObject<HTMLElement | null>): number {
+  const [width, setWidth] = React.useState<number>(() =>
+    typeof window === "undefined" ? 0 : window.innerWidth,
+  );
+
+  React.useEffect(() => {
+    const el = ref?.current;
+
+    if (el && typeof ResizeObserver !== "undefined") {
+      const ro = new ResizeObserver((entries) => {
+        for (const entry of entries) setWidth(entry.contentRect.width);
+      });
+      ro.observe(el);
+      setWidth(el.getBoundingClientRect().width);
+      return () => ro.disconnect();
+    }
+
+    // Viewport fallback: no ref, or an environment without ResizeObserver.
+    const onResize = () => setWidth(window.innerWidth);
+    window.addEventListener("resize", onResize);
+    // iOS Safari does not reliably fire `resize` on rotation, so listen for both.
+    window.addEventListener("orientationchange", onResize);
+    onResize();
+    return () => {
+      window.removeEventListener("resize", onResize);
+      window.removeEventListener("orientationchange", onResize);
+    };
+  }, [ref]);
+
+  return width;
+}

package/templates/power-pages-island/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "lib": ["DOM", "DOM.Iterable", "ES2020"],
+    "types": []
+  },
+  "include": ["src"]
+}