kmcom-nuxt-layers 2.2.11 → 2.2.12

package/docs/FALLOW-COMPLEXITY-DUPLICATION-AUDIT.md

@@ -0,0 +1,65 @@
+# Fallow Complexity and Duplication Audit
+
+This file is the entry point for the layer-by-layer Fallow refactor handoff. Each app or layer has its own document under `docs/fallow-refactor/`.
+
+Use the split documents instead of one combined warning list. They separate complexity work from duplication work and identify whether the likely extraction target is a component, composable, utility, or local refactor.
+
+## Source Data
+
+The audit uses two sources:
+
+- Complexity data from `fallow health --complexity --hotspots --targets --format json --quiet --explain`.
+- Duplication data from the user-provided Fallow Problems export.
+
+Run these commands before and after each implementation phase:
+
+```bash
+FALLOW_AGENT_SOURCE=codex fallow health --complexity --hotspots --targets --format json --quiet --explain 2>/dev/null || true
+FALLOW_AGENT_SOURCE=codex fallow dupes --top 80 --format json --quiet --explain 2>/dev/null || true
+pnpm typecheck
+```
+
+## Recommended Order
+
+1. [apps/playground](./fallow-refactor/apps-playground.md)
+2. [layers/shader](./fallow-refactor/layers-shader.md)
+3. [layers/layout](./fallow-refactor/layers-layout.md)
+4. [layers/core](./fallow-refactor/layers-core.md)
+5. [layers/feeds](./fallow-refactor/layers-feeds.md)
+6. Smaller cleanup documents, ordered by risk and locality.
+
+## App Documents
+
+- [apps/debug](./fallow-refactor/apps-debug.md)
+- [apps/playground](./fallow-refactor/apps-playground.md)
+- [apps/visual-identity](./fallow-refactor/apps-visual-identity.md)
+
+## Layer Documents
+
+- [layers/animations](./fallow-refactor/layers-animations.md)
+- [layers/canvas](./fallow-refactor/layers-canvas.md)
+- [layers/content](./fallow-refactor/layers-content.md)
+- [layers/core](./fallow-refactor/layers-core.md)
+- [layers/feeds](./fallow-refactor/layers-feeds.md)
+- [layers/forms](./fallow-refactor/layers-forms.md)
+- [layers/layout](./fallow-refactor/layers-layout.md)
+- [layers/mailer](./fallow-refactor/layers-mailer.md)
+- [layers/motion](./fallow-refactor/layers-motion.md)
+- [layers/navigation](./fallow-refactor/layers-navigation.md)
+- [layers/page-transitions](./fallow-refactor/layers-page-transitions.md)
+- [layers/routing](./fallow-refactor/layers-routing.md)
+- [layers/scroll](./fallow-refactor/layers-scroll.md)
+- [layers/scripts](./fallow-refactor/layers-scripts.md)
+- [layers/seo](./fallow-refactor/layers-seo.md)
+- [layers/shader](./fallow-refactor/layers-shader.md)
+- [layers/theme](./fallow-refactor/layers-theme.md)
+- [layers/transitions](./fallow-refactor/layers-transitions.md)
+- [layers/typography](./fallow-refactor/layers-typography.md)
+- [layers/ui](./fallow-refactor/layers-ui.md)
+- [layers/visual](./fallow-refactor/layers-visual.md)
+
+## Non-Goals
+
+Do not address unused exports, unused files, unused dependencies, circular dependencies, or catalog warnings as part of this specific task. Those warnings need separate verification and tracing.
+
+Do not run `fallow fix` for this work. These refactors are structural and require manual review.

package/docs/IMPROVE-AUDIT-README.md

@@ -0,0 +1,30 @@
+# Improve Audit
+
+Audit written against commit `a2805da`.
+
+## Files
+
+| File | Purpose |
+| --- | --- |
+| [IMPROVE-AUDIT-RESULTS.md](./IMPROVE-AUDIT-RESULTS.md) | Vetted improve audit findings, direction options, verification results, and recommended planning order. |
+
+## Recommended Next Work
+
+Recommended first implementation set:
+
+1. Fix the current feeds lint failure.
+2. Bring published server routes into root typecheck and type-aware lint coverage.
+3. Stop exposing configured mailer addresses from the public forms status endpoint.
+4. Correct the forms demo mailer environment variable names.
+5. Add focused behavior tests around feed, forms/mailer, and routing paths.
+
+## Dependency Order
+
+| Order | Finding | Depends On | Status |
+| --- | --- | --- | --- |
+| 1 | Current feeds lint failure | None | TODO |
+| 2 | Server route typecheck coverage | Feeds lint fix recommended first | TODO |
+| 3 | Public forms status endpoint leaks email addresses | Server route typecheck coverage recommended first | TODO |
+| 4 | Wrong mailer env var docs in forms demo | None | TODO |
+| 5 | Missing behavior tests | Typecheck/lint baseline | TODO |
+

