Toolify integrated growth + engagement — manual release gate (NO-GO)

docs/ENGAGEMENT_NEXT_WAVE_2026-11-05.md

@@ -0,0 +1,39 @@
+# Toolify365 — engagement improvement follow-up (2026-11-05)
+
+## Implemented in draft PR #39
+- Recently visited links on tool pages, limited to 3; now exclude both current/unknown/duplicate and any destination already shown by the existing related-tools row.
+- Percentage-calculator A/B comparison and explicit local draft save/restore/delete, 7-day expiry, 17-language text.
+- Analytics: `recent_tool_click` and `scenario_action` (IDs only; no user-entered numbers).
+- Standalone verification: pure-module strict TypeScript passed; 29 earlier independent assertions, 9 shared-state checks and 6 recent-link-selection checks passed separately. **Not full project Vitest/Next build**.
+
+## Current release blocks
+1. Full checkout cannot be fetched from this environment due to DNS resolution of github.com. Run `bash scripts/check-engagement-release.sh` on an owner-accessible clone.
+2. Manual en/ja desktop/mobile keyboard, share-link, unavailable browser storage, expired draft, consent and GA4 DebugView QA.
+3. Merge only after those checks; VPS deployment and post-deploy smoke test belong to owner.
+4. HYPD live-browser and Lighthouse endpoints were not available on the connected plan, so no real mobile performance score was obtained. HYPD GA4 account summaries returned no **selected** properties; do not claim measured engagement improvements.
+
+## Additional work worth doing after release, in impact order
+**P0 — use evidence, not time-on-page alone.** Establish last 28 days vs preceding 28 days: engaged sessions, engagement rate, average engagement time per session, pages/session, `calculate`, `recent_tool_click`, `related_click`, `scenario_action`, affiliate click and revenue. Break down by tool landing page, device, locale and source. Deduplicate returning navigation and avoid counting passive tabs as improvement. Register necessary GA4 custom dimensions (event-scoped `destination_tool`, `action`) if they are absent; verify consent first.
+
+**P1 — test on high-intent tools only.** Pick the top 5 landing pages from GA4 with enough traffic and the lowest engaged-session ratio; verify tool result is visible in first mobile viewport and no ad obscures it. Prioritize task completion, then a single logically related next action. Do not add generic link blocks or timers just to inflate average duration.
+
+**P2 — contextual workflows.** After successful % calculator comparison, test task-specific save/compare for loan, tip and other numeric tools only if a privacy review confirms their inputs are safe for local persistence. For free-text, health, financial identifiers or uploads, avoid blanket auto-save.
+
+**P3 — speed and A/B rollout.** Measure mobile Lighthouse LCP/INP/CLS, test reserved ad space and lazy loading, validate language navigation and ad placement. Roll out behind a tested feature gate or short evaluation window when analytics/sample size supports it. Roll back if tool completion or mobile performance worsens.
+
+## Operational release policy
+PR #39 stays draft / NO-GO until full build and real-device QA succeed. This document is a plan for further implementation, not a claim of production changes, conversion lifts or GA4 access.
+
+## Additional implementation: result-first navigation (2026-11-05)
+- `ToolFrame` now shows the existing related tool row and the new recent tool row **immediately after the workspace, before the below-result and banner ad units**. Both ad units, the in-article ad, and sidebar ad are retained; this is an ordering change, not an ad removal.
+- The previous related/recent deduplication means suggestions maximize distinct follow-up actions.
+- Added `site/src/components/tools/ToolFrame.order.test.ts` to enforce source-level order and retained ad components. This test was committed but has NOT been run inside the project's Vitest environment.
+- GitHub code readback confirmed the order after commit; visual, iPhone, ad placement and RPM impact still require real device QA and post-release measurement.
+- `percentage-calculator` was verified present in `MANUAL_SHARE_SLUGS`: its own `useShareableState` intentionally disables generic URL writing from `useAutoShareableState`, so this PR does not need to add a second serialization path.
+- GA4 cannot currently be queried with the selected connection: HYPD reports connected GA4 accounts but no selected property. Select the Toolify365 property before any baseline analysis; do not infer current engagement from other businesses.
+
+## ShareBar URL polling optimization (2026-11-05)
+- Replaced unconditional one-second URL polling with change events and history/BFCache resynchronization.
+- Both manual and automatic share hooks now notify the result-link control immediately after replaceState.
+- Added source-level regression tests in ShareBar.events.test.ts; full project Vitest and browser tests not run.
+- Validate result-link availability after edits, navigation and tab restoration before release. No performance uplift claimed.

docs/GROWTH_RELEASE_GATE_2026-11-05.md

