@spfx-fast/spfx-workbench 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +240 -2
  3. package/bin/spfx-workbench-auth.mjs +143 -0
  4. package/bin/spfx-workbench-capture.mjs +5 -0
  5. package/bin/spfx-workbench-debug.mjs +155 -0
  6. package/bin/spfx-workbench-doctor.mjs +2 -0
  7. package/bin/spfx-workbench-heft-target.mjs +2 -0
  8. package/bin/spfx-workbench-replay.mjs +2 -0
  9. package/bin/spfx-workbench.mjs +97 -0
  10. package/docs/mock-data-and-capture.md +52 -0
  11. package/docs/sharepoint-behavior-snapshot-2026-11-15-1455Z.md +67 -0
  12. package/fixtures/library-items.synthetic.json +23 -0
  13. package/index.html +13 -0
  14. package/package.json +58 -4
  15. package/scripts/benchmark-capture-import.mjs +50 -0
  16. package/scripts/benchmark-consumer-hmr.mjs +251 -0
  17. package/scripts/benchmark-mock-api.mjs +114 -0
  18. package/scripts/check-tarball-install.mjs +413 -0
  19. package/scripts/diagnose-consumer.mjs +228 -0
  20. package/scripts/diff-captures.mjs +452 -0
  21. package/scripts/import-synthetic-capture.mjs +60 -0
  22. package/scripts/minimal-playwright-state.mjs +15 -0
  23. package/scripts/mock-contract.mjs +375 -0
  24. package/scripts/replay-sharepoint-capture.mjs +123 -0
  25. package/scripts/resolve-chromium.mjs +22 -0
  26. package/scripts/resolve-serve-target.mjs +70 -0
  27. package/scripts/spfx-node-runtime.mjs +19 -0
  28. package/scripts/watch-sharepoint-capture.mjs +395 -0
  29. package/scripts/write-local-capture.mjs +121 -0
  30. package/src/auth-state.mjs +44 -0
  31. package/src/contracts/sharepoint-rest.d.ts +38 -0
  32. package/src/contracts/simulator-context.d.ts +38 -0
  33. package/src/data-source-label.mjs +10 -0
  34. package/src/format-modified.mjs +8 -0
  35. package/src/lifecycle-webpart.jsx +43 -0
  36. package/src/main.jsx +14 -0
  37. package/src/simulator-context.mjs +94 -0
  38. package/src/spfx-preview-shims.mjs +21 -0
  39. package/src/workbench.css +187 -0
  40. package/src/workbench.jsx +222 -0
  41. package/vite.config.js +399 -0