package/docs/IMPROVE-AUDIT-RESULTS.md

@@ -0,0 +1,52 @@
+# Improve Audit Results
+
+Audit written against commit `a2805da`.
+
+## Scope
+
+Standard hotspot-weighted audit of the Nuxt 4 pnpm workspace. The pass focused on root tooling, CI, published layer configuration, feed/form/mailer server paths, content composables, dependency posture, and existing architecture/migration docs.
+
+This pass did not audit ignored generated folders, local `.env`, or every Vue demo page exhaustively. It did not run `pnpm build` because that writes build artifacts.
+
+## Verification
+
+| Command | Result | Notes |
+| --- | --- | --- |
+| `pnpm typecheck` | PASS | Uses `vue-tsc --noEmit -p tsconfig.typecheck.json`. |
+| `pnpm lint` | FAIL | Fails in `kmcom-layer-feeds` on `layers/feeds/server/utils/content-adapter.ts:25`. |
+| `pnpm -F kmcom-layer-feeds typecheck` | PASS | Passes even though feeds server files are outside the root typecheck include. |
+| `pnpm audit --audit-level high --prod` | FAIL | Reports high advisories for `esbuild` and `ws`. |
+
+## Findings
+
+| # | Finding | Category | Impact | Effort | Risk | Confidence | Evidence |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | `pnpm lint` currently fails on feeds server code | DX / Tooling | The main local quality gate is red, so CI cannot safely adopt it yet. | S | LOW | HIGH | `layers/feeds/server/utils/content-adapter.ts:25` |
+| 2 | Published server routes are excluded from root typecheck and type-aware lint | Correctness / DX | Feed/form/mailer server code ships in npm but can pass `pnpm typecheck` with type errors hiding there. | M | MED | HIGH | `tsconfig.typecheck.json:25`, `eslint.config.mjs:387`, `package.json:37` |
+| 3 | Public forms status endpoint exposes configured email addresses | Security | Any visitor can read `emailFrom` and `emailTo`, leaking operational inboxes and increasing spam targeting. | S | LOW | HIGH | `layers/forms/server/api/forms/status.get.ts:4`, `layers/forms/server/api/forms/status.get.ts:7` |
+| 4 | Forms demo documents the wrong mailer env var namespace | Correctness / Docs | Users following the UI instructions set `NUXT_FORMS_LAYER_*`, but runtime config reads `NUXT_MAILER_LAYER_*`, leaving email unconfigured. | S | LOW | HIGH | `apps/playground/app/pages/forms.vue:732`, `layers/mailer/nuxt.config.ts:16` |
+| 5 | Contact email endpoint has no server-side abuse controls | Security | The public POST path can be used to burn Resend quota or spam the configured recipient. | M | MED | HIGH | `layers/forms/server/api/contact.post.ts:11`, `layers/mailer/server/utils/email.ts:17` |
+| 6 | Lockfile still contains high-advisory `esbuild` and `ws` versions | Security / Dependencies | Build/tooling and Nuxt Content dependency paths remain vulnerable per `pnpm audit --prod`. | S/M | MED | HIGH | `pnpm-lock.yaml:6770`, `pnpm-lock.yaml:12275` |
+| 7 | No automated behavior tests exist for the published layers | Test Coverage | Feed serialization, contact email, routing governance, and content composables have no regression harness. | M/L | LOW | HIGH | `package.json:41`, `package.json:246` |
+| 8 | Feed generation fetches whole collections before filtering/limiting | Performance | Large content collections make each feed request do avoidable in-memory filtering, sorting, and slicing. | M | MED | HIGH | `layers/feeds/server/utils/content-adapter.ts:61`, `layers/feeds/server/utils/feed-service.ts:16` |
+
+## Direction Options
+
+1. Define the routing runtime flags contract. The client fetches `/api/feature-flags`, and product/enterprise presets enable runtime flags, but the layer ships no endpoint. This should become a documented consumer contract or a small optional server route. Evidence: `layers/routing/app/plugins/feature-flags.client.ts:12`, `layers/routing/app/types/routing.ts:47`.
+
+2. Convert the existing fallow refactor docs into executable plans after the verification baseline is green. The repo already has a useful priority order in `docs/FALLOW-COMPLEXITY-DUPLICATION-AUDIT.md`, but those refactors should wait until lint/typecheck and focused tests protect behavior.
+
+## Considered And Rejected
+
+- The Nuxt Content schemas in `layers/content/content.config.ts` are not directly attached to `defineCollection()`, but `docs/MIGRATION.md:91` and `layers/content/app/types/collections.d.ts:4` document this as an intentional c12/jiti workaround. Treat future work here as decision/code drift investigation, not a simple schema attachment fix.
+- The previously documented picture provider and feeds packaging fixes were not reported again. Current source has `provider?: string`, exports `./layers/feeds`, and includes `layers/*/server/**` in package files.
+- No tracked credential values were found. Hits were environment variable names, examples, or GitHub Actions secret references.
+
+## Recommended Planning Order
+
+1. Fix finding 1 so `pnpm lint` is green.
+2. Fix finding 2 so server code is covered by the type system and type-aware lint.
+3. Fix findings 3 and 4 while the server route coverage is fresh.
+4. Add focused tests for the same paths before larger refactors.
+5. Address dependency advisories and feed query performance after the baseline is stable.
+

