Merge branch 'master' into sheetalnair/fix-text-outline

Author: SheetalNair

.claude/settings.json

@@ -0,0 +1,27 @@
+{
+  "permissions": {
+    "deny": [
+      "Bash(npm install *)"
+    ],
+    "allow": [
+      "Bash(rushx build *)",
+      "Bash(rushx test *)",
+      "Bash(rushx lint *)",
+      "Bash(rushx docs *)",
+      "Bash(rushx extract-api)",
+      "Bash(rushx clean)",
+      "Bash(rushx cover)",
+      "Bash(rush build)",
+      "Bash(rush install)",
+      "Bash(rush extract-api)",
+      "Bash(rush lint)",
+      "Bash(rush change)",
+      "Bash(rush clean)",
+      "Bash(rush cover)",
+      "Bash(rush test)",
+      "Bash(rush audit)",
+      "Bash(npm view *)",
+      "Bash(pnpm why *)"
+    ]
+  }
+}

.gitattributes

@@ -5,6 +5,7 @@
 # Ensure these file types use the correct OS specific line endings
 *.bat                                         eol=crlf
 *.sh                                          eol=lf
+*.api.md                                      eol=lf
 presentation/common/Ruleset.schema.json text  eol=lf
 *.snap                                        eol=lf
 

.github/agents/cve-audit.agent.md

@@ -35,7 +35,7 @@ rush install
 ```
 
 - **Do not create the security branch yet.** The branch name requires a CVE ID, which is only known after the audit in Step 1. Branch creation happens in Execution Flow Step 1b (after the audit).
-- For multiple CVEs, use the highest-severity CVE/GHSA ID for the branch name and include others in the commit/PR text. If severity is equal, use the first ID returned by `rush audit --json`.
+- For multiple CVEs, use the highest-severity CVE/GHSA ID for the branch name and include others in the commit/PR text. If severity is equal, use the first ID from the audit table output.
 
 ### Protected Branch Guard (Required)
 
@@ -79,14 +79,13 @@ rush change --bulk --message "" --bump-type none -b origin/<starting-branch>
 1. Audit — run on the starting branch before creating any branch or making any changes:
 
 ```bash
-rush audit --level high
-rush audit --json > /tmp/cve-audit-results.json
+rush audit
 ```
 
-Parse `/tmp/cve-audit-results.json` to extract CVE/GHSA IDs, severities, advisory URLs, and dependency paths. These values drive all subsequent steps (branch name, commit message, PR body, deferral issues).
+**Note:** `rush audit` internally invokes `rush-pnpm audit --audit-level high`. It does **not** accept `--level` or `--json` flags directly. Parse the table output to extract CVE/GHSA IDs, severities, advisory URLs, and dependency paths. Use `rush-pnpm why <package>` to investigate transitive dependency paths when the audit output shows truncated paths.
 
 **1b. Early exit if no High/Critical CVEs found:**
-If `rush audit --level high` reports zero High or Critical vulnerabilities — **stop here**. Do not create a branch. Do not run `rush update --full`. Report all-clear to the invoker.
+If `rush audit` reports zero High or Critical vulnerabilities — **stop here**. Do not create a branch. Do not run `rush update`. Report all-clear to the invoker.
 
 **1c. Create security branch (now that CVE ID is known):**
 ```bash
@@ -98,12 +97,21 @@ git rev-parse --verify security/<first-CVE-ID> >/dev/null 2>&1 \
 
 2. Fast-path auto updates — attempt before any manual changes:
 
+```bash
+rush update
+rush audit
+```
+
+   Start with `rush update` (without `--full`) — it is faster and less disruptive. Re-run the audit immediately. If High/Critical vulnerabilities are cleared, proceed to Step 4 (verify).
+
+   If High/Critical remain, escalate to a full re-resolve:
+
 ```bash
 rush update --full
-rush audit --level high
+rush audit
 ```
 
-   Re-run the audit immediately after `rush update --full`. If High/Critical vulnerabilities are cleared, proceed to Step 4 (verify) — no further manual changes are needed.
+   If still not cleared after `--full`, proceed to Step 3 for manual remediation.
 
 3. If High/Critical remain after step 2, remediate using the fix strategy defined in the `cve-remediation` skill:
 
@@ -117,7 +125,12 @@ rush audit --level high
 
 ```bash
 rush update
-rush audit --level high
+rush audit
+```
+
+   After audit confirms High/Critical are resolved, run build and test validation. If the invoker prefers to validate separately (e.g., in CI), commit after audit verification and note pending validation steps in the report.
+
+```bash
 rush build
 rush test
 ```
@@ -229,7 +242,7 @@ If not requested: stop after commit and final report (no push, no PR).
 ## Done Criteria
 
 - Critical/High vulnerabilities reduced or explicitly documented with rationale.
