@jmruthers/pace-core 0.6.9 → 0.6.11

package/docs/troubleshooting/common-issues.md

@@ -321,7 +321,23 @@ export const MyComponent = ({ isOpen, data }: Props) => {
 2. **Call hooks in the same order** - Every render must call the same hooks in the same order
 3. **No early returns before hooks** - All hooks must be called before any conditional returns
 
-### Issue 8: PagePermissionGuard UI Issues
+### Issue 8: Login succeeds but redirect doesn't happen / form resets
+
+**Symptoms:** After entering valid credentials, the login button shows "Signing in…" then the form resets and you stay on the login page.
+
+**Root Cause:** Global auth gate or wrong routing pattern (e.g. wrapping the whole app in a component that redirects to `/login` when `!isAuthenticated`), which races with post-login context updates.
+
+**Solution:** See [Authentication — Critical: Auth routing pattern](../implementation-guides/authentication.md#critical-auth-routing-pattern) and [Redirect not happening after login](../implementation-guides/authentication.md#1-login-not-working). Use a single public `/login` route and wrap all other routes in **ProtectedRoute**; do not wrap `<Routes>` in a component that redirects unauthenticated users to `/login`.
+
+### Issue 9: Logout button does nothing (e.g. 403)
+
+**Symptoms:** Clicking logout has no effect; the UI still shows the user as logged in. Network tab may show `POST .../auth/v1/logout` returning 403.
+
+**Root Cause:** Server-side logout can fail (e.g. cookie/domain); without handling the error, local state stays "logged in".
+
+**Solution:** pace-core clears local user/session on signOut error and falls back to `signOut({ scope: 'local' })`, so the UI should still show logged out. See [Authentication — Logout does nothing / 403 on logout](../implementation-guides/authentication.md#4-logout-does-nothing--403-on-logout). If logout still fails, check cookie domain and CORS.
+
+### Issue 10: PagePermissionGuard UI Issues
 
 **Symptoms:**
 - Access Denied modal persists despite correct permissions

package/docs/troubleshooting/organisation-context-setup.md

@@ -305,6 +305,14 @@ The key is making sure the database has the organisation context functions and y
 3. **Use RLS policies correctly**: Policies should use `auth.uid()` and `organisation_id` columns directly
 4. **No manual context setting**: The secure client handles everything automatically
 
+### Super admin and "All Organizations"
+
+When the user is a **super admin** and no organisation is selected (e.g. "All Organizations"), the secure client from `useSecureSupabase()` is created with `organisationId = null` and `isSuperAdmin: true`. Only in that case may RPCs such as `data_rbac_roles_list` be called without org context (e.g. to load a user's event roles across all orgs). Consuming apps must use the same secure client from the hook so that `isSuperAdmin` is correctly resolved (via `useOrganisationSecurity()`); do not create a separate client or bypass the hook.
+
+### Org from URL (e.g. /users?org=scouts-victoria)
+
+When the app derives "current organisation" from the URL (or another source) but does not set pace-core's `selectedOrganisation`, the secure client may have `organisationId = null`. For **org-scoped table queries** (e.g. listing users in an org), either: (1) keep `selectedOrganisation` in sync with the URL so the secure client has the correct org context, or (2) use the secure client's `withContext({ organisationId: urlOrgId })` to obtain a client scoped to that org for the request. RPCs that accept explicit `p_organisation_id` use the parameter as the source of truth and do not require the header to match.
+
 ## ♿ Accessibility
 
 Organisation context setup doesn't directly impact accessibility, but ensure:

package/docs/troubleshooting/print-event-name-css-variable-analysis.md

@@ -0,0 +1,217 @@
+# Investigation: `--print-event-name` CSS Variable Not Updating From Default
+
+**Status:** Analysis complete. No code changes until root cause is confirmed.
+
+**Observed behaviour:** Event colours update when the user selects an event (or when "Apply Demo Palette" is used on Styles Showcase), but the text driven by `var(--print-event-name)` (e.g. in `h1::after`) stays as the default `"Event Names not long 2026"` instead of the selected event name (e.g. "Kangaree 2022", "Venture24").
+
+---
+
+## 1. What is failing
+
+- **Symptom:** The CSS custom property `--print-event-name` on `document.documentElement` either is never set to the selected event’s name, or is set and then removed/overwritten, so the UI always shows the default value from `core.css`.
+- **Where it’s consumed:** `packages/core/src/styles/core.css` (e.g. `h1::after { content: var(--print-event-name); }` in a screen-only block, and in print margin boxes).
+- **Default value:** `core.css` sets `--print-event-name: "Event Names not long 2026"` in `@layer base { * { ... } }`.
+
+---
+
+## 2. Data flow (verified in code)
+
+### 2.1 Who can set `--print-event-name`
+
+**Only** `applyPalette(palette, eventName)` in `packages/core/src/theming/runtime.ts` sets it, and **only when `eventName !== undefined`**:
+
+```ts
+if (eventName !== undefined) {
+  root.style.setProperty('--print-event-name', escapeCssCustomPropertyValue(eventName));
+}
+```
+
+So:
+
+- **useEventTheme** (auth mode): subscription calls `applyPalette(normalized, current.event_name ?? '')` → **sets** the variable when there is a selected event with `event_colours`.
+- **useEventTheme** (public mode): main effect calls `applyPalette(normalized, selectedEvent.event_name ?? '')` → **sets** the variable when `event` prop is provided.
+- **StylesShowcasePage** “Apply Demo Palette”: calls `applyPalette(palette)` with **one argument** → **does not set** `--print-event-name` (argument is `undefined`). Colour variables are overwritten; `--print-event-name` is left unchanged.
+
+So the variable is only written by useEventTheme (subscription or public-page effect). Styles Showcase never writes it.
+
+### 2.2 Who can remove `--print-event-name`
+
+**Only** `clearPalette()` in `packages/core/src/theming/runtime.ts` removes it:
+
+```ts
+root.style.removeProperty('--print-event-name');
+```
+
+Call sites:
+
+- **useEventTheme:** subscription when `!current?.event_colours` or when `!normalized`; main effect when on login route or (public mode) when `!selectedEvent` or `!normalized`.
+- **PaceLoginPage:** on mount and when pathname is login.
+- **StylesShowcasePage** “Reset to App Colors”: `resetToAppColors()` → `clearPalette()`.
+
+So the variable is removed only by those three. No other code removes it.
+
+### 2.3 Event data shape
+
+- **Event type** (`packages/core/src/types/event.ts`): `event_name: string` is required.
+- **EventService** RPC response and mapping (`EventService.ts`): `event_name` and `event_colours` are mapped onto the `Event` object.
+- **Header/ContextSelector:** calls `setSelectedEvent(fullEvent || event)` with full event objects from the service.
+
+So selected events used by useEventTheme should have `event_name` and `event_colours` when coming from the event list / RPC.
+
+### 2.4 Subscription flow (auth mode)
+
+- **PaceAppLayout** calls `useEventTheme()` (no `event` prop) → auth mode.
+- **Effect 1** (subscription): subscribes to `eventService`; callback `applyThemeFromService` runs on notify.
+- **EventService.setSelectedEvent(event)** → `this.notify()` → all subscribers run, including `applyThemeFromService`.
+- **applyThemeFromService:**  
+  `current = eventService.getSelectedEvent()` → if `current?.event_colours`, parses colours and calls `applyPalette(normalized, current.event_name ?? '')` → **should set** `--print-event-name`.
+
+So when the user selects an event in the header, the subscription should run and set the variable. Styles Showcase is under PaceAppLayout, so useEventTheme and the subscription are active on that page.
+
+---
+
+## 3. Why it can still show the default
+
+Only two mechanisms can leave the UI showing the default:
+
+1. **Variable never set**  
+   - Subscription never runs with a valid event (e.g. no event selected, or event without `event_colours` / parse failure).  
+   - Or useEventTheme never runs (e.g. wrong route/layout); **not** the case for Styles Showcase (it’s under PaceAppLayout).
+
+2. **Variable set then removed**  
+   - Something calls `clearPalette()` after the subscription (or public-page effect) has set `--print-event-name`.
+
+### 3.1 “Reset to App Colors” on Styles Showcase
+
+- **StylesShowcasePage** “Reset to App Colors” calls `clearPalette()`.
+- That **removes** `--print-event-name` (and colour variables).
+- After that, the default from `core.css` applies, so the UI shows `"Event Names not long 2026"`.
+- The subscription does **not** run again until the user changes the selected event (e.g. picks another event in the header).
+- So: **If the user clicks “Reset to App Colors”, the variable will show the default until they change the event again.** That matches “variable not updating from default” if they never change the event after Reset.
+
+### 3.2 “Apply Demo Palette” on Styles Showcase
+
+- “Apply Demo Palette” calls `applyPalette(demoPalette)` with **no second argument**.
+- So `eventName === undefined` → the `if (eventName !== undefined)` block is **skipped** → `--print-event-name` is **not** set (and not removed).
+- Colour variables are overwritten; `--print-event-name` is left as-is.
+- So:
+  - If the variable was already set (e.g. by subscription) → it stays set; event name still shows.
+  - If the variable was never set or was cleared (e.g. by Reset) → it stays at default; “Event Names not long 2026” still shows.
+
+So “Apply Demo Palette” alone does **not** fix or break the event name; it only explains why colours can change while the name stays default when the variable was never set or was cleared.
+
+### 3.3 Auth-mode main effect (current code)
+
+- In auth mode (`event === undefined`), the main effect in useEventTheme **returns immediately** and does **not** call `clearPalette()` or `applyPalette()`.
+- So the main effect in auth mode **does not** clear `--print-event-name` after the subscription sets it (this was the previous bug that was fixed).
+
+---
+
+## 4. Root cause summary (with certainty)
+
+**Proven:**
+
+1. **Only** `applyPalette(..., eventName)` with `eventName !== undefined` sets `--print-event-name`. So useEventTheme (subscription or public-page effect) is the only code that can set the current event name.
+2. **Only** `clearPalette()` removes it. So useEventTheme (no event / login / parse fail), PaceLoginPage, or Styles Showcase “Reset to App Colors” can clear it.
+3. **Styles Showcase “Apply Demo Palette”** never passes `eventName`, so it **never sets** (and never removes) `--print-event-name`. It only changes colour variables.
+4. **Styles Showcase “Reset to App Colors”** calls `clearPalette()` and **removes** `--print-event-name`, so the default appears and stays until the user changes the event again (which would re-run the subscription and set the variable again).
+
+**Two plausible root causes:**
+
+- **A) User clicked “Reset to App Colors”**  
+  Then `--print-event-name` is cleared. The default is shown and does not “update” until they select an event again (subscription then sets it). If they never change the event after Reset, the variable will stay at default.
+
+- **B) Variable never set in the first place**  
+  Subscription either never runs with a valid event (e.g. no event selected, or event without `event_colours`, or parse failure), or there is another caller that clears the variable after the subscription sets it (only clearPalette call sites above qualify; auth main effect no longer clears).
+
+To distinguish A vs B in practice: after selecting an event (e.g. “Kangaree 2022”), does the text next to the title ever show “Kangaree 2022”? If **yes**, then at some point the variable was set; if it later reverts to default without clicking “Reset to App Colors”, something else would be clearing it (no such path found in code). If **no** (it never shows the selected event name even before any Reset), then the subscription is not setting the variable (e.g. event missing `event_colours`/`event_name`, or parse failing, or subscription not running).
+
+---
+
+## 5. Patterns and anomalies
+
+1. **Asymmetry:** Colour variables are set by both useEventTheme and Styles Showcase “Apply Demo Palette”. `--print-event-name` is set **only** by useEventTheme (when `eventName` is passed). So any code path that applies a palette without passing the event name will update colours but not the event name.
+2. **Styles Showcase:** “Apply Demo Palette” is the only consumer call to `applyPalette` with a single argument. All useEventTheme call sites pass `event_name ?? ''`. So the “no eventName” path is effectively the Styles Showcase demo.
+3. **Single source of removal:** Every removal of `--print-event-name` goes through `clearPalette()`. So any unwanted reset to default implies a `clearPalette()` call (login, no event, parse fail, or “Reset to App Colors”).
+4. **Subscription vs main effect:** In auth mode, only the subscription applies/clears theme; the main effect no longer clears, so there is no “stale null” clear overwriting the subscription.
+
+---
+
+## 6. What to verify before changing code
+
+1. **Repro steps:**  
+   - Select an event (e.g. “Kangaree 2022”) and **do not** click “Reset to App Colors”.  
+   - Check whether the text next to the title (or in `h1::after`) ever shows “Kangaree 2022”.  
+   - If it never does, the subscription path is not setting the variable (event shape, parse, or subscription not running).  
+   - If it does, then click “Reset to App Colors” and confirm the text reverts to the default; that confirms Reset as the clear path.
+
+2. **DevTools:**  
+   - On `<html>`, inspect computed/style and see whether `--print-event-name` is present and what its value is after selecting an event and after “Reset to App Colors”.
+
+3. **Logging:**  
+   - Ensure `[event-theme-diagnostic]` logs in useEventTheme and EventService run when selecting an event and that they show a non-null event with `event_name` and `event_colours` when the variable is expected to be set.
+
+---
+
+## 7. References (file:line or symbol)
+
+| Item | Location |
+|------|----------|
+| Default `--print-event-name` | `packages/core/src/styles/core.css` (e.g. in `@layer base` under `*`) |
+| `h1::after` uses variable | `packages/core/src/styles/core.css` (screen-only block) |
+| Set variable when `eventName !== undefined` | `packages/core/src/theming/runtime.ts` `applyPalette` |
+| Remove variable | `packages/core/src/theming/runtime.ts` `clearPalette` |
+| useEventTheme subscription (auth) | `packages/core/src/hooks/useEventTheme.ts` (first `useEffect`) |
+| useEventTheme main effect (auth early return) | `packages/core/src/hooks/useEventTheme.ts` (second `useEffect`, `event === undefined` return) |
+| Styles Showcase applyPalette (one arg) | `src/pages/StylesShowcasePage.tsx` “Apply Demo Palette” handler |
+| Styles Showcase clearPalette | `src/pages/StylesShowcasePage.tsx` “Reset to App Colors” handler |
+| EventService.setSelectedEvent → notify | `packages/core/src/services/EventService.ts` |
+| BaseService.notify | `packages/core/src/services/base/BaseService.ts` |
+| Event type and RPC mapping (event_name, event_colours) | `packages/core/src/types/event.ts`, `EventService.ts` (e.g. EventRpcResponse and transformedEvents) |
+
+No fixes are proposed in this document; it is analysis only. Fixes should be applied only after the above checks confirm which of (A) or (B) is the actual root cause.
+
+---
+
+## 8. Diagnostic logging (investigation)
+
+Temporary `[print-event-name]` console logs were added (dev only) to trace the flow:
+
+- **runtime.ts**
+  - When `applyPalette` is called **with** `eventName`: logs that `--print-event-name` was set and the value.
+  - When `applyPalette` is called **without** `eventName`: logs that `--print-event-name` was not set.
+  - When `clearPalette` runs: logs that `--print-event-name` was removed.
+- **useEventTheme.ts**
+  - Every time the subscription runs: logs `hasEvent`, `event_id`, `event_name`, `hasEventColours`, and `willAction` (`applyPalette` vs `clearPalette`).
+  - When clearing due to parse failure: logs that parse returned null/undefined.
+
+**How to use:** Run the app in dev, open the console, filter by `[print-event-name]`. Then:
+
+1. Load a page (e.g. Super Admin Test). Note the first run: often `subscription ran` with `hasEvent: false` → `clearPalette removed`.
+2. Select an event from the header dropdown. You should see:
+   - `subscription ran` with `hasEvent: true`, `event_name: "…"`, `willAction: "applyPalette"`.
+   - `applyPalette set --print-event-name: "…"`.
+3. If you never see step 2 after selecting, the subscription is either not running on selection or `getSelectedEvent()` is null when it runs.
+4. If you see `applyPalette set` then later `clearPalette removed`, something is clearing the variable after it is set.
+5. If you see `subscription clearing: parseAndNormalizeEventColours returned null`, the event’s `event_colours` failed to parse and the subscription correctly clears.
+
+Remove or gate these logs once the root cause is fixed.
+
+---
+
+## 9. Root cause (confirmed)
+
+**Logs showed** that `applyPalette set --print-event-name` was called with the correct event names ("One Camp 2026", "Kangaree 2025", "GG Camp 2024"), but the UI still showed the default "Event Names not long 2026".
+
+**Cause:** In `core.css`, the default was set in the **`*` selector**:
+
+```css
+* {
+  --print-event-name: "Event Names not long 2026";
+  /* ... */
+}
+```
+
+That gives **every element** (body, main, h1, etc.) its own `--print-event-name` from the stylesheet. The runtime sets the variable only on **`<html>`** via inline style. When **`h1::after`** uses `var(--print-event-name)`, the value is resolved on **h1**; because h1 is matched by `*`, h1 has the variable set by the stylesheet to the default, so that value is used and the value on html is never seen.
+
+**Fix:** Define the print variables on **`:root` only** (so only the root has the default). Then when the runtime sets the variable on html, descendants have no competing rule and inherit the value from html. In `core.css`, the print variables were moved from the `*` block into a separate `:root { ... }` block.

package/eslint-config-pace-core.cjs

@@ -96,6 +96,10 @@ module.exports = [
       
       // Standard 5: Styling
       'pace-core-compliance/no-inline-styles': 'error',
+      'pace-core-compliance/no-typography-styling': 'error',
+      'pace-core-compliance/no-pace-core-style-override': 'warn',
+      'pace-core-compliance/prefer-semantic-html': 'warn',
+      'pace-core-compliance/no-nested-same-type-tags': 'error',
       
       // Standard 6: Security & RBAC
       'pace-core-compliance/no-direct-supabase-client': 'error',
@@ -106,6 +110,7 @@ module.exports = [
       'pace-core-compliance/rbac-use-resource-names-constants': 'error',
       'pace-core-compliance/no-rbac-wrapper-components': 'error',
       'pace-core-compliance/no-rbac-wrapper-functions': 'error',
+      'pace-core-compliance/require-derived-organisation-id': 'warn',
       
       // Standard 7: API & Tech Stack
       'pace-core-compliance/rpc-naming-pattern': 'warn',
@@ -122,6 +127,25 @@ module.exports = [
       }]
     }
   },
+  // Standard 3: Architecture - SRP proxies (source only; consuming app src/; exclude tests)
+  {
+    files: ['src/**/*.{ts,tsx}'],
+    ignores: [
+      '**/__tests__/**',
+      '**/*.{spec,test}.{ts,tsx}',
+      '**/fixtures/**',
+      '**/mocks/**',
+      '**/*.mock.{ts,tsx}',
+      '**/*.template.{ts,tsx}',
+    ],
+    rules: {
+      // Standard 3: SRP proxies (line limits + named exports) — single source
+      'max-lines': ['warn', { max: 1000 }],
+      'max-lines-per-function': ['warn', { max: 400 }],
+      'pace-core-compliance/max-named-exports': ['warn', { max: 10 }],
+      'complexity': ['warn', { max: 30 }],
+    }
+  },
   // Override for Edge Functions (Deno runtime)
   // Edge Functions run in Deno, not React, so they cannot use React hooks
   // They need direct Supabase client access and console.log for debugging

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.6.9",
+  "version": "0.6.11",
   "description": "React component library with Tailwind v4",
   "private": false,
   "publishConfig": {
@@ -78,7 +78,8 @@
     "./package.json": "./package.json",
     "./core-usage-manifest.json": "./core-usage-manifest.json",
     "./cursor-rules": "./cursor-rules",
-    "./scripts/install-cursor-rules": "./scripts/install-cursor-rules.cjs",
+    "./scripts/setup": "./scripts/setup.cjs",
+    "./scripts/validate": "./scripts/validate.cjs",
     "./source": {
       "import": "./src/index.ts",
       "default": "./src/index.ts"
@@ -159,8 +160,8 @@
     "build": "tsup && node scripts/build-css.js",
     "build:fast": "SKIP_CLEAN=true NODE_ENV=development tsup && node scripts/build-css.js",
     "build:watch": "tsup --watch",
-    "build:docs": "node scripts/build-docs-incremental.js",
-    "build:docs:force": "node scripts/build-docs-incremental.js --force",
+    "build:docs": "node scripts/build-docs.js",
+    "build:docs:force": "node scripts/build-docs.js --force",
     "build:all": "npm run build && npm run build:docs",
     "_comment_local_dev": "Local development utilities",
     "link": "npm run build && npm link",
@@ -170,15 +171,15 @@
     "validate:dependencies": "node scripts/validate-dependencies.cjs",
     "clean": "rimraf dist",
     "_comment_test": "Test suite with various configurations",
-    "test": "cross-env NODE_OPTIONS=\"--max-old-space-size=8192 --max-semi-space-size=128\" vitest run --config ../../vitest.config.ts",
-    "test:watch": "vitest --watch --config ../../vitest.config.ts",
-    "test:coverage": "cross-env NODE_OPTIONS=\"--max-old-space-size=8192 --max-semi-space-size=128\" vitest run --coverage --config ../../vitest.config.ts --reporter=dot",
-    "test:ui": "vitest --ui --config ../../vitest.config.ts",
-    "test:new": "cross-env NODE_OPTIONS=\"--max-old-space-size=8192 --max-semi-space-size=128\" vitest run --config vitest.new.config.ts",
-    "test:new:watch": "vitest --watch --config vitest.new.config.ts",
+    "test": "cross-env NODE_OPTIONS=\"--max-old-space-size=8192 --max-semi-space-size=128\" vitest run --config ../../vitest.config.ts --test-timeout=30000",
+    "test:watch": "vitest --watch --config ../../vitest.config.ts --test-timeout=30000",
+    "test:coverage": "cross-env NODE_OPTIONS=\"--max-old-space-size=8192 --max-semi-space-size=128\" vitest run --coverage --config ../../vitest.config.ts --reporter=dot --test-timeout=30000",
+    "test:ui": "vitest --ui --config ../../vitest.config.ts --test-timeout=30000",
+    "test:new": "cross-env NODE_OPTIONS=\"--max-old-space-size=8192 --max-semi-space-size=128\" vitest run --config vitest.new.config.ts --test-timeout=30000",
+    "test:new:watch": "vitest --watch --config vitest.new.config.ts --test-timeout=30000",
     "migrate-tests": "node scripts/migrate-tests.js",
-    "test:unit": "vitest src/**/*.test.{ts,tsx} --config ../../vitest.config.ts",
-    "test:integration": "vitest tests/integration --config ../../vitest.config.ts",
+    "test:unit": "vitest src/**/*.test.{ts,tsx} --config ../../vitest.config.ts --test-timeout=30000",
+    "test:integration": "vitest tests/integration --config ../../vitest.config.ts --test-timeout=30000",
     "_comment_quality": "Code quality and formatting checks",
     "lint": "eslint src --ext .ts,.tsx",
     "type-check": "tsc --noEmit",
@@ -193,14 +194,7 @@
     "pack:dry": "npm pack --dry-run",
     "publish:latest": "npm publish",
     "publish:test": "npm publish --tag beta",
-    "publish:dry-run": "npm publish --dry-run",
-    "_comment_docs": "Documentation generation and management",
-    "docs:generate": "node scripts/generate-docs.js generate",
-    "docs:update-index": "node scripts/generate-docs.js update-index",
-    "docs:generate-api": "node scripts/generate-docs.js generate-api",
-    "docs:all": "node scripts/generate-docs.js all",
-    "_comment_audit": "Audit tool for consuming apps",
-    "audit:pace-core": "node packages/core/audit-tool/index.cjs"
+    "publish:dry-run": "npm publish --dry-run"
   },
   "keywords": [
     "react",

package/scripts/build-docs.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+
+/**
+ * TypeDoc Build Script
+ * 
+ * Generates API documentation using TypeDoc with incremental builds.
+ * Only regenerates documentation when source files have changed,
+ * significantly speeding up the build process.
+ */
+
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { existsSync } from 'fs';
+
+// Import modules
+import { scanDirectory, getLatestSourceModTime, getLatestDocModTime } from './build-docs/file-utils.js';
+import { shouldSkipDueToCleanGitState, getGitStatus } from './build-docs/git-utils.js';
+import { getSourceFileHashes, hasSourceChanged, hashesMatch, getExistingDocHashes } from './build-docs/hash-utils.js';
+import { loadCache, saveCache, primeCacheFromExistingDocs } from './build-docs/cache-utils.js';
+import { shouldRunTypeDoc, needsRebuild } from './build-docs/build-decision.js';
+import { runTypeDoc } from './build-docs/typedoc-runner.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const PACKAGE_ROOT = join(__dirname, '..');
+const REPO_ROOT = join(PACKAGE_ROOT, '..', '..');
+const SRC_DIR = join(PACKAGE_ROOT, 'src');
+const DOCS_DIR = join(PACKAGE_ROOT, 'docs', 'api');
+const CACHE_FILE = join(PACKAGE_ROOT, '.docs-cache.json');
+const DOCS_RELEVANT_PATHS = [
+  'packages/core/src',
+  'packages/core/examples',
+  'packages/core/typedoc.json'
+];
+
+const IGNORE_PATTERNS = [
+  /\.test\.(ts|tsx)$/,
+  /\.spec\.(ts|tsx)$/,
+  /__tests__/,
+  /\/test\//,
+  /\/tests\//
+];
+
+/**
+ * Main function
+ */
+function main() {
+  const forceRebuild = process.argv.includes('--force');
+  const dryRun = process.argv.includes('--dry-run');
+  const verifyGit = process.argv.includes('--verify-git');
+
+  // Create configuration object for modules
+  const config = {
+    packageRoot: PACKAGE_ROOT,
+    repoRoot: REPO_ROOT,
+    srcDir: SRC_DIR,
+    docsDir: DOCS_DIR,
+    cacheFile: CACHE_FILE,
+    docsRelevantPaths: DOCS_RELEVANT_PATHS,
+    ignorePatterns: IGNORE_PATTERNS,
+    getLatestSourceModTime,
+    getLatestDocModTime,
+    getSourceFileHashes: (srcDir) => getSourceFileHashes(srcDir, IGNORE_PATTERNS),
+    getExistingDocHashes,
+    hasSourceChanged,
+    hashesMatch,
+    shouldSkipDueToCleanGitState,
+    primeCacheFromExistingDocs: (config) => primeCacheFromExistingDocs({
+      cacheFile: config.cacheFile,
+      docsDir: config.docsDir,
+      srcDir: config.srcDir,
+      getLatestSourceModTime: config.getLatestSourceModTime,
+      getLatestDocModTime: config.getLatestDocModTime,
+      getExistingDocHashes: config.getExistingDocHashes,
+      getSourceFileHashes: config.getSourceFileHashes
+    })
+  };
+
+  if (forceRebuild) {
+    console.log('🔄 Force rebuild requested, regenerating all documentation...');
+    const result = runTypeDoc({
+      ...config,
+      dryRun
+    });
+    if (result.success) {
+      const currentSourceHashes = getSourceFileHashes(SRC_DIR, IGNORE_PATTERNS);
+      const sourceHashesObj = {};
+      for (const [relativePath, hash] of currentSourceHashes.entries()) {
+        sourceHashesObj[relativePath] = hash;
+      }
+      
+      const cache = {
+        lastBuildTime: Date.now(),
+        sourceModTime: getLatestSourceModTime(SRC_DIR, IGNORE_PATTERNS),
+        docModTime: getLatestDocModTime(DOCS_DIR),
+        fileHashes: result.fileHashes || {},
+        sourceFileHashes: sourceHashesObj
+      };
+      if (!dryRun) {
+        saveCache(CACHE_FILE, cache);
+      }
+      console.log('✅ Documentation generation completed');
+    }
+    process.exit(result.success ? 0 : 1);
+    return;
+  }
+
+  // Load cache for decision making
+  const cache = loadCache(CACHE_FILE);
+
+  // Aggressive pre-check: Skip TypeDoc entirely if source unchanged
+  const shouldRunConfig = {
+    ...config,
+    cache
+  };
+  
+  if (!shouldRunTypeDoc(shouldRunConfig)) {
+    console.log('⏭️  Skipping TypeDoc - source files unchanged and docs are up to date');
+    process.exit(0);
+    return;
+  }
+
+  // Get git status before if verifying
+  let gitStatusBefore = [];
+  if (verifyGit) {
+    gitStatusBefore = getGitStatus(PACKAGE_ROOT, DOCS_DIR);
+    console.log(`📋 Git status before: ${gitStatusBefore.length} modified files`);
+  }
+
+  const needsRebuildConfig = {
+    ...config,
+    cache
+  };
+
+  if (needsRebuild(needsRebuildConfig)) {
+    const result = runTypeDoc({
+      ...config,
+      dryRun
+    });
+    if (result.success) {
+      const currentSourceHashes = getSourceFileHashes(SRC_DIR, IGNORE_PATTERNS);
+      const sourceHashesObj = {};
+      for (const [relativePath, hash] of currentSourceHashes.entries()) {
+        sourceHashesObj[relativePath] = hash;
+      }
+      
+      const cache = {
+        lastBuildTime: Date.now(),
+        sourceModTime: getLatestSourceModTime(SRC_DIR, IGNORE_PATTERNS),
+        docModTime: getLatestDocModTime(DOCS_DIR),
+        fileHashes: result.fileHashes || {},
+        sourceFileHashes: sourceHashesObj
+      };
+      if (!dryRun) {
+        saveCache(CACHE_FILE, cache);
+      }
+      
+      // Verify git status after if requested
+      if (verifyGit && !dryRun) {
+        const gitStatusAfter = getGitStatus(PACKAGE_ROOT, DOCS_DIR);
+        const newChanges = gitStatusAfter.filter(file => !gitStatusBefore.includes(file));
+        if (newChanges.length > 0 && result.updatedCount === 0) {
+          console.log(`\n⚠️  WARNING: Git shows ${newChanges.length} files changed but script reported 0 updates`);
+          console.log(`   This suggests files were modified unnecessarily`);
+        } else if (newChanges.length !== result.updatedCount) {
+          console.log(`\n📊 Git verification: ${newChanges.length} files changed in git, ${result.updatedCount} reported by script`);
+        }
+      }
+      
+      console.log('✅ Documentation generation completed');
+    }
+    process.exit(result.success ? 0 : 1);
+  } else {
+    console.log('⏭️  Skipping documentation generation (no changes detected)');
+    process.exit(0);
+  }
+}
+
+main();