package/docs/IMPROVE-DEEP-AUDIT-RESULTS.md

@@ -0,0 +1,81 @@
+# Improve Deep Audit Results
+
+Deep audit written against commit `a2805da` on 2026-06-17.
+
+## Scope
+
+This pass expanded the earlier improve audit across the Nuxt 4 pnpm workspace. It reviewed root tooling, recursive package scripts, published package surfaces, server routes, content composables, feeds, forms and mailer, routing, dependency posture, CSS quality, Fallow health, duplication, dead-code leads, feature flags, and local security candidates.
+
+This pass stayed read-only for source code. It did not read `.env` files. It did not run `pnpm build` because that writes build artifacts. Ignored/generated folders were excluded from findings unless a tool accidentally scanned them; those noisy results were discarded and rerun against tracked source where possible.
+
+## Verification Summary
+
+| Command | Result | Notes |
+| --- | --- | --- |
+| `pnpm typecheck` | PASS | Root `vue-tsc --noEmit -p tsconfig.typecheck.json` passed. |
+| `pnpm -r --if-present --workspace-concurrency=1 --no-bail typecheck` | PASS | Recursive package typecheck completed successfully across workspace packages. |
+| `pnpm -r --if-present --workspace-concurrency=1 --no-bail lint` | FAIL | 23 packages passed, `kmcom-layer-feeds` failed on one ESLint error. The run also reported 63 warnings. |
+| `pnpm format:check` | FAIL | Reports unknown `ignorePath` config option and 309 formatting failures, including local `.agents` content. |
+| `git ls-files '*.css' \| xargs pnpm exec stylelint --allow-empty-input` | FAIL | Tracked CSS only: 96 problems, 84 errors and 12 warnings. |
+| `pnpm audit --audit-level high --prod --json` | FAIL | 2 high advisories: `esbuild` and `ws`. Metadata also reports 1 low and 1 moderate advisory. |
+| `fallow health --hotspots --targets --format json --quiet` | COMPLETE | 651 files, 2825 functions, 147 functions above Fallow thresholds. |
+| `fallow dupes --top 20 --format json --quiet` | COMPLETE | 467 files, 147 with clones, 5593 duplicated lines in the top clone set, 9.18% duplication. |
+| `fallow dead-code --unused-deps --unused-files --unused-exports --format json --quiet` | COMPLETE | 260 cleanup candidates: 43 files, 190 exports, 27 dependencies. Treat as trace-required leads. |
+| `fallow flags --format json --quiet` | COMPLETE | No feature flags detected by Fallow, despite routing runtime flags being hand-implemented. |
+| `fallow security --surface --format json --quiet` | COMPLETE | One low-severity weak-hash candidate in feed ETag generation. |
+
+## Confirmed Findings
+
+| Priority | Finding | Impact | Effort | Confidence | Evidence |
+| --- | --- | --- | --- | --- | --- |
+| P0 | Public forms status endpoint exposes configured email addresses. | Any visitor can read operational sender and recipient addresses, increasing spam and metadata exposure. | S | HIGH | `layers/forms/server/api/forms/status.get.ts:4`, `layers/forms/server/api/forms/status.get.ts:7`, `apps/playground/app/pages/forms.vue:662`, `apps/playground/app/pages/forms.vue:675` |
+| P0 | Contact email endpoint has no server-side abuse controls. | The public POST path can burn Resend quota, spam the configured recipient, and create noisy hooks. | M | HIGH | `layers/forms/server/api/contact.post.ts:11`, `layers/forms/server/api/contact.post.ts:22`, `layers/mailer/server/utils/email.ts:17` |
+| P0 | Production dependency audit has high advisories. | `pnpm audit` reports high-severity `esbuild` and `ws` paths in production dependency graphs. | S/M | HIGH | `pnpm-lock.yaml:6770`, `pnpm-lock.yaml:6775`, `pnpm-lock.yaml:12275`, `package.json:106`, `package.json:112`, `package.json:115` |
+| P1 | Content list composables reuse cache keys while accepting different query options. | Calls with different `tags`, `limit`, `featured`, or `excludeDrafts` can share or cancel the wrong `useAsyncData` payload. | S/M | HIGH | `layers/content/app/composables/useContentData.ts:1`, `layers/content/app/composables/useBlogPosts.ts:3`, `layers/content/app/composables/useBlogPosts.ts:6`, `layers/content/app/composables/useGalleryItems.ts:3`, `layers/content/app/composables/usePortfolioItems.ts:3`, `layers/content/app/composables/createPortfolioComposables.ts:20` |
+| P1 | Published server files are outside root typecheck and type-aware lint. | `layers/*/server/**` ships in the package but is excluded from root typechecking and has type-aware ESLint disabled. | M | HIGH | `package.json:37`, `tsconfig.typecheck.json:25`, `eslint.config.mjs:387`, `eslint.config.mjs:390` |
+| P1 | Main lint baseline is red. | Recursive lint has one hard error, so CI or pre-commit adoption cannot rely on lint yet. | S | HIGH | `layers/feeds/server/utils/content-adapter.ts:25`, recursive lint summary: 1 fail, 23 pass |
+| P1 | Format baseline is noisy and includes local agent assets. | `pnpm format:check` fails on 309 files and warns that `ignorePath` is not a valid config option. The ignore file does not exclude `.agents/` or `.claude/`. | S | HIGH | `prettier.config.cjs:46`, `.prettierignore:1`, `.prettierignore:85` |
+| P1 | No tracked behavior tests exist. | Feed serialization, forms/mailer, routing governance, content composables, and shader utilities rely on manual checks plus lint/typecheck. | M/L | HIGH | `package.json:41`, `package.json:246`; `git ls-files` found no `*.test.*`, `*.spec.*`, `tests`, or `__tests__` paths. |
+| P2 | Feed dynamic collection routes accept arbitrary collection names. | `/feed/:collection/:format` passes unvalidated path segments into `queryCollection(event, collection)`, so invalid collections become uncontrolled content-query failures instead of 404s. | S | HIGH | `layers/feeds/server/routes/feed/[collection]/rss.get.ts:2`, `layers/feeds/server/utils/content-adapter.ts:28`, `layers/feeds/app/app.config.ts:5`, `layers/feeds/server/routes/feed/discovery.get.ts:20` |
+| P2 | Feed generation fetches whole collections before filtering and limiting. | Large collections make every feed request filter, sort, and slice in memory instead of pushing draft/date/limit work into the Nuxt Content query. | M | HIGH | `layers/feeds/server/utils/content-adapter.ts:61`, `layers/feeds/server/utils/content-adapter.ts:63`, `layers/feeds/server/utils/feed-service.ts:16` |
+| P2 | Feed date handling can turn bad frontmatter into runtime feed failures. | `new Date(...)` is not validated before `toISOString()`. Invalid dates can crash JSON or Atom serialization. | S | MED | `layers/feeds/server/utils/content-adapter.ts:50`, `layers/feeds/server/utils/formats/json.ts:16`, `layers/feeds/server/utils/formats/atom.ts:13`, `layers/feeds/server/utils/formats/atom.ts:22` |
+| P2 | CSS lint rules are configured but tracked CSS fails them. | Stylelint reports 84 errors and 12 warnings against tracked CSS only, mostly token fallback hex colors, import ordering, keyframe casing, and deprecated properties. | M | HIGH | `stylelint.config.mjs:48`, `stylelint.config.mjs:123`, `layers/core/app/assets/css/core.css:6`, `layers/feeds/public/feed/style.css:15`, `layers/feeds/app/assets/css/feeds.css:20` |
+| P2 | Routing runtime flags have a client fetch contract but no shipped endpoint. | Product and enterprise presets enable `runtimeFlags`, and the client fetches `/api/feature-flags`; the layer does not provide that server route. Consumers need an explicit contract or optional route. | S/M | HIGH | `layers/routing/app/plugins/feature-flags.client.ts:8`, `layers/routing/app/plugins/feature-flags.client.ts:12`, `layers/routing/app/types/routing.ts:47`, `layers/routing/app/types/routing.ts:56` |
+| P3 | Feed ETag generation uses MD5. | This is not password/signature crypto, but modern cache fingerprints should use SHA-256 to avoid weak-crypto findings. | S | HIGH | `layers/feeds/server/utils/cache.ts:5` |
+
+## Structural Findings
+
+Fallow health reports the codebase is broadly maintainable but has concentrated complexity. It analyzed 651 files and 2825 functions; 147 functions exceed Fallow thresholds, with 28 critical, 37 high, and 82 moderate findings. The hottest files include `layers/feeds/server/utils/feed-service.ts`, content composables, `layers/layout/app/components/Layout/Grid/Item.vue`, theme/client plugin code, scroll helpers, and large shader playground pages.
+
+The shader area is the largest duplication cluster. Fallow dupes reports 5593 duplicated lines in the top clone set, with repeated shader pipeline color watchers across 29 components, repeated material mouse uniform watchers across 8 components, and repeated theme preset boilerplate across 7 components. Evidence starts at `layers/shader/app/components/Pipeline/Aurora.client.vue:41`, `layers/shader/app/components/Material/AmbientAurora.client.vue:61`, and `layers/shader/app/components/Preset/ThemeAurora.client.vue:2`.
+
+The largest demo pages are also carrying application logic. `apps/playground/app/pages/shader-background.vue` and `apps/playground/app/pages/shader-pipeline-background.vue` both contain large `getActiveBlocks()` switches at `apps/playground/app/pages/shader-background.vue:299` and `apps/playground/app/pages/shader-pipeline-background.vue:221`. These are good refactor candidates after the quality gates are green, but they are less urgent than public server and dependency issues.
+
+`layers/layout/app/components/Layout/Grid/Item.vue` has a high-impact computed style block starting at `layers/layout/app/components/Layout/Grid/Item.vue:139`. Fallow marks it as a high-priority refactor target because many files depend on it and its responsive grid logic is complex.
+
+Fallow dead-code reports 260 cleanup candidates, but many are Nuxt-layer assets, auto-import surfaces, CSS files, and public exported types. Treat those as leads only. Trace each candidate before deletion with `fallow dead-code --trace ...` or `fallow dead-code --trace-file ...`.
+
+## Tooling Notes
+
+The root `format:check` failure is partly self-inflicted. Prettier reads `.prettierignore` by default, but `ignorePath` inside `prettier.config.cjs` is not a supported config key. The current `.prettierignore` also omits `.agents/` and `.claude/`, so local agent skill files get formatted as project content.
+
+The stylelint run against raw globs originally picked up ignored build output such as `apps/playground/dist`. The result above uses `git ls-files '*.css'`, so it represents tracked CSS only.
+
+Depcheck reported unused dependencies, but it also read local agent skill files and Nuxt layer side effects poorly. I did not use depcheck as evidence for removal. Fallow dependency findings are still trace-required because dependencies can be required by Nuxt modules, `nuxt.config.ts`, peer dependency contracts, or package publishing.
+
+## Considered And Rejected
+
+- The Nuxt Content schema workaround remains intentionally documented. `docs/MIGRATION.md` explains why schemas are not passed directly to `defineCollection()`, so this audit does not recommend a simple schema attachment change.
+- Ignored generated output under `.nuxt`, `.output`, `.netlify`, `dist`, and local package caches is not treated as source debt. When a tool scanned those paths, I reran a scoped command.
+- Fallow reported no feature flags, but the routing layer uses a custom runtime flag pattern. That means Fallow did not detect the pattern; it does not mean runtime flags are absent.
+- The MD5 feed ETag finding is a hardening item, not a confirmed exploit. The hash is used for response cache validation, not credential storage or signature verification.
+
+## Recommended Triage Order
+
+1. Fix public server risks first: remove address exposure from the status endpoint and add abuse controls to contact submission.
+2. Resolve high dependency advisories and the current feeds lint failure so the baseline is trustworthy.
+3. Bring `layers/*/server/**/*.ts` into typecheck or a dedicated Nitro server typecheck before changing server routes.
+4. Fix content composable cache keys and add targeted tests for content list variants.
+5. Harden feed routes with collection allowlisting, query pushdown, and date validation.
+6. Clean the formatting and CSS lint baselines so future reports are not buried in noise.
+7. Use the existing Fallow refactor docs plus this report to sequence shader/layout/playground structural work after tests exist.