@@ -0,0 +1,86 @@
+# Toolify365 Growth Release Gate — 2026-11-05
+
+Related: #37, PR #38. No GitHub Actions are required or authorized for this rollout.
+
+## Existing SEO safeguards (do not duplicate)
+- `src/app/sitemap.ts`: generates only URLs selected by `isIndexableIn` / `indexableLocalesFor`.
+- `src/app/robots.ts`: publishes robots/sitemap configuration.
+- `src/lib/seo/metadata.ts`: canonical, robots and hreflang.
+- `src/lib/tools/registry.ts`: demand-ranked core index allowlist + selective locale exceptions.
+- `scripts/audit-seo.ts`, `scripts/report-index-policy.ts`, `scripts/indexnow.ts`: existing audits and index notification.
+
+**Do not** bulk-index all 223 tools × 17 locales. GSC index coverage is NOT the same as the count of URLs intended for indexing.
+
+## Local verification from repository root
+
+```bash
+cd site
+npm ci
+npm run typecheck
+npm run test
+npm run validate
+npm run audit:seo
+npm run audit:i18n
+npm run audit:index-policy -- --json
+npm run build
+```
+
+These checks need a machine with dependencies and network/required build environment. If any check fails, do not merge or deploy. Follow existing `prebuild` exchange-rate freshness policy; do not bypass it to force a green build.
+
+## Browser QA before production
+1. Check en and ja pages `/tools/character-frequency` and `/tools/reverse-text-generator`: free software CTA appears below tool and links to Text Batch Studio with correct locale.
+2. Check `/tools/csv-json-converter` and `/tools/json-formatter`: only currently available CSV Cleaner Pro and JSON Studio destinations appear.
+3. Confirm a tool with no mapping does not show an empty software panel.
+4. On mobile and keyboard navigation, confirm CTA focus, labels and layout.
+5. Check `/software/{csv-cleaner-pro,json-studio,text-batch-studio}` processing / downloading still work, and failed input still gives the previous error.
+6. Consent/debug QA: `software_click` fires on CTA, `software_process` on process success/failure and `software_download` on a download click. No user-entered text, file name or file contents are sent. Without GA configuration events are safe no-ops.
+7. Verify live canonical host is `https://toolify365.com`, and check HTTP 200, robots/sitemap and hreflang reciprocal URLs manually. Search-result snippets can lag deployment.
+
+## GA4 definitions
+Create event-scoped custom dimensions (where not already present): `tool_slug`, `locale`, `destination`, `software_slug`. Do not register redundant fields. Analyze:
+- Organic landing sessions → `calculate` → `software_click`
+- `software_click` → `software_process` successful
+- `software_process` → `software_download`
+Count users/sessions when possible, not only raw events. Exclude internal traffic. Not all click-through events guarantee successful navigation or file download.
+
+## Search prioritization
+- Obtain last 28 finalized days and prior 28 days from GSC / Bing, grouped by page + query + locale/country + device.
+- Work on high-impression, low-CTR indexed pages first; ensure unique title, accurate introduction, examples and FAQ.
+- Expand `INDEX_EXCEPTIONS` only for verified demand with localized content; 5–10 pairs at a time, assess after 28 days, rollback if indexing/crawl quality degrades.
+- Do not automatically post marketing links to unrelated communities or create scaled thin pages.
+
+## Deployment and rollback
+- After all gates pass, merge PR #38 and deploy by the site's owner-managed process.
+- Verify direct URLs and GA4 DebugView, then submit **changed, valid, canonical** URLs using existing IndexNow script (not Google).
+- Record release commit, timestamp, and post-release GA4/GSC/Bing baseline.
+- If UI/processing or analytics regress, revert PR #38 and redeploy; do not edit the sitemap allowlist as part of rollback unless it changed.
+
+## Current evidence
+Source-only reviews are not equivalent to running the above commands. The connected GSC access returned a 3-day sample (2026-10-31 to 2026-11-02) with no suggested opportunities; it cannot establish a 28-day comparison or zero traffic.
+
+## Post-deployment automated smoke check (new)
+Run only **after** a successful owner deployment:
+```bash
+cd site
+SITE_URL=https://toolify365.com npm run audit:live-growth
+```
+This performs read-only HTTP checks on key en/ja tool and software pages, expected contextual CTA HTML, canonical presence, robots and sitemap. HTTP connectivity is required; a failure from a restricted runner is NOT proof that the production site is down. This script is not a substitute for browser interaction tests, GA4 DebugView, live Search Console URL Inspection or a local production build.
+
+## Extended release safeguards (2026-11-05)
+The `audit:live-growth` script now also checks that known index-eligible core tool pages do **not** return a noindex meta tag and appear in the served sitemap, while verifying same-origin self-canonical and unexpected redirects. This is a *post-deployment* check; it intentionally fails when the current production deployment does not yet contain the PR's CTA. Do not run it as a pre-deploy gate against the old production version.
+
+## Dependency-free regression test (2026-11-05)
+`cd site && npm run test:smoke-html` runs the Node built-in test suite for HTML meta robots, canonical extraction, and actual on-domain, same-locale software CTA anchor detection. This was also exercised in an isolated Node.js 22 environment (3 test groups passing). It is **not** a substitute for Next.js/Vitest full tests, real browser QA or deploy verification.
+
+## Parallel PR integration guard — PR #39
+PR #39 (engagement) also edits `site/src/components/tools/ToolFrame.tsx` and `site/src/lib/analytics/events.ts`, both changed in this PR #38. Do **not** overwrite either file with an entire version copied from one PR while merging the other.
+
+When integrating:
+1. Rebase/merge both branches locally in a scratch branch (not `main`).
+2. Preserve in `ToolFrame.tsx` BOTH PR #39's engagement/navigation UI and PR #38's `ToolSoftwareRecommendations` section.
+3. Preserve in `events.ts` ALL existing event exports plus PR #39 event changes and PR #38 `trackSoftwareClick`, `trackSoftwareProcess`, `trackSoftwareDownload`.
+4. Resolve conflicts, run TypeScript, all tests including `test:smoke-html`, audits and build, and review DOM/keyboard order of CTA vs related/recents.
+5. Only after passing checks merge/release through the owner process. Avoid untested sequential merges.
+
+## Isolated execution evidence
+Node.js 22 `node --test` was run on exact reproduced copies of `growth-html-checks.mjs` and its test cases in the working container: 3/3 subtests passed (robots/googlebot; canonical; valid destination/locale/origin). This does **not** validate the complete Next.js application, GitHub PR head in a cloned checkout, nor the deployed website.