@khester/create-dynamics-app 3.0.0 → 3.2.0

package/templates/host-swap/README.md

@@ -1,7 +1,9 @@
 # {{projectName}} — host-swap component
 
 One React component, written once against an injected `IApiService`, that you can
-host as a **PCF control**, a **Dynamics 365 custom page**, or a **web resource**.
+host as a **PCF control** or as a **web resource** (in two flavours — webpack, or Vite under the
+legacy `custom-page` host name; ★ despite the name that host emits an HTML web resource, NOT a
+Power Apps custom page — for a real one, use `--host pcf` and drop the control on the page).
 You chose the host at scaffold time (`--host pcf`, `--host custom-page`, or
 `--host web-resource`); to retarget, scaffold again with another host and copy your
 `src/Component.tsx` across — the component never changes, only the thin wrapper does.
@@ -17,7 +19,7 @@ You chose the host at scaffold time (`--host pcf`, `--host custom-page`, or
 
 ## How each host supplies the data service
 
-- **Custom page (Vite):** `App.tsx` resolves the Xrm context and `ServiceFactory`
+- **`custom-page` host (Vite web resource):** `App.tsx` resolves the Xrm context and `ServiceFactory`
   picks Mock (localhost), the token-proxy (`npm run dev` with `DYNAMICS_URL`), or
   the production `XrmApiService` (deployed).
 - **PCF control (pcf-scripts):** the control builds the service directly — a
@@ -36,3 +38,56 @@ npm install
 # pcf:          npm run build   (pcf-scripts build)    |  npm start     (PCF test harness)
 # web-resource: npm run build   (webpack --mode production) | npm run dev (webpack dev server)
 ```
+
+> ★ **`pcf-scripts build` exits 0 even when the build FAILS.** If you script this in CI, grep the
+> log for `[build] Succeeded` and for the absence of `compiled with N errors` — don't trust `$?`.
+
+## Deploy
+
+The three hosts are **not** symmetric here. Only the PCF host has a first-class deploy path.
+
+### PCF
+
+```bash
+pac pcf push --publisher-prefix <your-prefix>
+```
+
+Builds, wraps the control in a temporary `PowerAppsToolsTemp_<prefix>` solution, imports it and
+publishes. This needs the `.pcfproj` this template ships; its `ProjectGuid` is generated per
+scaffold, so two controls from this template never collide inside one solution.
+
+To ship versioned **managed + unmanaged** solution zips instead of a temp solution, wrap the
+control in a solution project and build that:
+
+```bash
+pac solution init --publisher-name <you> --publisher-prefix <p>
+pac solution add-reference --path .
+dotnet build -c Release -p:SolutionPackageType=Both
+pac solution import --path bin/Release/<Solution>.zip
+```
+
+(If you have the `claude-workspace` checkout, `msft/04-dynamics/scripts/deploy/package-control.sh
+--source . --version 1.0.0 --output ./dist` automates exactly that — it discards this `.pcfproj`
+and generates its own, so the two paths never conflict.)
+
+★ **Bump `ControlManifest.Input.xml`'s `version=` on every change.** Neither command does it for
+you, and without a bump the platform serves the cached previous build — the single most common
+"my fix didn't deploy".
+
+★ **The `<platform-library>` versions must be exact.** `pcf-scripts` matches a *range* and
+silently remaps the bundle, but leaves your number in the manifest — so a wrong version **builds
+green and fails to load in every host**. React must be `16.14.0`; Fluent `@fluentui/react` must be
+`8.29.0` or `8.121.1`.
+
+### Web resource
+
+No deploy script ships. Build, then upload `dist/` as a JavaScript web resource — via the maker
+portal, `pac webresource push`, or the workspace's `webresource-manager.sh` if you have that
+checkout — and reference it from a form or the sitemap.
+
+### Custom page
+
+★ **No deploy path ships for this host.** Despite the name it emits a Vite-built **HTML web
+resource**, not a Power Apps custom page — see the registry description. If you want an uploader,
+the `react-custom-page` artifact has one (`tools/deploy/deploy-webresource.cjs`); if you want a
+*real* model-driven custom page, use `--host pcf` and drop the control onto the page in Studio.

package/templates/host-swap/_variants/host.custom-page/src/App.tsx

@@ -1,14 +1,18 @@
 import * as React from "react";
 import { ServiceFactory } from "./core/services/ServiceFactory";
 import { Component } from "./Component";
+import { useHostWidth } from "./useHostWidth";
 
-// Resolve the Xrm context when hosted as a Dynamics custom page (the app runs in
-// an iframe → window.parent.Xrm, or window.Xrm). ServiceFactory then picks the
-// IApiService per environment: Mock on localhost, the token-proxy in dev, or the
-// production XrmApiService when deployed.
+// Resolve the Xrm context. This host is an HTML WEB RESOURCE (not a Power Apps
+// custom page): it runs in an iframe inside a model-driven app, so Xrm comes from
+// window.parent. ServiceFactory then picks the IApiService per environment: Mock on
+// localhost, the token-proxy in dev, or the production XrmApiService when deployed.
 const Xrm = (window.parent as any)?.Xrm ?? (window as any).Xrm;
 
 export const App: React.FC = () => {
   const api = React.useMemo(() => ServiceFactory.createApiService(Xrm), []);
-  return <Component api={api} />;
+  // Embedded in a form iframe this is often narrow on a phone, so measure rather
+  // than assume desktop.
+  const width = useHostWidth();
+  return <Component api={api} width={width} />;
 };

package/templates/host-swap/_variants/host.pcf/ControlManifest.Input.xml

@@ -6,8 +6,32 @@
     <property name="value" display-name-key="value_Display_Key" description-key="value_Desc_Key" of-type="SingleLine.Text" usage="bound" required="false" />
     <resources>
       <code path="index.ts" order="1"/>
-      <platform-library name="React" version="18.2.0" />
-      <platform-library name="Fluent" version="8.115.6" />
+      <!--
+        ★ These versions MUST come from Microsoft's supported platform-library list; arbitrary
+        versions do not fail the build, they fail the RUNTIME. `pcf-scripts` silently maps an
+        unsupported version to the nearest supported one when bundling (8.115.6 was emitted as
+        `external "FluentUIReactv81211"`), but the MANIFEST keeps the number the platform then
+        cannot resolve — so the control builds green and renders "Error loading control" in every
+        host. Live-diagnosed 2026-07-26: this template previously declared React 18.2.0 + Fluent
+        8.115.6, neither of which is supported, and could not load in a form OR a custom page.
+        Supported (learn.microsoft.com/power-apps/developer/component-framework/react-controls-platform-libraries):
+          React  → 16.14.0 only (the platform loads 17.0.2 in model-driven, 16.14.0 in canvas)
+          Fluent → @fluentui/react 8.29.0 or 8.121.1; @fluentui/react-components >=9.4.0 <=9.46.2
+        v8 and v9 cannot both be declared in one manifest.
+
+        ★ The rule is EQUALITY, not range membership. pcf-scripts matches a supported
+        {minVersion, maxVersion} range and remaps the bundle to that row's platformVersion,
+        but never rewrites this file — so a version inside the range yet unequal to its
+        platformVersion builds green and cannot be resolved at runtime. Asserted in
+        src/__tests__/registry.test.ts.
+
+        ★ package.json intentionally carries react@^18 while this says 16.14.0: the shared
+        dataverse-seam pulls @khester/reusable-components, whose peer is react>=17. So the
+        types will NOT stop you writing a React 18 API that crashes only in a custom page
+        (canvas serves 16.14.0). Don't. See package.json `_comment_versions`.
+      -->
+      <platform-library name="React" version="16.14.0" />
+      <platform-library name="Fluent" version="8.121.1" />
       <resx path="strings/{{componentName}}.1033.resx" version="1.0.0" />
     </resources>
     <feature-usage>

package/templates/host-swap/_variants/host.pcf/gitignore

@@ -3,3 +3,10 @@ out/
 generated/
 *.log
 .env
+
+# MSBuild output from the .pcfproj (`pac pcf push` / `dotnet build`). Without these
+# the first push litters an untracked obj/PowerAppsToolsTemp_* tree into the repo.
+bin/
+obj/
+*.binlog
+.vs/

package/templates/host-swap/_variants/host.pcf/index.ts

@@ -15,12 +15,18 @@ import { MockApiService } from "./src/core/services/MockApiService";
  * the session cookie — no Xrm or clientUrl needed. On localhost (the pcf-scripts
  * test harness) it falls back to the in-memory mock so the control renders with
  * no org.
+ *
+ * ★ This holds in a model-driven CUSTOM PAGE too — verified live 2026-07-25: a
+ * custom page reports the org origin (not apps.powerapps.com) and a same-origin
+ * fetch returns 200, in a desktop browser and in the native Power Apps iOS app.
+ * That is observed behaviour rather than a documented contract, so if it ever
+ * regresses, swap this line for `context.webAPI` (the API Microsoft documents).
  */
 export class {{componentName}} implements ComponentFramework.ReactControl<IInputs, IOutputs> {
   private api!: IApiService;
 
   public init(
-    _context: ComponentFramework.Context<IInputs>,
+    context: ComponentFramework.Context<IInputs>,
     _notifyOutputChanged: () => void,
     _state: ComponentFramework.Dictionary,
   ): void {
@@ -28,10 +34,22 @@ export class {{componentName}} implements ComponentFramework.ReactControl<IInput
       typeof window !== "undefined" &&
       /^(localhost|127\.0\.0\.1)$/.test(window.location.hostname);
     this.api = onLocalhost ? new MockApiService() : new FetchApiService("");
+
+    // Opt in to container-size reporting. WITHOUT THIS `allocatedWidth` never
+    // updates, so the control cannot respond to the device or to a resize — the
+    // usual reason a "responsive" PCF silently isn't.
+    context.mode.trackContainerResize(true);
   }
 
-  public updateView(_context: ComponentFramework.Context<IInputs>): React.ReactElement {
-    return React.createElement(Component, { api: this.api });
+  public updateView(context: ComponentFramework.Context<IInputs>): React.ReactElement {
+    // Pass the measured width down. Do NOT use context.client.getFormFactor():
+    // verified live on a physical iPhone in the native Power Apps app, a custom
+    // page reports formFactor 1 (Desktop) and client "Web", so form-factor
+    // branching hands every phone the desktop layout.
+    return React.createElement(Component, {
+      api: this.api,
+      width: context.mode.allocatedWidth,
+    });
   }
 
   public getOutputs(): IOutputs {

package/templates/host-swap/_variants/host.pcf/package.json

@@ -1,7 +1,7 @@
 {
   "name": "{{projectName}}",
   "version": "1.0.0",
-  "description": "{{componentName}} — host-swap component hosted as a PCF control",
+  "description": "{{componentName}} \u2014 host-swap component hosted as a PCF control",
   "scripts": {
     "build": "pcf-scripts build",
     "clean": "pcf-scripts clean",
@@ -9,8 +9,24 @@
     "start": "pcf-scripts start",
     "refreshTypes": "pcf-scripts refreshTypes"
   },
+  "_comment_versions": [
+    "\u2605 @fluentui/react is PINNED EXACTLY to the <platform-library> version in",
+    "ControlManifest.Input.xml and must move with it. This is a VIRTUAL control: react, react-dom",
+    "and @fluentui/react are externalized by pcf-scripts and supplied by the platform at runtime \u2014",
+    "and by pcf-start in the harness \u2014 so none of them reaches the bundle. That makes the version a",
+    "TYPES decision: the compiler should see the API the platform will actually serve. A caret",
+    "defeats it \u2014 ^8.120.0 resolved to 8.125.7 while the platform served 8.121.1.",
+    "",
+    "\u2605 react/react-dom stay at ^18 on purpose: pinning them to the manifest's 16.14.0 fails",
+    "npm install ERESOLVE, because the shared dataverse-seam imports @khester/reusable-components",
+    "(peer react>=17). But the @types ARE pinned to 16, which is what actually matters here \u2014 the",
+    "canvas runtime behind a custom page serves React 16.14.0, so useId/useTransition/",
+    "useSyncExternalStore must be a COMPILE error rather than a crash that only reproduces on a",
+    "phone. Since nothing from these packages is bundled, the runtime versions are inert and the",
+    "types carry the contract."
+  ],
   "dependencies": {
-    "@fluentui/react": "^8.120.0",
+    "@fluentui/react": "8.121.1",
     "@types/powerapps-component-framework": "^1.3.18",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
@@ -18,8 +34,8 @@
   "devDependencies": {
     "@microsoft/eslint-config-spfx": "^1.18.2",
     "@types/node": "^18.16.9",
-    "@types/react": "^18.2.0",
-    "@types/react-dom": "^18.2.0",
+    "@types/react": "^16.14.0",
+    "@types/react-dom": "^16.9.0",
     "eslint-plugin-react-hooks": "^4.6.0",
     "pcf-scripts": "^1",
     "pcf-start": "^1",

package/templates/host-swap/_variants/host.pcf/{{componentName}}.pcfproj

@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  MSBuild project for the PCF control. Without this file `pac pcf push` fails
+  outright, so a scaffolded control has no deploy path at all — which is exactly
+  what this template shipped before.
+
+  Two ways to deploy (see the README's Deploy section):
+    • pac pcf push --publisher-prefix <p>   — fastest dev loop; wraps the control
+      in a temporary PowerAppsToolsTemp_<p> solution and imports it.
+    • package-control.sh --source <dir>     — emits versioned managed/unmanaged
+      solution zips with no temp solution. That script DISCARDS this file and
+      generates its own, so the two never conflict.
+
+  ProjectGuid is generated per scaffold, so two controls from this template never collide
+  inside one solution.
+-->
+<Project ToolsVersion="15.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <PropertyGroup>
+    <PowerAppsTargetsPath>$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\PowerApps</PowerAppsTargetsPath>
+  </PropertyGroup>
+
+  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" />
+  <Import Project="$(PowerAppsTargetsPath)\Microsoft.PowerApps.VisualStudio.Pcf.props" Condition="Exists('$(PowerAppsTargetsPath)\Microsoft.PowerApps.VisualStudio.Pcf.props')" />
+
+  <PropertyGroup>
+    <Name>{{componentName}}</Name>
+    <ProjectGuid>{{{projectGuid}}}</ProjectGuid>
+    <OutputPath>$(MSBuildThisFileDirectory)out\controls</OutputPath>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <TargetFrameworkVersion>v4.6.2</TargetFrameworkVersion>
+    <TargetFramework>net462</TargetFramework>
+    <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.PowerApps.MSBuild.Pcf" Version="1.*" />
+    <!-- Supplies the net462 reference assemblies on macOS/Linux so this builds
+         without a Windows image (otherwise MSB3644). -->
+    <PackageReference Include="Microsoft.NETFramework.ReferenceAssemblies" Version="1.0.3" PrivateAssets="All" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\.gitignore" />
+    <!-- A scaffolded project always has a nested .git (initGit runs unless --skip-git); the
+         probe this was modelled on lives inside a repo and never had one. package-control.sh
+         rm -rf's it before building, which is the same signal. -->
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\.git\**" />
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\.vs\**" />
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\bin\**" />
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\obj\**" />
+    <ExcludeDirectories Include="$(OutputPath)\**" />
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\*.pcfproj" />
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\*.pcfproj.user" />
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\*.sln" />
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\node_modules\**" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="$(MSBuildThisFileDirectory)\**" Exclude="@(ExcludeDirectories)" />
+  </ItemGroup>
+
+  <Import Project="$(MSBuildToolsPath)\Microsoft.Common.targets" />
+  <Import Project="$(PowerAppsTargetsPath)\Microsoft.PowerApps.VisualStudio.Pcf.targets" Condition="Exists('$(PowerAppsTargetsPath)\Microsoft.PowerApps.VisualStudio.Pcf.targets')" />
+
+</Project>

package/templates/host-swap/_variants/host.web-resource/src/App.tsx

@@ -3,6 +3,7 @@ import type { IApiService } from "./core/services/IApiService";
 import { FetchApiService } from "./core/services/FetchApiService";
 import { MockApiService } from "./core/services/MockApiService";
 import { Component } from "./Component";
+import { useHostWidth } from "./useHostWidth";
 
 // A web resource is served from the org origin, so a same-origin relative
 // /api/data/v9.2 fetch is authenticated by the session cookie — no Xrm or
@@ -14,5 +15,8 @@ export const App: React.FC = () => {
     const onLocalhost = /^(localhost|127\.0\.0\.1)$/.test(window.location.hostname);
     return onLocalhost ? new MockApiService() : new FetchApiService("");
   }, []);
-  return <Component api={api} />;
+  // A web resource embedded on a form is often narrow on a phone, so measure the
+  // viewport rather than assuming desktop.
+  const width = useHostWidth();
+  return <Component api={api} width={width} />;
 };

package/templates/host-swap/src/Component.tsx

@@ -17,14 +17,33 @@ initializeIcons();
 
 /**
  * The ONE host-agnostic component. It depends on nothing but an injected
- * `IApiService` — no PCF `context`, no Xrm, no lifecycle, no bundler globals — so
- * the SAME source renders unchanged inside a PCF control and a Dynamics custom
- * page. Each host's thin wrapper builds the right `IApiService` and mounts this.
+ * `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">',
@@ -47,10 +66,14 @@ const COLUMNS: IColumn[] = [
   { key: "telephone1", name: "Phone", fieldName: "telephone1", minWidth: 140, isResizable: true },
 ];
 
-export const Component: React.FC<ComponentProps> = ({ api }) => {
+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
@@ -70,12 +93,13 @@ export const Component: React.FC<ComponentProps> = ({ api }) => {
     <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 and a
-        Dynamics custom page; only the thin host wrapper changes.
+        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 && (
+      {rows && !isNarrow && (
         <DetailsList
           items={rows}
           columns={COLUMNS}
@@ -84,6 +108,29 @@ export const Component: React.FC<ComponentProps> = ({ api }) => {
           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/host-swap/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/pcf-dataset/dev/harness/dataverse.ts

@@ -0,0 +1,82 @@
+import { apiFetch, toHttpError } from '@dataverse-kit/pcf-dev-harness/shell';
+import type { ColumnDef } from '@dataverse-kit/grid-kit';
+import type { Row } from '../../{{componentName}}/{{componentName}}App';
+
+/**
+ * TIER 2 of the dev harness — the {{componentName}}-specific live-org read.
+ *
+ * The reusable parts (shell, proxy, token refresh, `apiFetch`'s one-shot 401/403 retry) come
+ * from `@dataverse-kit/pcf-dev-harness`. This file is what only THIS control can supply:
+ * turning an OData recordset into the exact `items` + `columns` its App expects.
+ *
+ * All calls go through the same-origin `/api/data` proxy in `vite.config.ts`, which injects
+ * the bearer token server-side — no token ever reaches the browser. READ-ONLY: this is a
+ * read-only grid, so there is no save counterpart.
+ */
+
+export type { HttpError } from '@dataverse-kit/pcf-dev-harness/shell';
+
+/**
+ * Shape a raw OData recordset into the App's props.
+ *
+ * Prefers the `@OData.Community.Display.V1.FormattedValue` annotation for each field, which
+ * is what the deployed control sees via `record.getFormattedValue()` — currency symbols,
+ * option-set labels and lookup display names rather than raw ids. `fields` fixes the column
+ * set and order; the first field is treated as the primary column.
+ */
+function shapeResult(
+  rows: Array<Record<string, unknown>>,
+  fields: string[],
+): { items: Row[]; columns: ColumnDef<Row>[] } {
+  const items: Row[] = rows.map((r, i) => {
+    // The harness never navigates, so a per-render index is a stable enough record id.
+    const row: Row = { key: String(i) };
+    for (const f of fields) {
+      const formatted = r[`${f}@OData.Community.Display.V1.FormattedValue`];
+      row[f] = formatted !== undefined && formatted !== null ? String(formatted) : String(r[f] ?? '');
+    }
+    return row;
+  });
+
+  const columns: ColumnDef<Row>[] = fields.map((f, i) => ({
+    key: f,
+    fieldName: f,
+    name: f,
+    rendererType: 'text',
+    minWidth: i === 0 ? 200 : 120,
+    maxWidth: i === 0 ? 320 : 240,
+    isResizable: true,
+    isSortable: true,
+    isFilterable: true,
+  }));
+
+  return { items, columns };
+}
+
+/**
+ * Fetch `top` rows of `select` columns from an entity set.
+ *
+ * @param entitySetName plural set name, e.g. `accounts`
+ * @param select        comma-separated logical names, e.g. `name,revenue`
+ * @param top           max rows
+ */
+export async function fetchRecords(
+  entitySetName: string,
+  select: string,
+  top: string,
+): Promise<{ items: Row[]; columns: ColumnDef<Row>[] }> {
+  const fields = select
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  const params = new URLSearchParams({ $select: fields.join(','), $top: top || '50' });
+  const res = await apiFetch(`/api/data/v9.2/${entitySetName}?${params}`, {
+    // Ask for the formatted-value annotations the deployed control renders.
+    headers: { Prefer: 'odata.include-annotations="OData.Community.Display.V1.FormattedValue"' },
+  });
+  if (!res.ok) throw await toHttpError(res);
+
+  const body = (await res.json()) as { value?: Array<Record<string, unknown>> };
+  return shapeResult(body.value ?? [], fields);
+}

package/templates/pcf-dataset/dev/index.html

@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{componentName}} – Dev Harness</title>
+    <style>
+      html, body, #root {
+        margin: 0;
+        padding: 0;
+        height: 100%;
+        font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>