package/docs/fallow-refactor/apps-debug.md

@@ -0,0 +1,27 @@
+# apps/debug
+
+`apps/debug` has no complexity or duplication findings in the current Fallow snapshot used for this audit.
+
+## Complexity Findings
+
+- No current findings.
+
+## Duplication Findings
+
+- No current findings in the supplied Problems export.
+
+## Component Opportunities
+
+- No extraction is recommended.
+
+## Composable Opportunities
+
+- No extraction is recommended.
+
+## Utility Opportunities
+
+- No extraction is recommended.
+
+## Agent Notes
+
+Do not create refactor work for this app unless a later Fallow run introduces findings.

package/docs/fallow-refactor/apps-playground.md

@@ -0,0 +1,46 @@
+# apps/playground
+
+`apps/playground` has the highest-value overlap between complexity and duplication. Start here before touching lower-risk layers.
+
+## Complexity Findings
+
+- `15` complexity findings.
+- `7` critical findings.
+- `apps/playground/app/pages/shader-background.vue:299` defines `getActiveBlocks` with cyclomatic complexity `57` and cognitive complexity `101`.
+- `apps/playground/app/pages/shader-pipeline-background.vue:221` defines a matching `getActiveBlocks` with cyclomatic complexity `57` and cognitive complexity `101`.
+- `apps/playground/app/pages/routing.vue:126` computes `simResult` with high branching.
+
+## Duplication Findings
+
+- `16` duplicate warnings.
+- `shader-background.vue:299-546` duplicates `shader-pipeline-background.vue:221-468` for `248` lines.
+- `shader-background.vue:72-182` duplicates `shader-pipeline-background.vue:60-163` for `111` lines.
+- `typography.vue:2-83` duplicates `ui.vue:2-91` for `90` lines.
+- `Demo/ThemeNode.client.vue:51-92` duplicates `Demo/ThemeCanvas.client.vue:90-133` for `44` lines.
+
+## Component Opportunities
+
+- Create `Demo/ShaderDemoShell.vue` for the shared full-screen shader demo layout.
+- Create `Demo/ShaderPresetGrid.vue` for category-specific preset buttons.
+- Create `Demo/ShaderBackgroundControls.vue` for the right-hand controls.
+- Create `Demo/ShaderGrainLayerRenderer.vue` for repeated grain rendering blocks.
+
+## Composable Opportunities
+
+- Create `useShaderBackgroundDemo()` for category state, active preset state, grain state, active labels, and generated code.
+- Create `useDemoAccent()` for repeated `setPageAccent()` and cleanup patterns.
+- Create `useThemeNodeUniforms()` for shared theme color and ambient uniform watchers used by `ThemeNode` and `ThemeCanvas`.
+- Move routing demo logic to `useRoutingDemo()` if the page keeps reactive simulator state.
+
+## Utility Opportunities
+
+- Create `apps/playground/app/utils/shaderBackgroundPresets.ts` for preset metadata and block serialization.
+- Create `apps/playground/app/utils/routingSimulation.ts` for the governance simulator.
+- Create `apps/playground/app/utils/demoSnippets.ts` for UI and typography code snippets.
+
+## Acceptance Criteria
+
+- The two `getActiveBlocks` complexity findings disappear or drop below threshold.
+- The `248` line shader page duplicate group disappears.
+- The page output and generated code output remain equivalent.
+- `pnpm typecheck` passes.