@@ -0,0 +1,97 @@
1
+ #!/usr/bin/env node
2
+ import { readFile, readdir, realpath, stat } from 'node:fs/promises';
3
+ import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
4
+ import { fileURLToPath } from 'node:url';
5
+ import { createServer } from 'vite';
6
+
7
+ const args = process.argv.slice(2);
8
+ const valueAfter = (flag) => {
9
+ const index = args.indexOf(flag);
10
+ return index < 0 ? undefined : args[index + 1];
11
+ };
12
+
13
+ if (args.includes('--help') || args.includes('-h')) {
14
+ process.stdout.write('Usage: spfx-workbench --component <project-relative-file> [--props-file <project-relative-json>] [--port <port>]\n');
15
+ process.exit(0);
16
+ }
17
+
18
+ const componentArg = valueAfter('--component');
19
+ const propsFileArg = valueAfter('--props-file');
20
+ const port = Number(valueAfter('--port') ?? 4176);
21
+ const consumerRoot = resolve(process.cwd());
22
+ const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
23
+
24
+ async function componentTitle(componentPath, consumerRoot) {
25
+ let directory = dirname(componentPath);
26
+ while (directory === consumerRoot || directory.startsWith(`${consumerRoot}${sep}`)) {
27
+ let manifests = [];
28
+ try { manifests = (await readdir(directory)).filter((name) => name.endsWith('.manifest.json')); } catch {}
29
+ for (const name of manifests) {
30
+ try {
31
+ const manifestPath = resolve(directory, name);
32
+ if ((await stat(manifestPath)).size > 256_000) continue;
33
+ const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
34
+ if (manifest.componentType !== 'WebPart') continue;
35
+ const title = manifest.preconfiguredEntries?.[0]?.title?.default;
36
+ if (typeof title === 'string' && title.trim()) return title.trim().slice(0, 120);
37
+ } catch {}
38
+ }
39
+ if (directory === consumerRoot) break;
40
+ directory = dirname(directory);
41
+ }
42
+ return componentPath.split(sep).at(-1).replace(/\.[^.]+$/, '');
43
+ }
44
+
45
+ try {
46
+ if (!componentArg || !Number.isInteger(port) || port < 1 || port > 65535) {
47
+ throw new Error('Provide --component <file> and a valid --port (default 4176).');
48
+ }
49
+ const canonicalConsumerRoot = await realpath(consumerRoot);
50
+ const componentPath = await realpath(resolve(canonicalConsumerRoot, componentArg));
51
+ const relativePath = relative(canonicalConsumerRoot, componentPath);
52
+ if (!relativePath || relativePath === '..' || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {
53
+ throw new Error('The component must be inside the consuming project directory.');
54
+ }
55
+ if (!/\.[jt]sx?$/.test(componentPath)) throw new Error('The component must be a JS, JSX, TS, or TSX module.');
56
+ if (!(await stat(componentPath)).isFile()) throw new Error('The component path must point to a file.');
57
+
58
+ let props = {};
59
+ if (propsFileArg) {
60
+ const propsPath = await realpath(resolve(canonicalConsumerRoot, propsFileArg));
61
+ const propsRelative = relative(canonicalConsumerRoot, propsPath);
62
+ if (!propsRelative || propsRelative === '..' || propsRelative.startsWith(`..${sep}`) || isAbsolute(propsRelative)) {
63
+ throw new Error('The props file must be inside the consuming project directory.');
64
+ }
65
+ const propsInfo = await stat(propsPath);
66
+ if (!propsInfo.isFile()) throw new Error('The props path must point to a file.');
67
+ if (propsInfo.size > 1_000_000) throw new Error('The props file must be no larger than 1 MB.');
68
+ props = JSON.parse(await readFile(propsPath, 'utf8'));
69
+ if (!props || Array.isArray(props) || typeof props !== 'object') throw new Error('The props file must contain a JSON object.');
70
+ if (Object.hasOwn(props, 'context')) throw new Error('The simulator owns the context prop; remove it from the props file.');
71
+ }
72
+
73
+ const canonicalPackageRoot = await realpath(packageRoot);
74
+ process.chdir(canonicalPackageRoot);
75
+ process.env.SPFX_WORKBENCH_COMPONENT = componentPath;
76
+ process.env.VITE_SPFX_WORKBENCH_TITLE = await componentTitle(componentPath, canonicalConsumerRoot);
77
+ process.env.SPFX_WORKBENCH_DATA_ROOT = canonicalConsumerRoot;
78
+ process.env.SPFX_WORKBENCH_PROPS = JSON.stringify(props);
79
+ const server = await createServer({
80
+ configFile: resolve(packageRoot, 'vite.config.js'),
81
+ root: packageRoot,
82
+ server: {
83
+ host: '127.0.0.1',
84
+ port,
85
+ strictPort: true,
86
+ fs: { allow: [canonicalConsumerRoot, canonicalPackageRoot] },
87
+ },
88
+ });
89
+ await server.listen();
90
+ server.printUrls();
91
+ const close = async () => { await server.close(); process.exit(0); };
92
+ process.once('SIGINT', close);
93
+ process.once('SIGTERM', close);
94
+ } catch (error) {
95
+ process.stderr.write(`SPFx Workbench: ${error.message}\n`);
96
+ process.exitCode = 1;
97
+ }
@@ -0,0 +1,52 @@
1
+ # Mock data contract
2
+
3
+ The capture and replay contract is intentionally narrow: a successful, read-only SharePoint REST list-items GET. It reflects Microsoft’s documented `SPHttpClient` example selecting `Id`, `Title`, `FileLeafRef`, and `Modified` from list items. The response models are recorded in [sharepoint-rest.d.ts](../src/contracts/sharepoint-rest.d.ts); these are response models shown in Microsoft’s example, not imported SPFx SDK declarations.
4
+
5
+ ## Contract
6
+
7
+ - Format: `spfx-workbench-capture/v1`
8
+ - Route key: `sp-rest-library-items` (the actual tenant/site/list URL is never stored)
9
+ - Request: `GET`, fixed route key, only `$select` and `$top`; `$select` is restricted to the four fields and `$top` is from 1 to 100
10
+ - Response: status `200`, a `value` array with at most 100 items
11
+ - Item fields: `Id` is `Edm.Int32` from 0 through 2,147,483,647; `Title` and `FileLeafRef` are strings; `Modified` is an ISO 8601 timestamp with a timezone
12
+ - Source: must explicitly be `synthetic`
13
+
14
+ The installed `spfx-workbench-doctor` command reports this route, operation, fields, query options, limits, unsupported calls, and source URL as machine-readable mock coverage. The workbench contract is based on Microsoft's [SPFx 1.24.1 list-items tutorial](https://learn.microsoft.com/en-us/sharepoint/dev/spfx/copilot/get-started/connect-to-sharepoint-data#show-the-items-in-a-list), which selects these four fields and requests 25 items. The local models are not SDK declarations.
15
+
16
+ ## Built-in web title read
17
+
18
+ The read-only context also supports Microsoft's documented `SPHttpClient.get` request to `/_api/web?$select=Title`. It returns `{ "Title": "Workbench site" }` from a committed synthetic fallback when no HAR entry matches. Only the `Title` selection is supported by this synthetic fallback; a matching tenant HAR can replay other captured web queries directly. The request and response shape follow Microsoft's [SPFx SharePoint API example](https://learn.microsoft.com/en-us/sharepoint/dev/spfx/connect-to-sharepoint#connect-to-sharepoint-api-using-the-sphttpclient).
19
+
20
+ ## Synthetic list-metadata fallback
21
+
22
+ When no matching HAR response exists, the synthetic fallback supports Microsoft's list-picker query exactly: `GET /_api/web/lists?$select=Id,Title,ItemCount&$filter=Hidden eq false&$orderby=Title`. It returns two invented list rows with string IDs, titles, and integer item counts from a separate committed synthetic route. The synthetic route rejects other selections, filters, ordering, and query options. A matching tenant HAR response is checked first and can include other query shapes. The shape and request are based on Microsoft's [SPFx list-picker example](https://learn.microsoft.com/en-us/sharepoint/dev/spfx/copilot/access-data), which maps `value` rows to `Id`, `Title`, and `ItemCount`.
23
+
24
+ `scripts/import-synthetic-capture.mjs` reconstructs this shape from its allowlist. It reads at most 1 MB plus one byte and rejects oversized input before parsing. It never copies an input object wholesale. On success, it prints a field-level contract diff with retained allowlisted fields and counts of unrecognized response fields stripped; it does not print input values or unrecognized field names. Request headers are reported as ignored without exposing their contents. Unknown fields and headers are discarded. It rejects non-synthetic sources, verifies with `git check-ignore --verbose` that repository `.gitignore` rules exclude both the final destination and its randomly named temporary file before writing, and rejects machine-wide or `.git/info/exclude` rules as substitutes. It rejects symlinked destination directories and output files, then atomically writes below `.spfx-workbench/captures/` without imposing a file-mode policy. In a consumer project, this capture directory belongs to that project and is also the replay directory used by the CLI.
25
+
26
+ ## Data boundary
27
+
28
+ `fixtures/library-items.synthetic.json` is a small, invented example contract and is the only mock payload committed. Local replay captures are ignored by Git. No cookie, authorization header, request digest, body field outside the allowlist, or tenant URL is accepted into the replay file. The synthetic marker is an operator assertion, not a content scanner; never use this import command for tenant data.
29
+
30
+ The Vite dev and preview middleware serves either the ignored local capture or the committed example from `GET /__spfx_workbench/api/library-items`. It applies `$select` projection and `$top` truncation deterministically, rejects unsupported query options with a 400 response, and returns a source header so the UI can show which data it served. It does not forward requests. See [Microsoft’s SPFx SharePoint REST example](https://learn.microsoft.com/en-us/sharepoint/dev/spfx/copilot/get-started/connect-to-sharepoint-data#show-the-items-in-a-list) for the selected fields and fallback from `Title` to `FileLeafRef`.
31
+
32
+ ## Whole-page tenant capture and offline replay
33
+
34
+ The local editor toolbox contains the component under development and a deterministic document library fixture. It does not load or imitate SharePoint built-in web parts. OOTB parts work when SharePoint loads them in the real host.
35
+
36
+ The installed `spfx-workbench-capture --watch --page <url>` command captures the whole page, including web parts and extensions. Add `--tenant <name>` to load the shared per-tenant state from the OS home directory, or pass `--storage-state <path>` for a separate file. The `@spfx-fast/spfx-workbench` package also provides `spfx-workbench-auth login|refresh|check` and exports `@spfx-fast/spfx-workbench/auth` for project code; see [the browser workflow](AGENT-BROWSER-WORKFLOW.md). During capture it atomically refreshes `.spfx-workbench/captures/tenant-live.json` as responses arrive; component replay reads this live snapshot first. Before replacing an existing `tenant.har`, capture saves it as a timestamped `tenant-archive-*.har`; after a successful capture it archives the new HAR too. The current HAR remains the latest capture, the archives stay in the consumer’s ignored capture directory until removed, and the live snapshot is removed when capture ends. It also writes a capture manifest with hash, timestamps, runtime/browser versions, viewport, and request counts, plus a Chromium CDP initiator trace for fetch/XHR callsites. These sidecars and the HAR stay in `.spfx-workbench/captures/`; add that path to the consumer repository's `.gitignore` first. The HAR contains full request/response headers and bodies. `--duration <seconds>` ends a capture 1–3600 seconds after page navigation and an edit-mode attempt; `--once` captures for four seconds. The optional `--cdp-endpoint http://127.0.0.1:9222` path can use an already signed-in local Chromium session. It writes target-scoped state to the consumer capture directory and remains separate from the reusable per-tenant state. The shared auth CLI never automates sign-in; `login --fresh` waits for the user to complete it in a visible browser and writes state only after a current-user check passes.
37
+
38
+ `spfx-workbench-replay --capture <tenant.har>` opens the first recorded HTML document using Playwright's HAR route. It blocks service workers because Playwright cannot intercept their requests from HAR. Replay automatically loads timestamped `tenant-archive-*.har` files beside the primary capture, oldest first. The primary HAR has highest priority; explicit `--fallback-capture <cache.har>` files are checked after the automatic archive and before the primary. Each response still comes only from local HAR files. Recorded responses, including a recorded successful `POST /_api/contextinfo` response, replay from the HAR. If that response is absent from every file, replay may return a fixed synthetic contextinfo response only for the replayed SharePoint origin and site path so the page can finish booting. This is not a captured or server-issued request digest and is not valid for SharePoint writes; every request outside the HAR files still stays offline and aborts, including cross-origin contextinfo requests. Microsoft describes request digests as opaque server-generated tokens used for REST writes and expiring after a server-configured period ([`SPHttpClient`](https://learn.microsoft.com/en-us/javascript/api/sp-http-base/sphttpclient?view=sp-typescript-latest), [`IDigestCache`](https://learn.microsoft.com/en-us/javascript/api/sp-http-base/idigestcache?view=sp-typescript-latest)). The JSON result reports response status counts, failed request method/resource type, origin and path without query values, query option names, page errors, canvas/webpart counts, and viewport overflow. Playwright documents that routing disables the browser HTTP cache; the HAR files supply the cached responses. `spfx-workbench-capture --diff --before <before.har> --after <after.har>` compares repeated method/URL calls in sequence and returns a compact summary of new, removed, and changed calls, with JSON changed paths and byte counts. Add `--values` for bounded before/after values at changed paths and compact values for added/removed calls. Use `--raw-values` for original request/response body text, capped at 1,000 characters per body. See the [Playwright BrowserContext HAR API](https://playwright.dev/docs/api/class-browsercontext#browser-context-route-from-har).
39
+
40
+ To map what the page called before replay, run `spfx-workbench-capture --summary --capture <tenant.har> --initiators <tenant-initiators.json> --no-values`. It lists fetch/XHR calls in capture order, including repeat numbers, resource type, status, request/response byte counts, and JSON body shapes. `apiReview.routes` groups SharePoint REST method/path pairs, redacts function arguments, tenant/site names, drive IDs, and item IDs, records the first fetch/XHR sequence, and marks each pair `unreviewed`; this is a source-review queue, not a claim that routes are undocumented. When a CDP trace is supplied, route entries also show matched initiator calls and compact caller evidence (script filename, function, line, and count); origins and query strings are omitted. A stack frame identifies the browser callsite, not necessarily the web part. To track route families across time, add `--baseline <earlier.har>` to compare the current summary with an earlier dated capture. `apiReview.evolution.newSinceBaseline` lists new route families to source-review; `baselineNotObserved` lists routes absent from this capture; `shared` reports current and baseline call counts. A newly seen route is not proof of an undocumented API, and a route missing from one page capture is not proof that SharePoint removed it. Review initiators and response shapes to distinguish reusable component data from page chrome, telemetry, or editor plumbing. Add `--values` to include bounded input/output values; each JSON value is capped at 512 bytes with a short preview when larger. `--raw-values` includes up to 1,000 characters from each request and response body. The `--diff` report compares additions, removals, changed request/response paths, and the first changed API-route position. For each unreviewed method/path pair, check Microsoft Learn and protocol references, compare multiple captures, record its purpose as documented, observed, inferred, or unknown, then implement useful offline behavior or retain it as captured-only replay. “Not found in checked sources” is not proof that an API is undocumented. Retain one dated snapshot per capture; SharePoint Online changes independently of this package. The auto-refreshed live snapshot contains fetch/XHR responses needed for component replay; the final HAR retains all browser resources for full-page offline replay. The current dated observations are in [the 2026-11-15 edit-mode behavior snapshot](sharepoint-behavior-snapshot-2026-11-15-1455Z.md); it records ordered calls and source confidence, not a permanent SharePoint contract.
41
+
42
+ HAR and storage-state files contain tenant content and authentication material; keep them local under the Git-ignored capture directory. The extracted state is scoped to the requested SharePoint origin, but its cookie and localStorage values remain credentials. The command imposes no file-mode policy. The local metadata-only trace endpoint was removed because it duplicated observability while discarding the data needed for replay.
43
+
44
+ ## Consumer component file boundary
45
+
46
+ The consumer CLI accepts one component file below the consuming project root. It resolves the real path before loading it, then checks every Vite `/@fs/` request against the canonical Vite allow roots before Vite's internal file middleware. This additional check matters because the installed Vite 8.3.8 `server.fs.allow` implementation compares path strings and does not resolve symlinks. Vite documents that middleware registered directly from `configureServer` runs before its internal middleware ([Vite plugin API](https://vite.dev/guide/api-plugin)). A temporary-consumer regression smoke verifies that both a direct external file request and a consumer-local symlink to an external module receive 403 and expose no file content.
47
+
48
+ ## Simulator context and captured API replay
49
+
50
+ The consumer wrapper supplies a fixed `SimulatorContext`: `domElement`, `manifest`, edit `displayMode`, `isServedFromLocalhost`, no Teams SDK, `pageContext.web/site/user`, stable `instanceId`, and `spHttpClient.get`/`post`. Class-based web parts invoke `onInit`, `render`, `onAfterResize`, and `onDispose`. Common public SPFx runtime imports used by generated React web parts resolve to lightweight simulator shims. The preview resolves `localizedResources` from `config/config.json` to the `en-us` file and falls back from the generated `lib` path to its matching `src` file before Heft runs. This is not the actual SPFx runtime or SharePoint host. The doctor reports detected lifecycle hooks and SDK/context gaps. The simulator does not create SharePoint's service scope, property pane, or display-mode host behavior. AAD, Graph, Teams SDK methods, and other service-scope clients are unsupported. Context coverage is derived from pinned SPFx 1.24.1 declarations and remains unknown for other releases. `SPHttpClient` follows [`@microsoft/sp-http-base` 1.24.1](https://registry.npmjs.org/@microsoft/sp-http-base/-/sp-http-base-1.24.1.tgz); configuration flags and transport behavior are not simulated. HTTP(S) `/_api/` GETs replay by API path and sorted query pairs. Captured read-only POSTs replay for `SiteUserInfoList/GetItems`, `GetList(...)/RenderListDataAsStream`, and `GetList(...)/RenderExtendedListFormData(...)`; they match the canonical JSON body too. Microsoft documents `RenderListDataAsStream`; other routes remain capture-derived. Host and site prefix do not affect matching. Repeated matches replay in capture order. Captured status, body, and usable headers return locally; `Set-Cookie` and transport headers are excluded. No request leaves the local server or mutates SharePoint. GET misses use documented deterministic list routes or return 404. POST options are limited, and other methods or unsupported POSTs are rejected. Context values are synthetic placeholders. A props file cannot override `context`; unsupported reads and mutations fail with a diagnostic.
51
+
52
+ The synthetic component API importer remains a separate, narrow path for explicitly synthetic list-item fixtures. The component simulator also replays matching GET and allowlisted POST responses directly from the whole-page HAR without rewriting or sanitizing the capture.
@@ -0,0 +1,67 @@
1
+ # SharePoint behavior snapshot — 2026-11-15 14:55 UTC
2
+
3
+ This is a dated observation from one private development tenant. It records current behavior, not a stable SharePoint contract. Compare future captures against this snapshot and keep each capture's HAR, initiator trace, and generated summary under the consumer's Git-ignored capture directory.
4
+
5
+ ## Capture identity
6
+
7
+ - Captured 2026-11-15 14:55:23–14:56:31 UTC; SHA-256 `d8c1415aea868b8dfbbd124a7db782fb8f4eafb813bdd169bced21218e23651f`.
8
+ - Playwright 1.65.1, Chromium 159.0.8154.6, Node 22.22.1, macOS arm64; viewport 1280×720.
9
+ - `editModeEntered: true`; 1,477 browser requests, 1,036 fetch/XHR calls, 73 SharePoint `/_api/` calls across 26 method/path families.
10
+ - CDP recorded 116 fetch/XHR initiators. All 73 SharePoint REST calls matched a script frame. The other 963 fetch/XHR calls are not SharePoint REST families.
11
+ - The recorder entered edit mode and did not change page controls or publish. SharePoint sent one successful `SavePageCoAuth` request while the editor was open. No page readback followed; server-side page mutation status is unknown.
12
+ - The earlier 10:52 UTC view-mode capture remains a separate historical capture. Entering edit mode changes the call sequence and adds collaboration and list-rendering calls.
13
+
14
+ The API sequence below is the first appearance among fetch/XHR calls, not response-completion order. Repeated calls are grouped by method and route; concurrent calls can interleave. The `tenant-summary-2026-11-15T1455Z.json` artifact contains the shape-only ordered calls and matched initiator sources. The corresponding HAR retains the full request/response bodies locally. Do not treat every SharePoint REST call as a web-part call: editor, navigation, catalog, telemetry, and collaboration traffic is included.
15
+
16
+ ## Ordered SharePoint REST route families
17
+
18
+ Identifiers, tenant/site prefixes, folder arguments, drive IDs, and item IDs are redacted below. Purposes are marked **documented**, **observed**, **inferred**, or **unknown**. “No exact public endpoint reference found” means only that the Microsoft Learn sources checked did not document that exact route; it does not prove the route is undocumented.
19
+
20
+ | First API call | Calls | Method and route | What the capture shows | Evidence status |
21
+ |---:|---:|---|---|---|
22
+ | 3 | 1 | `GET SP.Web.GetContextWebThemeData` | Theme/context payload in the `d` envelope. | Observed response; purpose inferred; exact route contract not found. |
23
+ | 4 | 1 | `GET Microsoft.SharePoint.Portal.SuiteNavData.GetSuiteNavData` | Suite navigation response with an OData `value` array. | Observed response; purpose inferred; internal route. |
24
+ | 6 | 35 | `POST web/GetClientSideComponents` | Component metadata, primarily `Library` manifests. The 35 responses contain 2,486 library rows. | Observed schema. Microsoft Dev Proxy SPFx guidance names this workbench endpoint, but does not specify its response contract. |
25
+ | 18 | 9 | `POST SP.UserProfiles.PersonalCache/ReadCacheOrCreate2` | Request has `folderPath`, `requiredCacheKeys`, and `createIfMissing`; responses contain cache names, values, hashes, and versions. | Observed schema; cache semantics unknown; internal route. |
26
+ | 29 | 2 | `POST sitepages/pages/feed` | Request has `metadataFilter` and `languageOverride`; response contains `value`. | Observed schema; page-feed purpose inferred; internal route. |
27
+ | 30 | 1 | `GET Site/RestrictedAccessControlGroupsEnforcedOnSite` | Site restriction state in the `d` envelope. | Observed response; purpose inferred. |
28
+ | 35 | 1 | `GET Web` | Web properties in the `d` envelope. | SharePoint REST resource; observed. |
29
+ | 36 | 1 | `GET SPHSite/Details` | OData response contains `@odata.context` and `@odata.null`. | Observed response; purpose unknown. |
30
+ | 37 | 2 | `GET web` | Web properties in the `d` envelope. | SharePoint REST resource; observed. |
31
+ | 40 | 1 | `GET EE/FullDashboardContent` | Dashboard response includes canvas content, dashboard IDs/URL, extra components, and personalization data. | Observed schema; dashboard purpose inferred; exact route contract not found. |
32
+ | 42 | 1 | `GET Site` | Site properties in the `d` envelope. | SharePoint REST resource; observed. |
33
+ | 43 | 2 | `GET web/GetFolderByServerRelativeUrl({argument})/Files` | File collections for two folders. | Documented SharePoint REST resource; observed. |
34
+ | 58 | 1 | `POST sitepages/pages({argument})/startCoAuth` | Request includes authoring schema versions and editor flags; response includes page fields. | Observed schema; collaboration purpose inferred; internal route. |
35
+ | 60 | 1 | `GET v2.1/sites/{site}` | Site metadata response. | Observed response; exact public endpoint contract not found. |
36
+ | 61 | 1 | `POST web/SiteUserInfoList/GetItems` | Request contains a `query`; response returns user-info rows. | Observed schema; exact endpoint reference not found. |
37
+ | 62 | 1 | `GET v2.1/billingPolicies` | Billing-policy collection. | Observed response; exact public endpoint contract not found. |
38
+ | 68 | 1 | `POST v2.1/drives/{driveId}/items/{itemId}/opStream/snapshots/trees/latest` | Collaboration snapshot/tree request; response body was empty. | Observed call; purpose inferred; internal route. |
39
+ | 74 | 2 | `POST v2.1/drives/{driveId}/items/{itemId}/opStream` | Collaboration operation responses include `value`; one includes `sequenceNumber` and `op`. | Observed schema; collaboration purpose inferred; internal route. |
40
+ | 76 | 1 | `POST web/GetClientSideComponentsByComponentType({argument})` | Typed catalog response: 81 `WebPart`, 301 `Library`, and 23 `AdaptiveCardExtension` rows. | Observed schema; exact endpoint contract not found. |
41
+ | 80 | 1 | `POST v2.1/drives/{driveId}/items/{itemId}/opStream/joinSession` | Response includes session URLs, IDs, and a socket token; values remain in the ignored HAR only. | Observed schema; collaboration purpose inferred; internal route. |
42
+ | 83 | 2 | `POST web/GetList({argument})/RenderListDataAsStream` | One response contains list rows, schema, view, and templates; the other contains client-form rendering metadata. | Documented by Microsoft; observed in this capture. |
43
+ | 97 | 1 | `POST web/GetList({argument})/RenderExtendedListFormData({argument})` | Form-data response in the `d` envelope. | Observed response; exact route contract not found. |
44
+ | 242 | 1 | `POST web/ActivityLogger/LogActivity` | Request fields describe an activity, list, item, resource URL, and extra properties; response status 204. | Observed schema; telemetry purpose inferred; internal route. |
45
+ | 244 | 1 | `POST sitepages/pages({argument})/SavePageCoAuth` | Request includes page canvas/layout and collaboration state; response status 200. | Observed; mutation-capable internal route. No readback was performed. |
46
+ | 1029 | 1 | `POST sitepages/pages({argument})/ExtendSessionCoAuth` | Request includes authoring metadata and connectivity reason; response contains collaboration flags. | Observed schema; session keepalive purpose inferred; internal route. |
47
+ | 1033 | 1 | `POST v2.1/drives/{driveId}/items/{itemId}/opStream/snapshots/snapshot` | Request includes `entries`, `message`, `sequenceNumber`, and `type`; response includes ID and sequence number. | Observed schema; collaboration purpose inferred; internal route. |
48
+
49
+ All 73 calls returned 200 except the single activity-log call, which returned 204. The API summary can join the route families to their captured script frames:
50
+
51
+ ```sh
52
+ npx spfx-workbench-capture --summary \
53
+ --capture .spfx-workbench/captures/tenant.har \
54
+ --baseline .spfx-workbench/captures/<earlier-dated-capture>.har \
55
+ --initiators .spfx-workbench/captures/tenant-initiators.json \
56
+ --no-values
57
+ ```
58
+
59
+ The summary masks route arguments and records only the first script frame's file name, function name, line, and count. It omits query strings and origins from callsite evidence. With `--baseline`, `apiReview.evolution.newSinceBaseline` identifies newly observed route families to source-review, `baselineNotObserved` records routes absent from this capture, and `shared` gives call counts across both captures. New observation does not prove an endpoint undocumented; absence from one page capture does not mean SharePoint removed it. The full local trace retains call frames for follow-up. Matching a frame to a web part still needs source-map or module inspection; a stack frame alone does not prove a component caused the request.
60
+
61
+ ## Picker catalog evidence
62
+
63
+ `GetClientSideComponentsByComponentType` is required to observe web parts in this capture. The older extractor inspected only `GetClientSideComponents`, whose responses here contain library manifests. The capture now reads both endpoints, parses base64-encoded HAR response bodies, and writes only `WebPart` manifest names into the ignored tenant picker catalog. It found 81 web-part names; the current merged picker catalog contains 118 entries. The 301 libraries and 23 Adaptive Card Extensions from the typed response are not added as web parts.
64
+
65
+ This is evidence from one tenant/page and current date. It is not a complete Microsoft web-part catalog; locally developed components still appear only when their manifests are present in the consuming project. The SharePoint Framework workbench endpoint is referenced by [Microsoft's Dev Proxy guidance](https://learn.microsoft.com/en-us/microsoft-cloud/dev/dev-proxy/how-to/use-dev-proxy-with-spfx#configure-dev-proxy-to-not-intercept-sharepoint-framework-workbench-requests). That reference warns that the endpoint is needed to load web parts, but does not publish its request/response schema. The captured `RenderListDataAsStream` call is covered by [Microsoft's SharePoint REST list operations](https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/working-with-lists-and-list-items-with-rest).
66
+
67
+ SharePoint Online changes independently. Capture each relevant release/page state, compare the ordered call and response shapes, verify exact public sources, and keep route purposes marked as observed, inferred, unknown, or documented. Do not label an API undocumented solely because an exact route was absent from the sources checked.
@@ -0,0 +1,23 @@
1
+ {
2
+ "format": "spfx-workbench-capture/v1",
3
+ "source": "synthetic",
4
+ "request": {
5
+ "method": "GET",
6
+ "route": "sp-rest-library-items",
7
+ "query": {
8
+ "$select": "Id,Title,FileLeafRef,Modified",
9
+ "$top": "25"
10
+ }
11
+ },
12
+ "response": {
13
+ "status": 200,
14
+ "body": {
15
+ "value": [
16
+ { "Id": 101, "Title": "Quarterly planning", "FileLeafRef": "Quarterly-planning.docx", "Modified": "2026-11-13T10:42:00Z" },
17
+ { "Id": 102, "Title": "Team onboarding", "FileLeafRef": "Team-onboarding.aspx", "Modified": "2026-11-12T15:18:00Z" },
18
+ { "Id": 103, "Title": "Launch checklist", "FileLeafRef": "Launch-checklist.xlsx", "Modified": "2026-11-12T09:00:00Z" },
19
+ { "Id": 104, "Title": "Design review", "FileLeafRef": "Design-review.pptx", "Modified": "2026-11-10T16:30:00Z" }
20
+ ]
21
+ }
22
+ }
23
+ }
package/index.html ADDED
@@ -0,0 +1,13 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
+ <meta name="theme-color" content="#f6f8fb" />
7
+ <title>SPFx Workbench</title>
8
+ </head>
9
+ <body>
10
+ <div id="root"></div>
11
+ <script type="module" src="/src/main.jsx"></script>
12
+ </body>
13
+ </html>
package/package.json CHANGED
@@ -1,6 +1,60 @@
1
1
  {
2
2
  "name": "@spfx-fast/spfx-workbench",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "publishConfig": {
5
+ "access": "public"
6
+ },
7
+ "type": "module",
8
+ "bin": {
9
+ "spfx-workbench": "bin/spfx-workbench.mjs",
10
+ "spfx-workbench-capture": "bin/spfx-workbench-capture.mjs",
11
+ "spfx-workbench-replay": "bin/spfx-workbench-replay.mjs",
12
+ "spfx-workbench-auth": "bin/spfx-workbench-auth.mjs",
13
+ "spfx-workbench-doctor": "bin/spfx-workbench-doctor.mjs",
14
+ "spfx-workbench-heft-target": "bin/spfx-workbench-heft-target.mjs",
15
+ "spfx-workbench-debug": "bin/spfx-workbench-debug.mjs"
16
+ },
17
+ "exports": {
18
+ "./auth": "./src/auth-state.mjs"
19
+ },
20
+ "files": [
21
+ "bin/",
22
+ "docs/mock-data-and-capture.md",
23
+ "docs/sharepoint-behavior-snapshot-2026-11-15-1455Z.md",
24
+ "fixtures/",
25
+ "index.html",
26
+ "LICENSE",
27
+ "README.md",
28
+ "scripts/",
29
+ "src/",
30
+ "vite.config.js"
31
+ ],
32
+ "scripts": {
33
+ "dev": "vite --host 127.0.0.1 --port 4173 --strictPort",
34
+ "build": "vite build",
35
+ "test": "node tests/consumer-loader-smoke.mjs && node tests/check-cdp-auth-capture.mjs && node tests/check-sharepoint-har-replay.mjs",
36
+ "check:local": "npm run build && npm test && npm run benchmark:consumer-hmr && npm run check:tarball",
37
+ "check:browser-hmr": "node tests/check-browser-hmr.mjs",
38
+ "check:responsive": "node tests/check-responsive-layouts.mjs",
39
+ "check:release": "npm run check:local && npm run check:browser-hmr && npm run check:responsive",
40
+ "preview": "vite preview --host 127.0.0.1 --port 4174 --strictPort",
41
+ "sharepoint:target": "node scripts/resolve-serve-target.mjs",
42
+ "capture:synthetic": "node scripts/import-synthetic-capture.mjs",
43
+ "benchmark:mock-api": "node scripts/benchmark-mock-api.mjs",
44
+ "benchmark:capture-import": "node scripts/benchmark-capture-import.mjs",
45
+ "benchmark:consumer-hmr": "node scripts/benchmark-consumer-hmr.mjs",
46
+ "check:tarball": "node scripts/check-tarball-install.mjs",
47
+ "check:ide": "npm run check:package --prefix packages/ide"
48
+ },
49
+ "dependencies": {
50
+ "@vitejs/plugin-react": "6.3.0",
51
+ "playwright-core": "1.65.1",
52
+ "react": "18.3.1",
53
+ "react-dom": "18.3.1",
54
+ "vite": "8.3.8"
55
+ },
56
+ "engines": {
57
+ "node": "^20.19.0 || >=22.12.0"
58
+ },
59
+ "license": "MIT"
60
+ }
@@ -0,0 +1,50 @@
1
+ import { mkdtemp, rm, writeFile } from 'node:fs/promises';
2
+ import { spawnSync } from 'node:child_process';
3
+ import { tmpdir } from 'node:os';
4
+ import { dirname, resolve } from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+
7
+ const args = process.argv.slice(2);
8
+ const valueAfter = (flag, fallback) => {
9
+ const index = args.indexOf(flag);
10
+ return index < 0 ? fallback : args[index + 1];
11
+ };
12
+ const samples = Number(valueAfter('--samples', '5'));
13
+ const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
14
+ const importer = resolve(packageRoot, 'scripts/import-synthetic-capture.mjs');
15
+ const fixture = resolve(packageRoot, 'fixtures/library-items.synthetic.json');
16
+
17
+ if (!Number.isInteger(samples) || samples < 1 || samples > 100) {
18
+ process.stderr.write('--samples must be an integer from 1 to 100.\n');
19
+ process.exitCode = 2;
20
+ } else {
21
+ try {
22
+ const timings = [];
23
+ for (let index = 0; index < samples; index += 1) {
24
+ const consumer = await mkdtemp(resolve(tmpdir(), 'spfx-capture-benchmark-'));
25
+ try {
26
+ await writeFile(resolve(consumer, '.gitignore'), '.spfx-workbench/captures/\n');
27
+ const initialized = spawnSync('git', ['init', '-q'], { cwd: consumer, stdio: 'ignore' });
28
+ if (initialized.status !== 0) throw new Error('Could not initialize a temporary Git consumer.');
29
+ const start = performance.now();
30
+ const result = spawnSync(process.execPath, [importer, '--input', fixture], { cwd: consumer, stdio: 'ignore' });
31
+ const elapsed = performance.now() - start;
32
+ if (result.status !== 0) throw new Error('Synthetic capture import failed in the temporary consumer.');
33
+ timings.push(elapsed);
34
+ } finally {
35
+ await rm(consumer, { recursive: true, force: true });
36
+ }
37
+ }
38
+ timings.sort((a, b) => a - b);
39
+ const percentile = (p) => timings[Math.max(0, Math.ceil(p * timings.length) - 1)];
40
+ process.stdout.write(`${JSON.stringify({
41
+ kind: 'local synthetic capture import only', samples,
42
+ environment: { node: process.version, platform: process.platform, architecture: process.arch },
43
+ includes: 'Node process startup, contract validation, field diff, Git ignore check, and local file write',
44
+ latencyMs: { min: +timings[0].toFixed(1), median: +percentile(0.5).toFixed(1), p95: +percentile(0.95).toFixed(1), max: +timings.at(-1).toFixed(1) },
45
+ }, null, 2)}\n`);
46
+ } catch (error) {
47
+ process.stderr.write(`Capture import benchmark failed: ${error.message}\n`);
48
+ process.exitCode = 1;
49
+ }
50
+ }