-- `rush audit --level high` rerun and reported.
+- `rush audit` rerun and reported.
 - `rush build` and `rush test` pass (or no new failures with clear disclosure).
 - `rush change` handled non-interactively (`--verify`; blank entry via `--bulk --message "" --bump-type none` only when required).
 - API impact checked with `rush extract-api` when relevant.

.github/agents/electron-version-bump.agent.md

@@ -115,7 +115,9 @@ grep -r '"electron":' --include='package.json' -l .
 
 Compare the results with the list above and include any additional files found.
 
-### Step 3: Review and apply breaking changes
+### Step 3: Review breaking changes and get approval
+
+**This step requires explicit invoker approval before proceeding to file modifications.**
 
 Fetch the Electron breaking changes documentation. Use the raw URL to avoid GitHub rate limiting:
 
@@ -144,10 +146,7 @@ grep -r "require(\"electron\")" --include='*.ts' --include='*.js' -l .
 For each breaking change listed in the Electron docs for the new major version:
 
 1. **Identify** whether the breaking change affects any API used in this codebase.
-2. **If affected**, apply the necessary code fix:
-   - Search the codebase for all usages of the affected API.
-   - Update the code to use the new API or pattern as prescribed by the Electron breaking changes doc.
-   - Ensure backward compatibility with the minimum supported Electron version (currently ^35.0.0) — use feature detection or version checks when the old API is removed and a polyfill is needed.
+2. **If affected**, describe the required code fix and which files need modification.
 3. **If not affected**, note it and move on.
 
 **Common breaking change categories to watch for:**
@@ -159,6 +158,24 @@ For each breaking change listed in the Electron docs for the new major version:
 - New required permissions or security policy changes
 - Deprecated APIs that are now removed
 
+#### Present findings and wait for approval
+
+After completing the analysis, present a summary table to the invoker:
+
+| Breaking change | Affected? | Proposed fix |
+| --- | --- | --- |
+| (change description) | Yes / No | (fix description or "N/A") |
+
+**STOP here and wait for the invoker's explicit go-ahead before making any file changes.** If the invoker requests modifications to the proposed approach, incorporate their feedback before proceeding.
+
+#### Apply breaking change fixes (after approval)
+
+Once approved, for each affected breaking change:
+
+- Search the codebase for all usages of the affected API.
+- Update the code to use the new API or pattern as prescribed by the Electron breaking changes doc.
+- Ensure backward compatibility with the minimum supported Electron version documented in docs/learning/SupportedPlatforms.md — use feature detection or version checks when the old API is removed and a polyfill is needed.
+
 If a breaking change requires a non-trivial migration (e.g., architectural changes), document the issue in the report. If triggered from a GitHub issue, add a comment to the issue describing the blocker and wait for guidance. Otherwise, ask the invoker before proceeding with the fix.
 
 ### Step 3.5: Update `@itwin/electron-authorization` if needed
@@ -290,10 +307,13 @@ gh pr create \
   --head electron-<NEW_MAJOR> \
   --title "Add support for Electron <NEW_MAJOR>" \
   --body "$(cat <<'EOF'
-Adds support for Electron <NEW_MAJOR>.
-
 ### Breaking changes review
-<Include the breaking changes assessment here — list each change with "affected" / "not affected" status>
+
+<Include the breaking changes assessment table from Step 3 here>
+
+### Notes
+
+<Include any relevant notes, e.g. unmet peer dependencies>
 
 See [Electron <NEW_MAJOR> release blog](https://www.electronjs.org/blog/electron-<NEW_MAJOR>-0) for details.
 EOF

.github/copilot-instructions.md

@@ -88,6 +88,8 @@ API changes require:
 
 All published packages use **lockstep versioning** (`prerelease-monorepo-lockStep` policy). Versions are automatically synchronized across packages - do NOT manually edit internal dependency versions in `package.json`.
 
+When generating a changelog non-interactively with `rush change`, always use bump type `"none"` in the generated change file. In this lockstep monorepo, version bumps are coordinated separately and changelog entries should not choose per-package bump types like `"patch"` or `"minor"`.
+
 ## Testing
 
 ### Mocha vs Vitest
@@ -183,6 +185,13 @@ Valid formats recognized by the ESLint rule:
 
 **Critical**: Always run `rush extract-api` and `rush change` before pushing - CI will fail otherwise.
 
+### Draft PR Descriptions
+
+When creating or updating a draft PR, always include a `## Validation` section in the PR description. Summarize any targeted verification steps you performed beyond what CI checks cover, and note any known pre-existing failures or warnings:
+
+- `Targeted verification:`
+- `Known baseline issues:`
+
 ## Build Tools
 
 TypeScript compilation outputs dual format: CJS in `lib/cjs/`, ESM in `lib/esm/`.

.github/hooks/itwinjs-core-agent-hooks.json

@@ -0,0 +1,21 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "type": "command",
+        "bash": "node .github/hooks/scripts/itwinjs-core-pre-tool-use.mjs",
+        "cwd": ".",
+        "timeoutSec": 30
+      }
+    ],
+    "postToolUse": [
+      {
+        "type": "command",
+        "bash": "node .github/hooks/scripts/itwinjs-core-post-tool-use.mjs",
+        "cwd": ".",
+        "timeoutSec": 10
+      }
+    ]
+  }
+}