package/docs/fallow-refactor/apps-visual-identity.md

@@ -0,0 +1,41 @@
+# apps/visual-identity
+
+`apps/visual-identity` has small but clear duplication and moderate complexity. Treat this as a focused cleanup after the larger shader and playground work.
+
+## Complexity Findings
+
+- `10` complexity findings.
+- `2` critical findings.
+- `apps/visual-identity/app/composables/useExport.ts:135` has a high-complexity `generateTailwindV4`.
+- `apps/visual-identity/app/composables/useExport.ts:90` has a high-complexity `generateCssVars`.
+- `apps/visual-identity/app/composables/useBrandState.ts:151` has a critical `migrateState`.
+- `apps/visual-identity/app/components/Colour/ModePreview.vue:31` has a critical `mixOklch`.
+
+## Duplication Findings
+
+- `6` duplicate warnings.
+- `useExport.ts:114-126` duplicates `useExport.ts:158-170`.
+- Typography page setup duplicates between `typography/index.vue` and `typography/scale.vue`.
+- `colour/themes.vue` contains two small same-file duplicate groups.
+
+## Component Opportunities
+
+- Add a small typography page header component only if the same header pattern appears in more than the current two files.
+- Keep color preview components domain-specific.
+
+## Composable Opportunities
+
+- Keep `useExport()` as the public composable.
+- Move migration logic behind a small `useBrandStateMigrations()` helper only if migrations grow beyond the current version.
+
+## Utility Opportunities
+
+- Create `apps/visual-identity/app/utils/exportWriters.ts` for token line generation.
+- Create `apps/visual-identity/app/utils/brandStateMigrations.ts` for versioned state migration.
+- Create `apps/visual-identity/app/utils/oklchMix.ts` for OKLCH mixing used by components.
+
+## Acceptance Criteria
+
+- Duplicate export writer blocks disappear.
+- `generateCssVars` and `generateTailwindV4` use shared writer helpers.
+- `pnpm typecheck` passes.

package/docs/fallow-refactor/layers-animations.md

@@ -0,0 +1,34 @@
+# layers/animations
+
+`layers/animations` has duplicated pointer/motion logic and several high-complexity animation callbacks. Keep public animation composables separate.
+
+## Complexity Findings
+
+- `8` complexity findings.
+- `5` high findings.
+- Main findings include `useTiltEffect.ts:17`, `useMagneticElement.ts:17`, `MarqueeText.vue:80`, and `Marquee.vue:87`.
+
+## Duplication Findings
+
+- `2` duplicate warnings.
+- `useMagneticElement.ts:42-50` duplicates `useTiltEffect.ts:42-54`.
+
+## Component Opportunities
+
+- No new component is recommended.
+
+## Composable Opportunities
+
+- Create `usePointerMotionFrame()` for shared RAF setup, cleanup, and pointer interpolation.
+- Keep `useMagneticElement()` and `useTiltEffect()` as public composables because their interaction semantics differ.
+
+## Utility Opportunities
+
+- Extract shared lerp, bounds, and transform math helpers if they repeat after composable extraction.
+
+## Acceptance Criteria
+
+- The magnetic/tilt duplicate group disappears.
+- Public composable signatures remain stable.
+- Motion behavior remains visually equivalent.
+- `pnpm typecheck` passes.