.github/hooks/scripts/itwinjs-core-hook-utils.mjs

@@ -0,0 +1,102 @@
+export async function readHookInput() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+
+  const input = Buffer.concat(chunks).toString("utf8").trim();
+  if (!input) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(input);
+  } catch {
+    return {};
+  }
+}
+
+export function parseToolArgs(toolArgs) {
+  if (!toolArgs) {
+    return {};
+  }
+
+  if (typeof toolArgs === "object") {
+    return toolArgs;
+  }
+
+  if (typeof toolArgs === "string") {
+    try {
+      return JSON.parse(toolArgs);
+    } catch {
+      return { raw: toolArgs };
+    }
+  }
+
+  return {};
+}
+
+export function getBashCommand(input) {
+  const args = parseToolArgs(input.toolArgs);
+  return typeof args.command === "string" ? args.command : "";
+}
+
+export function isGitCommitCommand(command) {
+  return /\bgit\s+(?:-[^\s]+\s+)*commit\b/.test(command);
+}
+
+export function getChangedPathText(input) {
+  const args = parseToolArgs(input.toolArgs);
+  const directPath = args.file_path ?? args.path ?? "";
+  const summary = getPathSummary(args);
+
+  try {
+    const summaryText = Object.keys(summary).length > 0 ? JSON.stringify(summary) : "";
+    return summaryText ? `${directPath}\n${summaryText}` : `${directPath}\n`;
+  } catch {
+    return `${directPath}\n`;
+  }
+}
+
+export function getChangedPaths(input) {
+  const args = parseToolArgs(input.toolArgs);
+  const paths = [];
+  for (const value of [args.file_path, args.path, args.old_path, args.new_path, args.paths, args.files]) {
+    if (typeof value === "string" && value.length > 0) {
+      paths.push(value);
+    } else if (Array.isArray(value)) {
+      paths.push(...value.filter((entry) => typeof entry === "string" && entry.length > 0));
+    }
+  }
+
+  return paths;
+}
+
+export function isPackageJsonPath(path) {
+  return String(path).split(/[\\/]/).pop() === "package.json";
+}
+
+export function isWriteLikeTool(toolName) {
+  return /^(edit|create|write|apply_patch)$/i.test(String(toolName ?? ""));
+}
+
+export function compactJson(value) {
+  return `${JSON.stringify(value)}\n`;
+}
+
+function getPathSummary(args) {
+  const summary = {};
+  for (const key of ["file_path", "path", "old_path", "new_path", "paths", "files"]) {
+    const value = args?.[key];
+    if (typeof value === "string" && value.length > 0) {
+      summary[key] = value;
+    } else if (Array.isArray(value)) {
+      const paths = value.filter((entry) => typeof entry === "string" && entry.length > 0);
+      if (paths.length > 0) {
+        summary[key] = paths;
+      }
+    }
+  }
+
+  return summary;
+}

.github/hooks/scripts/itwinjs-core-post-tool-use.mjs

@@ -0,0 +1,40 @@
+import {
+  getBashCommand,
+  getChangedPaths,
+  getChangedPathText,
+  isGitCommitCommand,
+  isPackageJsonPath,
+  isWriteLikeTool,
+  readHookInput,
+} from "./itwinjs-core-hook-utils.mjs";
+
+const input = await readHookInput();
+const messages = [];
+const isWriteLike = isWriteLikeTool(input.toolName);
+
+if (isWriteLike) {
+  const changedPaths = getChangedPaths(input);
+
+  if (changedPaths.some(isPackageJsonPath)) {
+    messages.push("[itwinjs] package.json changed - run rush update to sync pnpm-lock.yaml before committing.");
+  }
+
+  if (changedPaths.some((path) => path.includes("tsconfig")) || /tsconfig/i.test(getChangedPathText(input))) {
+    messages.push(
+      "[itwinjs] tsconfig changed - clean and rebuild to avoid stale lib/ artifacts: from the affected package directory run rushx clean && rushx build, or from the repo root use rush clean && rush build.",
+    );
+  }
+}
+
+if (String(input.toolName ?? "").toLowerCase() === "bash") {
+  const command = getBashCommand(input);
+  if (isGitCommitCommand(command)) {
+    messages.push(
+      "[itwinjs] Commit checklist: (1) any .ts files staged? -> rush lint from the repo root, or rushx lint from the affected package; (2) any @public/@beta symbol or TSDoc comment changed? -> rush extract-api + commit .api.md; (3) package.json dep changed? -> rush update committed; (4) changed a package with dependents? -> run downstream tests.",
+    );
+  }
+}
+
+if (messages.length > 0) {
+  process.stderr.write(`${messages.join("\n")}\n`);
+}