package/docs/fallow-refactor/layers-canvas.md

@@ -0,0 +1,32 @@
+# layers/canvas
+
+`layers/canvas` has moderate renderer capability complexity. This is a local utility refactor, not a component extraction.
+
+## Complexity Findings
+
+- `3` complexity findings.
+- `1` high finding.
+- Main findings include `useRendererCapabilities.ts:97`, `useRendererCapabilities.ts:17`, and `nuxt.config.ts:133`.
+
+## Duplication Findings
+
+- No duplication warnings for this layer in the supplied Problems export.
+
+## Component Opportunities
+
+- No component extraction is recommended.
+
+## Composable Opportunities
+
+- Keep `useRendererCapabilities()` as the public composable.
+
+## Utility Opportunities
+
+- Extract renderer feature detection into pure predicate helpers.
+- Extract capability normalization into one resolver.
+
+## Acceptance Criteria
+
+- Renderer detection remains stable across WebGL, WebGPU, and fallback cases.
+- `useRendererCapabilities()` keeps its public return shape.
+- `pnpm typecheck` passes.

package/docs/fallow-refactor/layers-content.md

@@ -0,0 +1,33 @@
+# layers/content
+
+`layers/content` has small, repeated collection query composables. Use a generic composable and keep domain wrappers.
+
+## Complexity Findings
+
+- `6` complexity findings.
+- All are moderate.
+- Main findings include portfolio, gallery, and blog collection helpers/components.
+
+## Duplication Findings
+
+- `2` duplicate warnings.
+- `useGalleryItems.ts:11-20` duplicates `usePortfolioItems.ts:15-24`.
+
+## Component Opportunities
+
+- No component extraction is recommended from the current findings.
+
+## Composable Opportunities
+
+- Create `useCollectionItems()` that accepts collection name, query options, ordering, and limit.
+- Keep `useGalleryItems()` and `usePortfolioItems()` as thin wrappers.
+
+## Utility Opportunities
+
+- Extract shared query option normalization if needed.
+
+## Acceptance Criteria
+
+- The gallery/portfolio duplicate group disappears.
+- Domain-specific wrapper composables remain available.
+- `pnpm typecheck` passes.

package/docs/fallow-refactor/layers-core.md

@@ -0,0 +1,39 @@
+# layers/core
+
+`layers/core` has several utility-style complexity findings. Prefer rule tables and pure helpers while keeping composable APIs stable.
+
+## Complexity Findings
+
+- `20` complexity findings.
+- `4` critical findings.
+- `layers/core/app/composables/useBrowser.ts:13` defines `parseBrowserInfo` with cyclomatic complexity `27` and cognitive complexity `20`.
+- `layers/core/app/plugins/init.ts:14` defines a high-complexity setup function.
+- `layers/core/app/composables/useFeatures.ts:139` defines `applyFeatureClasses`.
+
+## Duplication Findings
+
+- `2` duplicate warnings.
+- `layers/core/app/pages/[...slug].vue:4-29` duplicates `layers/core/app/types/app-config.d.ts:13-34`.
+- Treat this duplicate group as low priority until verified. It may be structural or type-like rather than real runtime duplication.
+
+## Component Opportunities
+
+- No component extraction is recommended.
+
+## Composable Opportunities
+
+- Keep `useBrowser()` and `useFeatures()` as public composables.
+- Move parsing and class mapping out of the composables.
+
+## Utility Opportunities
+
+- Create `layers/core/app/utils/browserInfo.ts` with OS and browser detection rule tables.
+- Create `layers/core/app/utils/featureClasses.ts` for feature class mapping.
+- Split plugin setup helpers by responsibility in `layers/core/app/plugins/init.ts`.
+
+## Acceptance Criteria
+
+- `parseBrowserInfo` no longer uses a long `if`/`else` chain.
+- `applyFeatureClasses` uses a feature-to-class map.
+- Public composable return shapes remain stable.
+- `pnpm typecheck` passes.

package/docs/fallow-refactor/layers-feeds.md

@@ -0,0 +1,39 @@
+# layers/feeds
+
+`layers/feeds` has complexity in server-side feed assembly and formatters. The best target is pure utilities with thin route handlers.
+
+## Complexity Findings
+
+- `8` complexity findings.
+- `3` critical findings.
+- `layers/feeds/server/utils/feed-service.ts:6` defines `buildFeed` with cyclomatic complexity `22` and cognitive complexity `16`.
+- `layers/feeds/server/utils/formats/rss.ts:5` defines `toRSS` with high complexity.
+- `layers/feeds/server/utils/content-adapter.ts:33` defines `resolveFeedAuthor`.
+
+## Duplication Findings
+
+- No duplication warnings for this layer in the supplied Problems export.
+
+## Component Opportunities
+
+- No component extraction is relevant.
+
+## Composable Opportunities
+
+- No app composable extraction is recommended for the server-side findings.
+
+## Utility Opportunities
+
+- Create `layers/feeds/server/utils/feed-config.ts`.
+- Extract `resolveFeedSiteConfig()`.
+- Extract `resolveFeedCollection()`.
+- Extract `createFeedConfig()`.
+- Create `layers/feeds/server/utils/feed-author.ts`.
+- Create `layers/feeds/server/utils/feed-xml.ts` for XML escaping and repeated RSS serialization helpers.
+
+## Acceptance Criteria
+
+- Route handlers remain thin orchestration functions.
+- `buildFeed` delegates config and collection resolution.
+- RSS formatting uses smaller helpers for item URL, author, media, dates, and XML escaping.
+- `pnpm typecheck` passes.

package/docs/fallow-refactor/layers-forms.md

@@ -0,0 +1,30 @@
+# layers/forms
+
+`layers/forms` has one moderate component-level complexity finding. Keep this as a local cleanup.
+
+## Complexity Findings
+
+- `1` complexity finding.
+- `layers/forms/app/components/Form/Field.vue:64` defines `textInputProps` with moderate complexity.
+
+## Duplication Findings
+
+- No duplication warnings for this layer in the supplied Problems export.
+
+## Component Opportunities
+
+- No component extraction is recommended.
+
+## Composable Opportunities
+
+- No composable extraction is recommended.
+
+## Utility Opportunities
+
+- Extract input prop normalization into a small helper if more field types share the pattern.
+
+## Acceptance Criteria
+
+- `Form/Field.vue` remains the public field component.
+- Text input props remain unchanged.
+- `pnpm typecheck` passes.

package/docs/fallow-refactor/layers-layout.md

@@ -0,0 +1,42 @@
+# layers/layout
+
+`layers/layout` has one concentrated complexity hotspot in grid placement style generation. This wants utilities, not new components.
+
+## Complexity Findings
+
+- `5` complexity findings.
+- `1` critical finding.
+- `layers/layout/app/components/Layout/Grid/Item.vue:139` defines a computed `style` function with cyclomatic complexity `35` and cognitive complexity `52`.
+
+## Duplication Findings
+
+- `4` duplicate warnings.
+- All duplicate warnings sit inside `Layout/Grid/Item.vue`.
+- The duplicate blocks repeat responsive `md` and `lg` CSS variable assignment for row and column placement.
+
+## Component Opportunities
+
+- No new component is needed.
+- Keep `Layout/Grid/Item.vue` as the component boundary.
+
+## Composable Opportunities
+
+- Share logic with `layers/layout/app/composables/GridPlacement.ts` only if it needs reactive state.
+- Prefer pure utilities first.
+
+## Utility Opportunities
+
+- Create `layers/layout/app/utils/gridPlacementStyle.ts`.
+- Extract `resolveDefaultPlacement()`.
+- Extract `resolveResponsivePlacementVars()`.
+- Extract `resolveBleedStyles()`.
+- Extract `resolveAlignmentStyles()`.
+- Extract `resolveRhythmStyles()`.
+- Extract `resolveLayerStyles()`.
+
+## Acceptance Criteria
+
+- `Grid/Item.vue:139` drops below critical complexity.
+- Local responsive-var duplicate warnings disappear.
+- Full-span, bleed-left, bleed-right, responsive row, and responsive column behavior stays unchanged.
+- `pnpm typecheck` passes.

package/docs/fallow-refactor/layers-mailer.md

@@ -0,0 +1,32 @@
+# layers/mailer
+
+`layers/mailer` has one high-complexity email helper and one type-like duplicate group.
+
+## Complexity Findings
+
+- `1` complexity finding.
+- `layers/mailer/server/utils/email.ts:9` defines `sendContactEmail` with high complexity.
+
+## Duplication Findings
+
+- `2` duplicate warnings.
+- `app/types/mailer.ts:7-24` duplicates `server/utils/hooks.ts:3-20`.
+
+## Component Opportunities
+
+- No component extraction is relevant.
+
+## Composable Opportunities
+
+- No composable extraction is recommended.
+
+## Utility Opportunities
+
+- Move shared hook/event types into one importable type module.
+- Split `sendContactEmail()` into payload validation, recipient resolution, template data creation, and provider send call.
+
+## Acceptance Criteria
+
+- The duplicated mailer type block has one source of truth.
+- Server email sending behavior remains unchanged.
+- `pnpm typecheck` passes.