geneseed 5.5.0 → 5.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +17 -0
- package/README.md +9 -9
- package/SHIPPED.md +1 -1
- package/docs/extending.md +1 -1
- package/docs/guides/install.md +5 -5
- package/docs/reference/profiles.md +84 -0
- package/harness.config.json +1 -1
- package/js/build/export.mjs +11 -16
- package/js/hosts/hooks.mjs +4 -1
- package/package.json +1 -1
- package/profiles/autonomous.json +14 -0
- package/profiles/corporate.json +14 -0
- package/profiles/mentor.json +13 -0
- package/profiles/minimal.json +15 -0
- package/src/agents/devops-engineer.md +6 -5
- package/src/agents/kubernetes-specialist.md +3 -1
- package/src/agents/spring-boot-engineer.md +3 -3
- package/src/agents/spring-reviewer.md +4 -2
- package/src/skills/codebase-design.md +2 -2
- package/src/skills/diagram-design/SKILL.md +12 -7
- package/src/skills/diagram-design/VENDOR.md +19 -14
- package/src/skills/diagram-design/references/layout-budget.md +7 -1
- package/src/skills/diagram-design/references/onboarding.md +1 -1
- package/src/skills/diagram-design/references/primitives-core.md +1 -1
- package/src/skills/diagram-design/references/semantic-patterns.md +1 -1
- package/src/skills/diagram-design/references/style-guide.md +1 -1
- package/src/skills/diagram-design/references/type-dependency.md +69 -0
- package/src/skills/diagram-design/references/type-event-modeling.md +36 -0
- package/src/skills/diagram-design/references/type-requirement-traceability.md +45 -0
- package/src/skills/diagram-design/references/type-sbgn.md +80 -0
- package/src/skills/diagram-design/references/type-scatter.md +1 -1
- package/src/skills/diagram-design/references/type-steps.md +180 -0
- package/src/skills/diagram-design/references/type-unit-grid.md +63 -0
- package/src/skills/geneseed-code-review.md +2 -1
- package/src/skills/parallel-agents.md +1 -1
- package/src/skills/react-view-transitions/AGENTS.md +26 -26
- package/src/skills/react-view-transitions/SKILL.md +1 -1
- package/src/skills/react-view-transitions/VENDOR.md +12 -3
- package/src/skills/spring-boot/cloud.md +19 -1
- package/src/skills/spring-boot/logging.md +5 -3
- package/src/skills/spring-boot/web.md +27 -2
- package/src/skills/spring-boot.md +4 -2
- package/src/skills/spring-data-jpa.md +18 -4
- package/src/skills/spring-testing.md +4 -0
- package/src/upstreams.json +4 -4
- package/web/dist/assets/{Activity-LKsDzsnK.js → Activity-bUSPM3Dl.js} +1 -1
- package/web/dist/assets/{ActivityDetail-DhwTfPm6.js → ActivityDetail-AHRoXeFN.js} +1 -1
- package/web/dist/assets/{Bonsai-CePMLrpr.js → Bonsai-B5XY9pid.js} +1 -1
- package/web/dist/assets/{CopyButton-CuoaJ6k7.js → CopyButton-C0wwRR9H.js} +1 -1
- package/web/dist/assets/{Dashboard-D1VKuvLe.js → Dashboard-DPAA96EI.js} +2 -2
- package/web/dist/assets/{Docs-CUrHJKaU.js → Docs-CpGDq165.js} +1 -1
- package/web/dist/assets/{Factories-Ci1XfmSy.js → Factories-cNhETa5Q.js} +1 -1
- package/web/dist/assets/{GreenhouseView-CNfH2lPK.js → GreenhouseView-DO3ADmT9.js} +1 -1
- package/web/dist/assets/{Installs-ZHQZM1iS.js → Installs-D3dDyq10.js} +1 -1
- package/web/dist/assets/{JournalView-CMsWahkS.js → JournalView--W-Lw_V9.js} +1 -1
- package/web/dist/assets/{Kits-CkliyK0n.js → Kits-ChfehxY6.js} +1 -1
- package/web/dist/assets/Laws-CNxYmV36.js +4 -0
- package/web/dist/assets/{LibRows-Brv0Hmkr.js → LibRows-CiPvsRYB.js} +1 -1
- package/web/dist/assets/{Library-BYmiLjJr.js → Library-BxQvbwVU.js} +1 -1
- package/web/dist/assets/{Loops-ytm-xJ68.js → Loops-DAblKkyq.js} +1 -1
- package/web/dist/assets/{OperatorHudView-KaqCx_HP.js → OperatorHudView-QtSaSyYm.js} +1 -1
- package/web/dist/assets/{Personal-CmcnRKYE.js → Personal-DxSGv638.js} +1 -1
- package/web/dist/assets/{Settings-tUrpdOfq.js → Settings-CgTbhvRv.js} +1 -1
- package/web/dist/assets/{Tabs-CD7etcGD.js → Tabs-Cf4X1hdz.js} +1 -1
- package/web/dist/assets/{index-COKbhFNo.js → index-B_pTwZra.js} +3 -3
- package/web/dist/assets/index-CzfImiYb.css +1 -0
- package/web/dist/index.html +2 -2
- package/web/dist/assets/Laws-hh4O3HZ4.js +0 -4
- package/web/dist/assets/index-Ba_Kg3Af.css +0 -1
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Unit Grid
|
|
2
|
+
|
|
3
|
+
**Best for:** one bounded whole expressed as equal, discrete units: completion, capacity, survey responses, inventory, or a checklist. Use the canonical waffle form when the reader needs to see an exact count out of 100.
|
|
4
|
+
|
|
5
|
+
Not for: category-by-category comparison (use a **bar chart**), a part-of-whole with unequal pieces (use a **treemap**), continuous change (use a **line chart**), or a matrix where row and column positions carry meaning (the future punch-card variant).
|
|
6
|
+
|
|
7
|
+
## Input contract
|
|
8
|
+
|
|
9
|
+
```yaml
|
|
10
|
+
title: "Release readiness"
|
|
11
|
+
total: 100
|
|
12
|
+
filled: 64
|
|
13
|
+
unit_label: "release check"
|
|
14
|
+
focal_index: 63
|
|
15
|
+
source_note: "Illustrative checklist"
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Validation rules:
|
|
19
|
+
|
|
20
|
+
1. Version 1 is a 10 by 10 grid with exactly 100 cells.
|
|
21
|
+
2. `total` is exactly `100`; `filled` is an integer from `0` through `100`.
|
|
22
|
+
3. Every cell represents one unit. Do not use fractional cells, scaled cells, or merged cells.
|
|
23
|
+
4. At most one completed cell is focal. Accent is editorial emphasis, never a larger unit.
|
|
24
|
+
5. Cells fill in reading order, left to right and top to bottom. A different order needs an explicit future variant.
|
|
25
|
+
6. Rows and columns carry no category meaning in the canonical waffle form.
|
|
26
|
+
|
|
27
|
+
## Layout conventions
|
|
28
|
+
|
|
29
|
+
- Use a 10 by 10 grid of equal 20px cells with a 4px gutter. The shipped examples begin at `(382, 86)`, making the grid 236px square inside a `1000 × 390` viewBox.
|
|
30
|
+
- Every chart root carries `data-unit-grid="true"`, `data-unit-total="100"`, `data-unit-filled`, `data-unit-rows="10"`, and `data-unit-columns="10"`.
|
|
31
|
+
- Every cell is a `<rect>` with `data-unit-cell="filled"` or `data-unit-cell="empty"` and a unique `data-unit-index` from 0 through 99. `scripts/verify-unit-grid.py` checks count, geometry, indices, the declared filled value, and printed labels.
|
|
32
|
+
- Use one ink fill for completed cells, a quieter paper-relative fill for remaining cells, and no more than one accent completed cell. The count, not color, carries the value. Set each cell's literal fill on the `<rect>` (or a parent `<g>`): completed cells must match the page's `:root` `--ink` or `--accent`, and remaining cells share one other fill well away from both. Cells sit directly in the chart `<svg>` or in plain `<g>`/`<a>` groups with no `style`, `transform` or conditional attributes; cell strokes stay at or under 2px and corner radii at or under a quarter of the cell. The verifier rejects opacity, visibility, display, filter, mask, clip-path, paint-order and mix-blend-mode on cells or their ancestors, paint, stroke or hiding rules in `<style>` (after decoding escapes), `@import`, any linked stylesheet but Google Fonts, SMIL animation, and any element drawn after the first cell whose box touches the grid or cannot be computed from plain numeric attributes. It does not see HTML wrappers around the SVG or scripts.
|
|
33
|
+
- Mark the percentage text with `data-unit-percent="true"` and the count text with `data-unit-count="true"`. They must read `64%` and `64 complete · 36 remaining` for `filled: 64`; both are checked against `data-unit-filled`. Each label is plain visible `<text>` inside the chart SVG (no child elements, no hiding or `style` attributes), painted `--ink` or `--muted`, at least 8px, and inside the viewBox.
|
|
34
|
+
- Do not apply transforms to cells or their SVG/group ancestors, or move geometry through CSS. Bake movement into the coordinates so the verifier checks the rendered positions.
|
|
35
|
+
- Put the exact count in text near the grid and state the unit in the source line. The grid must remain understandable in grayscale.
|
|
36
|
+
- Keep the legend block below the grid. Label the focal cell as editorial emphasis, so it cannot be mistaken for a special unit.
|
|
37
|
+
|
|
38
|
+
## Honest-data rule
|
|
39
|
+
|
|
40
|
+
A unit grid claims that one mark equals one unit. Never round a 63.4% result to 64 filled cells without saying that the display is rounded. Never use a partial fill, larger focal cell, gradient, or area-sized mark to recover precision. If the denominator is not naturally bounded to 100, choose a number of whole cells that makes the unit honest or choose a different chart.
|
|
41
|
+
|
|
42
|
+
## Complexity budget
|
|
43
|
+
|
|
44
|
+
- Exactly 100 cells in a 10 by 10 grid.
|
|
45
|
+
- One count and one optional focal completed cell.
|
|
46
|
+
- One legend and one source note.
|
|
47
|
+
- Static output only.
|
|
48
|
+
- No categorical row or column axes in version 1.
|
|
49
|
+
|
|
50
|
+
## Anti-patterns
|
|
51
|
+
|
|
52
|
+
- Partial, merged, oversized, or differently shaped cells.
|
|
53
|
+
- Rainbow status fills or multiple accent cells.
|
|
54
|
+
- Using the grid for a denominator other than 100 without an explicit future variant.
|
|
55
|
+
- Treating rows and columns as categories. That is the later punch-card variant, not this canonical waffle form.
|
|
56
|
+
- Gradients, heatmap ramps, 3-D treatments, or shadows.
|
|
57
|
+
- Filling in a non-reading order without explaining that order.
|
|
58
|
+
|
|
59
|
+
## Examples
|
|
60
|
+
|
|
61
|
+
- `assets/example-unit-grid.html` - minimal light.
|
|
62
|
+
- `assets/example-unit-grid-dark.html` - minimal dark with the same dataset and geometry.
|
|
63
|
+
- `assets/example-unit-grid-full.html` - full editorial with unchanged grid geometry.
|
|
@@ -21,7 +21,8 @@
|
|
|
21
21
|
4. For a large change, consider dispatching the
|
|
22
22
|
[reviewer {{AGENT}}](../{{DIR_AGENTS}}/reviewer.md) to keep the main context clean.
|
|
23
23
|
When a spec exists and the diff spans more than a few files, run pass 3 in its own
|
|
24
|
-
subagent,
|
|
24
|
+
subagent — started fresh, never a fork of your own context — handed only the diff
|
|
25
|
+
command and the spec, alongside passes 1–2: a pass
|
|
25
26
|
that has already filled up on code findings stops reading the spec closely, and
|
|
26
27
|
kept apart, one axis's findings never mask the other's.
|
|
27
28
|
5. Pass 1 — correctness: logic errors, edge cases, error handling, race
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
## Procedure
|
|
12
12
|
1. Confirm independence: the subtasks must not depend on each other's output or write the same files ({{DOCTRINE:one-writer-per-file}}). Write down each unit's **write set** — the files or globs it may change — and intersect them; an overlap runs in sequence or goes to one owner, and shared append files (registries, index tables, lockfiles, generated bundles) stay with you. If they're sequential or share state, use [plan](plan.md) instead.
|
|
13
13
|
2. Split the work into self-contained units, each with one clear goal and a defined output contract — what it must return. Several small edits of one kind (the same fix, constant or field across files) form ONE unit with the union write set and get one review.
|
|
14
|
-
3. Dispatch each unit to its own subagent in one batch — units that call one rationed resource run in sequence instead ({{DOCTRINE:serialize-against-a-rationed-resource}}) — each under a handoff envelope: the unit's goal, the inputs it needs, its **write set** (edit nothing outside it; return rows for a shared file instead of writing it), the observable check that proves it done, its output contract — naming every file it changed — and the inherited constraints (a unit in the shared tree never commits or pushes; a slice on its own branch (step 6) commits only there, never pushes — {{DOCTRINE:consent-before-push}} stays with you; no sub-agents of its own — review comes from you; gaps reported, never invented). Hand each unit only the access its goal needs ({{LAW:least-privilege}}). Prefer the read-only [explorer {{AGENT}}](../{{DIR_AGENTS}}/explorer.md) for investigation so the heavy reading stays out of the main context ({{DOCTRINE:context-economy}}). Where no subagent capability exists, run the units sequentially as personas instead, converging the same way.
|
|
14
|
+
3. Dispatch each unit to its own fresh subagent (never a fork: a fork carries your context and model tier) in one batch — units that call one rationed resource run in sequence instead ({{DOCTRINE:serialize-against-a-rationed-resource}}) — each under a handoff envelope: the unit's goal, the inputs it needs, its **write set** (edit nothing outside it; return rows for a shared file instead of writing it), the observable check that proves it done, its output contract — naming every file it changed — and the inherited constraints (a unit in the shared tree never commits or pushes; a slice on its own branch (step 6) commits only there, never pushes — {{DOCTRINE:consent-before-push}} stays with you; no sub-agents of its own — review comes from you; gaps reported, never invented). Hand each unit only the access its goal needs ({{LAW:least-privilege}}). Prefer the read-only [explorer {{AGENT}}](../{{DIR_AGENTS}}/explorer.md) for investigation so the heavy reading stays out of the main context ({{DOCTRINE:context-economy}}). Where no subagent capability exists, run the units sequentially as personas instead, converging the same way.
|
|
15
15
|
|
|
16
16
|
**Brief checklist** — the envelope also states:
|
|
17
17
|
- **Git state:** the ref to measure (`HEAD` or `origin/main`, after a fetch) and whether the diff is staged, on disk or committed; after a restart, `git log` before redoing "uncommitted" work — a stale ref redoes every finding.
|
|
@@ -44,7 +44,7 @@ Reserve directional slides for hierarchical navigation (list → detail) and ord
|
|
|
44
44
|
## Availability
|
|
45
45
|
|
|
46
46
|
- **Next.js:** Do **not** install `react@canary` — the App Router already bundles React canary internally. `ViewTransition` works out of the box. `npm ls react` may show a stable-looking version; this is expected.
|
|
47
|
-
- **Without Next.js:**
|
|
47
|
+
- **Without Next.js:** Use stable `react` and `react-dom` 19.3 or newer (`ViewTransition` and `addTransitionType` became stable in React 19.3). Earlier stable React versions do not include these APIs.
|
|
48
48
|
- Browser support: Chromium 125+ (React needs the v2 object form of `startViewTransition`), Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers.
|
|
49
49
|
|
|
50
50
|
---
|
|
@@ -363,7 +363,7 @@ For each shared element (`name` prop), note every navigation where a pair forms
|
|
|
363
363
|
|
|
364
364
|
## Step 2: Add CSS Recipes
|
|
365
365
|
|
|
366
|
-
Choose the animation pattern from the audit and this skill's guidance, then copy only the applicable sections from [css-recipes.md](css-recipes.md). Always include reduced motion. Add live-root, persistent-element, backdrop, or floating-element rules only when the audit found those surfaces.
|
|
366
|
+
Choose the animation pattern from the audit and this skill's guidance, then copy only the applicable sections from [css-recipes.md](references/css-recipes.md). Always include reduced motion. Add live-root, persistent-element, backdrop, or floating-element rules only when the audit found those surfaces.
|
|
367
367
|
|
|
368
368
|
Customize timing after the structure works. Keep ordinary crossfades opacity-only; scope blur to a specific shared morph when it is intentional.
|
|
369
369
|
|
|
@@ -375,7 +375,7 @@ For every persistent element identified in Step 1, add a `viewTransitionName` st
|
|
|
375
375
|
<header style={{ viewTransitionName: "site-header" }}>...</header>
|
|
376
376
|
```
|
|
377
377
|
|
|
378
|
-
Then add the [Persistent Element Isolation](css-recipes.md#persistent-element-isolation) CSS (prevents the element from animating during page transitions). If the element uses `backdrop-blur` or `backdrop-filter`, use the [Backdrop-Blur Workaround](css-recipes.md#backdrop-blur-workaround) instead.
|
|
378
|
+
Then add the [Persistent Element Isolation](references/css-recipes.md#persistent-element-isolation) CSS (prevents the element from animating during page transitions). If the element uses `backdrop-blur` or `backdrop-filter`, use the [Backdrop-Blur Workaround](references/css-recipes.md#backdrop-blur-workaround) instead.
|
|
379
379
|
|
|
380
380
|
If a Suspense fallback mirrors a persistent control (e.g., a skeleton search input), give both the real control and the skeleton the same `viewTransitionName` so they morph in place.
|
|
381
381
|
|
|
@@ -410,7 +410,7 @@ Then wrap each **page component** (not layout) in a type-keyed `<ViewTransition>
|
|
|
410
410
|
</ViewTransition>
|
|
411
411
|
```
|
|
412
412
|
|
|
413
|
-
The `nav-forward` and `nav-back` CSS classes from [Directional Navigation](css-recipes.md#directional-navigation) produce horizontal slides. For simpler apps where directional motion isn't needed, a bare `<ViewTransition default="none">` wrapper with `enter="fade-in"` / `exit="fade-out"` works too.
|
|
413
|
+
The `nav-forward` and `nav-back` CSS classes from [Directional Navigation](references/css-recipes.md#directional-navigation) produce horizontal slides. For simpler apps where directional motion isn't needed, a bare `<ViewTransition default="none">` wrapper with `enter="fade-in"` / `exit="fade-out"` works too.
|
|
414
414
|
|
|
415
415
|
Extract this into a reusable component so every page doesn't repeat the verbose type map:
|
|
416
416
|
|
|
@@ -460,7 +460,7 @@ This example uses `slide-down` / `slide-up` for directional vertical motion. For
|
|
|
460
460
|
- Always use `default="none"` on the content `<ViewTransition>` to prevent re-animation on revalidation or unrelated transitions.
|
|
461
461
|
- Use simple string props (not type maps) on Suspense `<ViewTransition>`s — Suspense resolves fire as separate transitions with no type, so type-keyed props won't match.
|
|
462
462
|
- A fallback/content `share` pair morphs between snapshots. Use it only when that interpolation is desired and does not distort layout or geometry.
|
|
463
|
-
- If the same element appears in **both** the fallback and the content (a title, a heading), it flickers on reveal — an opacity dip. Render it **outside** the `<Suspense>` boundary (or pin it), so it isn't in both. See [Suspense reveal flicker](patterns.md#suspense-reveal-flicker).
|
|
463
|
+
- If the same element appears in **both** the fallback and the content (a title, a heading), it flickers on reveal — an opacity dip. Render it **outside** the `<Suspense>` boundary (or pin it), so it isn't in both. See [Suspense reveal flicker](references/patterns.md#suspense-reveal-flicker).
|
|
464
464
|
|
|
465
465
|
## Step 6: Add Shared Element Transitions
|
|
466
466
|
|
|
@@ -478,9 +478,9 @@ For every shared visual element identified in Step 1, add matching named `<ViewT
|
|
|
478
478
|
</ViewTransition>
|
|
479
479
|
```
|
|
480
480
|
|
|
481
|
-
The `share="morph"` class uses the [Shared Element Morph](css-recipes.md#shared-element-morph) recipe (controlled duration + motion blur). For a simpler cross-fade, use `share="auto"` (browser default).
|
|
481
|
+
The `share="morph"` class uses the [Shared Element Morph](references/css-recipes.md#shared-element-morph) recipe (controlled duration + motion blur). For a simpler cross-fade, use `share="auto"` (browser default).
|
|
482
482
|
|
|
483
|
-
When list items contain shared elements, compose both patterns with two nested `<ViewTransition>` layers — an outer keyed VT for list identity and an inner named VT for the cross-route pair. See [Composing Shared Elements with List Identity](
|
|
483
|
+
When list items contain shared elements, compose both patterns with two nested `<ViewTransition>` layers — an outer keyed VT for list identity and an inner named VT for the cross-route pair. See [Composing Shared Elements with List Identity](SKILL.md#composing-shared-elements-with-list-identity).
|
|
484
484
|
|
|
485
485
|
**Rules:**
|
|
486
486
|
- Names must be globally unique — use prefixes like `photo-${id}`.
|
|
@@ -497,9 +497,9 @@ Walk through every row in the navigation map from Step 1 and confirm:
|
|
|
497
497
|
- Do persistent elements stay static (not sliding with page content)?
|
|
498
498
|
- Do Suspense reveals animate independently from directional navigations?
|
|
499
499
|
|
|
500
|
-
If any path produces no animation or competing animations, use the symptom-driven [troubleshooting guide](troubleshooting.md).
|
|
500
|
+
If any path produces no animation or competing animations, use the symptom-driven [troubleshooting guide](references/troubleshooting.md).
|
|
501
501
|
|
|
502
|
-
For Next.js-specific implementation steps (`transitionTypes` on `<Link>`, prefetch behavior, and same-route dynamic segments), see [nextjs.md](nextjs.md).
|
|
502
|
+
For Next.js-specific implementation steps (`transitionTypes` on `<Link>`, prefetch behavior, and same-route dynamic segments), see [nextjs.md](references/nextjs.md).
|
|
503
503
|
|
|
504
504
|
---
|
|
505
505
|
|
|
@@ -621,10 +621,10 @@ Use `key` when content identity changes (state resets). Omit for cross-fades (ta
|
|
|
621
621
|
|
|
622
622
|
## Isolate Elements from Parent Animations
|
|
623
623
|
|
|
624
|
-
Pull an element out of the animated `root` snapshot by giving it its own `view-transition-name`. **`view-transition-name: none` is a no-op** — it's the CSS default, so the element stays in `root` (a common flicker bug). Use a real, unique name, then neutralize with `<ViewTransition default="none">` (no CSS) or CSS (needed for `z-index`/`display` control — see [css-recipes.md](css-recipes.md#persistent-element-isolation)).
|
|
624
|
+
Pull an element out of the animated `root` snapshot by giving it its own `view-transition-name`. **`view-transition-name: none` is a no-op** — it's the CSS default, so the element stays in `root` (a common flicker bug). Use a real, unique name, then neutralize with `<ViewTransition default="none">` (no CSS) or CSS (needed for `z-index`/`display` control — see [css-recipes.md](references/css-recipes.md#persistent-element-isolation)).
|
|
625
625
|
|
|
626
626
|
- **Persistent chrome** (nav, sidebar, player bar): `<nav style={{ viewTransitionName: 'persistent-nav' }}>` + isolation CSS. `<ViewTransition default="none">` works too, but its auto-name can't take `z-index`/backdrop `display:none` — hand-name when you need those.
|
|
627
|
-
- **Floating elements** (popovers, menus): left open, they're captured in `root` and flicker on settle. Real name + isolation ([Floating Element Isolation](css-recipes.md#floating-element-isolation-popovers-menus-tooltips-control-clusters)). A static name is fine if only one is mounted (`unmountOnHide`); native top-layer (`popover`/`<dialog>`) settle-flicker is a browser limit.
|
|
627
|
+
- **Floating elements** (popovers, menus): left open, they're captured in `root` and flicker on settle. Real name + isolation ([Floating Element Isolation](references/css-recipes.md#floating-element-isolation-popovers-menus-tooltips-control-clusters)). A static name is fine if only one is mounted (`unmountOnHide`); native top-layer (`popover`/`<dialog>`) settle-flicker is a browser limit.
|
|
628
628
|
- **Naming an interactive element has a cost:** named participants are skipped by hit-testing while a transition runs ([csswg#10930](https://github.com/w3c/csswg-drafts/issues/10930)) — clicks and hover fall through to whatever is beneath. Portal named popovers/menus; rendered inline in a clickable row, mid-transition clicks activate the row and read as outside-clicks that close the popover.
|
|
629
629
|
- **Third-party floating components** (toast libraries, portals you don't render): put the name on an always-mounted wrapper you own — `<div style={{ viewTransitionName: 'toaster' }} className="pointer-events-none fixed inset-0">`. Library containers often unmount when empty, so naming them directly leaves the group unpinned exactly when a toast appears mid-transition. Name a dialog's backdrop separately from its panel so each pins independently.
|
|
630
630
|
|
|
@@ -641,7 +641,7 @@ Don't put a manual `viewTransitionName` on the root DOM node inside `<ViewTransi
|
|
|
641
641
|
|
|
642
642
|
## Sliding Indicator (tabs)
|
|
643
643
|
|
|
644
|
-
One shared-name indicator rendered under the **active** tab morphs between positions on change (slide the group, disable old/new — see [Sliding Indicator](css-recipes.md#sliding-indicator-tab-underline--segmented-pill)). Render it only under the active tab so exactly one element holds `indicatorName`; use a distinct `indicatorName` per tab strip. Trigger the state change inside `startTransition` so the move animates. Whatever owns `active` drives it — local state here, routing in Next (see [Routing-Driven Tabs](nextjs.md#routing-driven-tabs)).
|
|
644
|
+
One shared-name indicator rendered under the **active** tab morphs between positions on change (slide the group, disable old/new — see [Sliding Indicator](references/css-recipes.md#sliding-indicator-tab-underline--segmented-pill)). Render it only under the active tab so exactly one element holds `indicatorName`; use a distinct `indicatorName` per tab strip. Trigger the state change inside `startTransition` so the move animates. Whatever owns `active` drives it — local state here, routing in Next (see [Routing-Driven Tabs](references/nextjs.md#routing-driven-tabs)).
|
|
645
645
|
|
|
646
646
|
```tsx
|
|
647
647
|
import { useState, useTransition, ViewTransition } from 'react';
|
|
@@ -668,7 +668,7 @@ export function Tabs({ tabs, indicatorName = 'tab-indicator' }) {
|
|
|
668
668
|
}
|
|
669
669
|
```
|
|
670
670
|
|
|
671
|
-
Because the state change is a transition, if the newly-active tab renders suspending content the whole update — indicator **and** `aria-current` — waits for it to commit, and the strip feels dead on click. Give the controls an immediate value with `useOptimistic` (drive `aria-current` from it) so feedback is instant while the content streams. The routing variant ([Routing-Driven Tabs](nextjs.md#routing-driven-tabs)) does exactly this: optimistic `aria-current`, committed `active` for the bar.
|
|
671
|
+
Because the state change is a transition, if the newly-active tab renders suspending content the whole update — indicator **and** `aria-current` — waits for it to commit, and the strip feels dead on click. Give the controls an immediate value with `useOptimistic` (drive `aria-current` from it) so feedback is instant while the content streams. The routing variant ([Routing-Driven Tabs](references/nextjs.md#routing-driven-tabs)) does exactly this: optimistic `aria-current`, committed `active` for the bar.
|
|
672
672
|
|
|
673
673
|
## Layout Displacement Morph
|
|
674
674
|
|
|
@@ -719,7 +719,7 @@ function AnimatedCollapse({ open, children }) {
|
|
|
719
719
|
</Activity>
|
|
720
720
|
```
|
|
721
721
|
|
|
722
|
-
Only reach for Activity when there's state worth preserving — a stateless element (e.g. the sliding indicator above) gains nothing from it. In Next.js, layout-hosted chrome already persists across navigations without Activity (see [nextjs.md](nextjs.md#layout-level-viewtransition)).
|
|
722
|
+
Only reach for Activity when there's state worth preserving — a stateless element (e.g. the sliding indicator above) gains nothing from it. In Next.js, layout-hosted chrome already persists across navigations without Activity (see [nextjs.md](references/nextjs.md#layout-level-viewtransition)).
|
|
723
723
|
|
|
724
724
|
## Exclude Elements with `useOptimistic`
|
|
725
725
|
|
|
@@ -790,9 +790,9 @@ The `types` array (second argument) lets you vary animation based on transition
|
|
|
790
790
|
|
|
791
791
|
**Scrolling hangs while a transition animates:** the `::view-transition` overlay is `position: fixed` and its snapshots don't scroll — a browser limitation, not fixable in React (skipping snaps to the end). Keep reveal durations short; for scroll-driven UI use gesture transitions (experimental `useSwipeTransition`, if available).
|
|
792
792
|
|
|
793
|
-
**Open popover flickers when a background transition settles:** it's captured in `root`. Give it a real `view-transition-name` + isolation (not `none`) — see [Isolate Elements from Parent Animations](patterns.md#isolate-elements-from-parent-animations).
|
|
793
|
+
**Open popover flickers when a background transition settles:** it's captured in `root`. Give it a real `view-transition-name` + isolation (not `none`) — see [Isolate Elements from Parent Animations](references/patterns.md#isolate-elements-from-parent-animations).
|
|
794
794
|
|
|
795
|
-
**Popover closes or goes dead when clicked mid-transition:** named participants are skipped by hit-testing while a transition runs; clicks land on what's beneath and read as outside-clicks. Portal the popover (see [Isolate Elements from Parent Animations](patterns.md#isolate-elements-from-parent-animations)); brief dead clicks during the transition remain — that's the price of the name.
|
|
795
|
+
**Popover closes or goes dead when clicked mid-transition:** named participants are skipped by hit-testing while a transition runs; clicks land on what's beneath and read as outside-clicks. Portal the popover (see [Isolate Elements from Parent Animations](references/patterns.md#isolate-elements-from-parent-animations)); brief dead clicks during the transition remain — that's the price of the name.
|
|
796
796
|
|
|
797
797
|
**Shared morph silently not firing:** `share` resolved to `none`. Either the VT has `default="none"` with no explicit `share` prop, or `share` is type-keyed and the navigation never adds the type — the link needs `transitionTypes` (or `addTransitionType` in the transition).
|
|
798
798
|
|
|
@@ -800,7 +800,7 @@ The `types` array (second argument) lets you vary animation based on transition
|
|
|
800
800
|
|
|
801
801
|
**An enter animation runs even though Suspense never showed its fallback:** The content-side VT became the topmost entering subtree during navigation. At that call site, add a host DOM element immediately outside `Suspense`. The host suppresses the nested enter during warm navigation but remains mounted so the VT can enter on a later fallback-to-content reveal. Keep the host outside `Suspense`, not inside the reusable crossfade; do nothing when a direct host already exists.
|
|
802
802
|
|
|
803
|
-
**Section below a list teleports instead of gliding:** it's outside any activated boundary, its VT has `default="none"` (which disables `update`), or it isn't an immediate sibling of the changing content. See [Layout Displacement Morph](patterns.md#layout-displacement-morph).
|
|
803
|
+
**Section below a list teleports instead of gliding:** it's outside any activated boundary, its VT has `default="none"` (which disables `update`), or it isn't an immediate sibling of the changing content. See [Layout Displacement Morph](references/patterns.md#layout-displacement-morph).
|
|
804
804
|
|
|
805
805
|
**`router.back()` and browser back/forward skip the directional slide:** traversals carry no transition types, so type-keyed maps resolve to `default` — untyped shared-element morphs still apply. Use `router.push()` for typed animations.
|
|
806
806
|
|
|
@@ -820,7 +820,7 @@ The `types` array (second argument) lets you vary animation based on transition
|
|
|
820
820
|
|
|
821
821
|
**Hash fragments cause scroll jumps:** Navigate without hash; scroll programmatically after navigation.
|
|
822
822
|
|
|
823
|
-
**Backdrop-blur flickers:** Use the [Backdrop-Blur Workaround](css-recipes.md#backdrop-blur-workaround).
|
|
823
|
+
**Backdrop-blur flickers:** Use the [Backdrop-Blur Workaround](references/css-recipes.md#backdrop-blur-workaround).
|
|
824
824
|
|
|
825
825
|
**`border-radius` lost during transitions:** Apply `border-radius` directly to the captured element.
|
|
826
826
|
|
|
@@ -1050,7 +1050,7 @@ The `::view-transition` overlay captures all pointer events. React shrinks it to
|
|
|
1050
1050
|
}
|
|
1051
1051
|
```
|
|
1052
1052
|
|
|
1053
|
-
Trade-offs: clicks can hit live elements under still-moving snapshots, and it only helps **unnamed** content — named participants are skipped by hit-testing for the transition's duration, no CSS override ([csswg#10930](https://github.com/w3c/csswg-drafts/issues/10930)). Weigh that before naming interactive elements; portal named popovers (see [Isolate Elements from Parent Animations](patterns.md#isolate-elements-from-parent-animations)).
|
|
1053
|
+
Trade-offs: clicks can hit live elements under still-moving snapshots, and it only helps **unnamed** content — named participants are skipped by hit-testing for the transition's duration, no CSS override ([csswg#10930](https://github.com/w3c/csswg-drafts/issues/10930)). Weigh that before naming interactive elements; portal named popovers (see [Isolate Elements from Parent Animations](references/patterns.md#isolate-elements-from-parent-animations)).
|
|
1054
1054
|
|
|
1055
1055
|
---
|
|
1056
1056
|
|
|
@@ -1155,13 +1155,13 @@ Read the current [Next.js View Transitions guide](https://nextjs.org/docs/app/gu
|
|
|
1155
1155
|
|
|
1156
1156
|
Because every link click is a transition, any VT with `default="auto"` fires on **every** navigation — use `default="none"` to prevent competing animations.
|
|
1157
1157
|
|
|
1158
|
-
For unexpected or broken animation behavior, see [troubleshooting.md](troubleshooting.md).
|
|
1158
|
+
For unexpected or broken animation behavior, see [troubleshooting.md](references/troubleshooting.md).
|
|
1159
1159
|
|
|
1160
1160
|
---
|
|
1161
1161
|
|
|
1162
1162
|
## Next.js Implementation Additions
|
|
1163
1163
|
|
|
1164
|
-
When following [implementation.md](implementation.md), apply these additions:
|
|
1164
|
+
When following [implementation.md](references/implementation.md), apply these additions:
|
|
1165
1165
|
|
|
1166
1166
|
**Step 4:** Use `transitionTypes` on `<Link>` — see [The `transitionTypes` Prop](#the-transitiontypes-prop-on-nextlink). If the animation depends on dynamic destination content, also see [When Content Must Be Ready](#when-content-must-be-ready).
|
|
1167
1167
|
|
|
@@ -1171,11 +1171,11 @@ When following [implementation.md](implementation.md), apply these additions:
|
|
|
1171
1171
|
|
|
1172
1172
|
## Layout-Level ViewTransition
|
|
1173
1173
|
|
|
1174
|
-
**Do NOT add a layout-level VT wrapping `{children}` if pages have their own VTs.** A nested VT skips its own enter/exit only when it mounts or unmounts *as one unit* with a parent VT, which is exactly what a layout VT wrapping `{children}` causes — page-level enter/exit will silently not work. Remove the layout VT entirely. Nesting is otherwise fine and sometimes required: a child VT inside a *persistent* parent VT fires enter/exit normally, and two nested boundaries are the intended shape for [shared elements inside list items](
|
|
1174
|
+
**Do NOT add a layout-level VT wrapping `{children}` if pages have their own VTs.** A nested VT skips its own enter/exit only when it mounts or unmounts *as one unit* with a parent VT, which is exactly what a layout VT wrapping `{children}` causes — page-level enter/exit will silently not work. Remove the layout VT entirely. Nesting is otherwise fine and sometimes required: a child VT inside a *persistent* parent VT fires enter/exit normally, and two nested boundaries are the intended shape for [shared elements inside list items](SKILL.md#composing-shared-elements-with-list-identity).
|
|
1175
1175
|
|
|
1176
1176
|
A bare `<ViewTransition>` in layout works only if pages have **no** VTs of their own.
|
|
1177
1177
|
|
|
1178
|
-
**Layouts persist across navigations** — `enter`/`exit` only fire on initial mount, not on route changes. Don't use type-keyed maps in layouts. Because layouts persist, chrome hosted in one (nav, sidebar, player) keeps its state across navigations for free — no `Activity` needed. Reserve `Activity` for in-page show/hide (see [Composing with Activity](patterns.md#composing-with-activity)).
|
|
1178
|
+
**Layouts persist across navigations** — `enter`/`exit` only fire on initial mount, not on route changes. Don't use type-keyed maps in layouts. Because layouts persist, chrome hosted in one (nav, sidebar, player) keeps its state across navigations for free — no `Activity` needed. Reserve `Activity` for in-page show/hide (see [Composing with Activity](references/patterns.md#composing-with-activity)).
|
|
1179
1179
|
|
|
1180
1180
|
---
|
|
1181
1181
|
|
|
@@ -1260,15 +1260,15 @@ function SortControl() {
|
|
|
1260
1260
|
}
|
|
1261
1261
|
```
|
|
1262
1262
|
|
|
1263
|
-
List items wrapped in `<ViewTransition key={item.id}>` will animate reorder. This is the server-component alternative to the client-side [Searchable Grid](patterns.md#searchable-grid-with-usedeferredvalue) pattern.
|
|
1263
|
+
List items wrapped in `<ViewTransition key={item.id}>` will animate reorder. This is the server-component alternative to the client-side [Searchable Grid](references/patterns.md#searchable-grid-with-usedeferredvalue) pattern.
|
|
1264
1264
|
|
|
1265
|
-
For immediate control feedback while the route commits, use `useOptimistic` for the button state but keep the animated list tied to the committed sort value. See [Exclude Elements with `useOptimistic`](patterns.md#exclude-elements-with-useoptimistic).
|
|
1265
|
+
For immediate control feedback while the route commits, use `useOptimistic` for the button state but keep the animated list tied to the committed sort value. See [Exclude Elements with `useOptimistic`](references/patterns.md#exclude-elements-with-useoptimistic).
|
|
1266
1266
|
|
|
1267
1267
|
---
|
|
1268
1268
|
|
|
1269
1269
|
## Routing-Driven Tabs
|
|
1270
1270
|
|
|
1271
|
-
The generalized sliding indicator ([Sliding Indicator](patterns.md#sliding-indicator-tabs)) driven by navigation instead of local state: tabs are `<Link>`s, `active` comes from the URL (a server prop), and `useOptimistic` slides the indicator instantly while the route commits. Key the mounted indicator to committed `active` so the bar lands where navigation actually settles.
|
|
1271
|
+
The generalized sliding indicator ([Sliding Indicator](references/patterns.md#sliding-indicator-tabs)) driven by navigation instead of local state: tabs are `<Link>`s, `active` comes from the URL (a server prop), and `useOptimistic` slides the indicator instantly while the route commits. Key the mounted indicator to committed `active` so the bar lands where navigation actually settles.
|
|
1272
1272
|
|
|
1273
1273
|
```tsx
|
|
1274
1274
|
'use client';
|
|
@@ -44,7 +44,7 @@ Reserve directional slides for hierarchical navigation (list → detail) and ord
|
|
|
44
44
|
## Availability
|
|
45
45
|
|
|
46
46
|
- **Next.js:** Do **not** install `react@canary` — the App Router already bundles React canary internally. `ViewTransition` works out of the box. `npm ls react` may show a stable-looking version; this is expected.
|
|
47
|
-
- **Without Next.js:**
|
|
47
|
+
- **Without Next.js:** Use stable `react` and `react-dom` 19.3 or newer (`ViewTransition` and `addTransitionType` became stable in React 19.3). Earlier stable React versions do not include these APIs.
|
|
48
48
|
- Browser support: Chromium 125+ (React needs the v2 object form of `startViewTransition`), Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers.
|
|
49
49
|
|
|
50
50
|
---
|
|
@@ -10,14 +10,16 @@ listed in the generator's `VENDORED_SKILL_DIRS`.
|
|
|
10
10
|
- **Credit:** {{CREDIT:react-view-transitions:skills/react-view-transitions}}
|
|
11
11
|
|
|
12
12
|
The licence is MIT, declared in the upstream repo README's `## License`. Upstream ships no LICENSE
|
|
13
|
-
file (neither at the pinned commit nor on `main`; re-checked at
|
|
13
|
+
file (neither at the pinned commit nor on `main`; re-checked at 1a2c79d4), so there is no license text to carry here
|
|
14
14
|
and the entry's `licenseFile` is null; the README's declaration is the whole grant.
|
|
15
15
|
|
|
16
16
|
The skill follows the [Agent Skills](https://agentskills.io/) format (`SKILL.md` +
|
|
17
17
|
`references/`). Its internal links point at the upstream project's own files; do not
|
|
18
|
-
"fix" them to Geneseed paths — that is why the folder is gate-exempt.
|
|
18
|
+
"fix" them to Geneseed paths — that is why the folder is gate-exempt. Deviation 4 below only
|
|
19
|
+
repoints links that miss a sibling file of this folder. To update,
|
|
19
20
|
re-copy the upstream folder (new or removed files included, e.g. `references/troubleshooting.md`), re-apply the deviations below, and bump the entry's `commit`
|
|
20
|
-
in `src/upstreams.json`.
|
|
21
|
+
in `src/upstreams.json`. Afterwards every relative link in every `.md` here must resolve to a
|
|
22
|
+
file inside this folder.
|
|
21
23
|
|
|
22
24
|
**Deviation 1:** upstream's frontmatter says `name: vercel-react-view-transitions`;
|
|
23
25
|
here it is `name: react-view-transitions`. The Agent Skills format requires the name to
|
|
@@ -29,6 +31,13 @@ here it is `` `ViewTransition` ``. The Agent Skills spec forbids XML tags in a d
|
|
|
29
31
|
`checkBuild`'s description arm reports one for every first-party skill — the tag would be the
|
|
30
32
|
only one left in any install's catalogue.
|
|
31
33
|
|
|
34
|
+
**Deviation 4:** upstream's `AGENTS.md` is compiled from `SKILL.md` and the `references/` files,
|
|
35
|
+
and keeps the references' sibling-relative links, which miss at the folder root. In `AGENTS.md`
|
|
36
|
+
only, `](<name>.md` becomes `](references/<name>.md` for `<name>` in `css-recipes`,
|
|
37
|
+
`implementation`, `nextjs`, `patterns` and `troubleshooting` (any `#anchor` kept), and
|
|
38
|
+
`](../SKILL.md` becomes `](SKILL.md`. Links already written `](references/…` are left alone.
|
|
39
|
+
The other files keep upstream's links byte for byte: they already resolve.
|
|
40
|
+
|
|
32
41
|
**Deliberately not copied:** upstream's `README.md` (the repo-facing readme: install
|
|
33
42
|
command and folder tree, nothing an agent reads). `AGENTS.md`, upstream's compiled
|
|
34
43
|
all-in-one copy, IS kept — `SKILL.md`'s closing section points the agent at it.
|
|
@@ -78,7 +78,7 @@ spring:
|
|
|
78
78
|
The `CircuitBreaker` filter needs a Spring Cloud CircuitBreaker starter (for example the reactor-Resilience4j one) on the classpath. Gateway is WebFlux; do not put it in the same module as a Spring MVC service.
|
|
79
79
|
|
|
80
80
|
## Observability
|
|
81
|
-
- Health: `/actuator/health/liveness` and `/actuator/health/readiness` are on by default (`management.endpoint.health.probes.enabled=false` disables them); point the Kubernetes probes at those. Expose only what you need (`management.endpoints.web.exposure.include`), and protect the rest.
|
|
81
|
+
- Health: `/actuator/health/liveness` and `/actuator/health/readiness` are on by default (`management.endpoint.health.probes.enabled=false` disables them); point the Kubernetes probes at those, and permit `/actuator/health/**` in the security chain. Expose only what you need (`management.endpoints.web.exposure.include`), and protect the rest. `management.endpoint.health.show-components: always` with `show-details: when-authorized` tells an anonymous caller which component is down without leaking hosts or versions.
|
|
82
82
|
- Metrics: add `micrometer-registry-prometheus` and expose `prometheus`.
|
|
83
83
|
- Traces over OTLP: add `org.springframework.boot:spring-boot-starter-opentelemetry` and configure `management.opentelemetry.tracing.export.otlp.endpoint` (the old `management.otlp.tracing.*` keys are not the Boot 4 names). Boot samples 10% by default; set `management.tracing.sampling.probability: 1.0` only where the volume allows.
|
|
84
84
|
- Custom spans: `Observation.createNotStarted("order.process", registry).lowCardinalityKeyValue(...).observe(() -> ...)` (Micrometer Observation, unchanged by Boot 4 as far as the docs show).
|
|
@@ -99,5 +99,23 @@ Add a short Kubernetes `preStop` sleep so the endpoint leaves the load balancer
|
|
|
99
99
|
- GraalVM native: fast start and low memory, at the cost of build time and reflection hints; adopt it deliberately, not by default.
|
|
100
100
|
- Use whatever CI the project already has; do not introduce a new one.
|
|
101
101
|
|
|
102
|
+
## Local dependencies
|
|
103
|
+
Give each Docker Compose dependency a healthcheck, and make the services that need it wait with `depends_on: { <dep>: { condition: service_healthy } }`; `docker compose up -d --wait` then also returns only once everything is usable. Write a shell check as `["CMD-SHELL", "<script>"]`, never `["CMD", "bash", "-c", "<script>"]`: Podman splits that array on spaces and reports the service healthy before it starts.
|
|
104
|
+
|
|
102
105
|
## Kubernetes manifest essentials
|
|
103
106
|
Liveness and readiness probes on the actuator paths, a startup probe for slow starts, resource requests and limits, `runAsNonRoot`, config from ConfigMap and Secret. For TLS, let the platform terminate it (Ingress plus cert-manager) or mount the certificate and use an SSL bundle ([spring-boot/security.md](security.md)).
|
|
107
|
+
|
|
108
|
+
No committed manifest names a cluster, host, registry, namespace or secret value: no `namespace:` (it comes from `-n`), the image is a bare name (Skaffold `--default-repo`), Secrets are referenced by name and created out of band.
|
|
109
|
+
|
|
110
|
+
Dependencies deployed in the same namespace get the same three probes, or a redeploy routes traffic to a pod that is not ready:
|
|
111
|
+
- PostgreSQL: `pg_isready -h 127.0.0.1` (over TCP: during the first `initdb` the server listens only on its socket), a fast startup probe; data on a PVC with `strategy: Recreate`, or every redeploy starts empty.
|
|
112
|
+
- Keycloak: `KC_HEALTH_ENABLED=true`, then `/health/started`, `/health/ready`, `/health/live` on management port 9000, not 8080.
|
|
113
|
+
|
|
114
|
+
Prove a new probe can fail: watch the service start and see Warning events before it is up (`kubectl get events --field-selector type=Warning`), with no restarts in the pods that depend on it.
|
|
115
|
+
|
|
116
|
+
## One set of manifests for several platforms
|
|
117
|
+
When one service deploys to a local cluster, plain Kubernetes and OpenShift, use Kustomize overlays (deployed with Skaffold or `kubectl -k`):
|
|
118
|
+
- `deploy/base` is plain Kubernetes, valid anywhere; `deploy/overlays/<platform>` adds only what that platform needs (Routes on OpenShift, Ingresses elsewhere); environment overlays with hosts and TLS stay out of git.
|
|
119
|
+
- Stay within the kustomize 3.8 features that Skaffold, `kubectl -k` and `oc -k` all support (`resources`, `patches`, generators); no `labels`, `replacements` or `components`.
|
|
120
|
+
- Selectors stay `app: <name>`: a selector cannot change after the first deploy.
|
|
121
|
+
- CI runs `kustomize build` on every overlay, so a broken patch fails the build, not the deploy.
|
|
@@ -41,8 +41,9 @@ log.error("Payment failed for order {}", order.id(), e); //
|
|
|
41
41
|
```
|
|
42
42
|
- Placeholders, never string concatenation. Guard only genuinely expensive arguments with `isDebugEnabled()`.
|
|
43
43
|
- Pass the exception as the final argument; do not log `e.getMessage()` alone.
|
|
44
|
-
- Log an exception once, where
|
|
45
|
-
-
|
|
44
|
+
- Log an exception once, where the flow ends (the exception handler, listener or job), not at every layer it passes through: a lower layer wraps it with context and rethrows, without logging. Expected business errors (404, validation) are `WARN` or `DEBUG` without a stack trace; only unexpected failures are `ERROR` with the throwable.
|
|
45
|
+
- For fields a log platform should filter on, use the SLF4J 2 fluent API: `log.atError().addKeyValue("orderId", id).setCause(e).log("Order processing failed")`. Boot's structured formats write each pair as a JSON field.
|
|
46
|
+
- Never log secrets, tokens, passwords, `Authorization` or `Cookie` headers, card data or personal data; log identifiers. A record prints every component in `toString()`: log its id, not the record, when it carries personal data. No full request or response bodies in production.
|
|
46
47
|
- Lombok's `@Slf4j` is fine where the project uses Lombok; otherwise declare the logger as above.
|
|
47
48
|
|
|
48
49
|
| Level | Meaning |
|
|
@@ -76,7 +77,7 @@ class MdcFilter extends OncePerRequestFilter {
|
|
|
76
77
|
}
|
|
77
78
|
```
|
|
78
79
|
|
|
79
|
-
MDC is thread-local, so it does not follow work handed to another thread (virtual or platform). For executor tasks, copy the context with a `TaskDecorator` (`MDC.getCopyOfContextMap()` before, `MDC.setContextMap(...)` inside the task, `MDC.clear()` in `finally`) and register it on the executor you use; check that Boot applies it to your executor in the version you run.
|
|
80
|
+
MDC is thread-local, so it does not follow work handed to another thread (virtual or platform). For executor tasks, copy the context with a `TaskDecorator` (`MDC.getCopyOfContextMap()` before, `MDC.setContextMap(...)` inside the task, `MDC.clear()` in `finally`) and register it on the executor you use; check that Boot applies it to your executor in the version you run. `CompletableFuture.supplyAsync(...)` without an executor runs on the common pool and loses MDC: always pass the Spring executor.
|
|
80
81
|
|
|
81
82
|
Useful fields for incident analysis: `requestId`, user or tenant id, and a duration on slow-path logs. Keep them to identifiers, not payloads.
|
|
82
83
|
|
|
@@ -86,4 +87,5 @@ Useful fields for incident analysis: `requestId`, user or tenant id, and a durat
|
|
|
86
87
|
| JSON console | `logging.structured.format.console: logstash` |
|
|
87
88
|
| Per-package level | `logging.level.com.example.orders: DEBUG` |
|
|
88
89
|
| Correlate a request | MDC `requestId` set in a filter |
|
|
90
|
+
| One event's fields as JSON | `log.atInfo().addKeyValue("k", v).log("msg")` |
|
|
89
91
|
| Follow one request in JSON logs | `jq 'select(.requestId == "abc")' app.log` (field name depends on MDC key and format) |
|
|
@@ -36,6 +36,8 @@ class UserController {
|
|
|
36
36
|
|
|
37
37
|
Version the path (`/api/v1`). Use GET for reads, POST/PUT/PATCH/DELETE for state changes; never change state on GET.
|
|
38
38
|
|
|
39
|
+
Paged lists return Spring Data's `org.springframework.data.web.PagedModel` (`{content, page}`; not the HATEOAS class of the same name): the JSON of `Page`/`PageImpl` is not a stable format and Spring Data warns when it serializes one. To get that shape for every `Page`, set `spring.data.web.pageable.serialization-mode: via-dto`, not `@EnableSpringDataWebSupport(pageSerializationMode = VIA_DTO)` on the application class: `@WebMvcTest` then registers the web support twice and fails. Cap the page size (`spring.data.web.pageable.max-page-size: 100`).
|
|
40
|
+
|
|
39
41
|
## DTOs and validation
|
|
40
42
|
Records for request and response. Constraints sit on the record components (`jakarta.validation.constraints`); `@Valid` on the controller parameter triggers them. Put the entity-to-DTO mapping in a static factory or a mapper, not in the controller.
|
|
41
43
|
|
|
@@ -46,7 +48,7 @@ public record UserCreateRequest(
|
|
|
46
48
|
@Min(18) Integer age) {}
|
|
47
49
|
```
|
|
48
50
|
|
|
49
|
-
A custom constraint is an annotation with `@Constraint(validatedBy = ...)` plus a `ConstraintValidator`; the validator may be a Spring bean and inject a repository. A uniqueness check in a validator is advisory only; the database constraint is the truth, so also handle `DataIntegrityViolationException` (409).
|
|
51
|
+
A custom constraint is an annotation with `@Constraint(validatedBy = ...)` plus a `ConstraintValidator`; the validator may be a Spring bean and inject a repository. A rule across two fields (a date range) is a class-level constraint that reports on one field (`context.buildConstraintViolationWithTemplate(...).addPropertyNode("to")`), so a client can show it next to the input. A uniqueness check in a validator is advisory only; the database constraint is the truth, so also handle `DataIntegrityViolationException` (409).
|
|
50
52
|
|
|
51
53
|
## Errors: Problem Details
|
|
52
54
|
Enable RFC 9457 responses for Spring's own exceptions:
|
|
@@ -73,10 +75,31 @@ class ApiExceptionHandler extends ResponseEntityExceptionHandler {
|
|
|
73
75
|
ProblemDetail conflict(DataIntegrityViolationException ex) {
|
|
74
76
|
return ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, "Resource already exists");
|
|
75
77
|
}
|
|
78
|
+
|
|
79
|
+
@ExceptionHandler(ObjectOptimisticLockingFailureException.class)
|
|
80
|
+
ProblemDetail staleVersion(ObjectOptimisticLockingFailureException ex) {
|
|
81
|
+
return ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, "Record was changed by someone else; reload and retry");
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
@ExceptionHandler(PropertyReferenceException.class) // ?sort=unknownProperty
|
|
85
|
+
ProblemDetail badSort(PropertyReferenceException ex) {
|
|
86
|
+
return ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, "Unknown sort property: " + ex.getPropertyName());
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
@ExceptionHandler({AccessDeniedException.class, AuthenticationException.class})
|
|
90
|
+
void security(RuntimeException ex) {
|
|
91
|
+
throw ex; // back to Spring Security: 403/401, not 500
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
@ExceptionHandler(Exception.class)
|
|
95
|
+
ProblemDetail unexpected(Exception ex) {
|
|
96
|
+
logger.error("Unexpected error", ex); // logged here, never returned
|
|
97
|
+
return ProblemDetail.forStatusAndDetail(HttpStatus.INTERNAL_SERVER_ERROR, "Unexpected server error");
|
|
98
|
+
}
|
|
76
99
|
}
|
|
77
100
|
```
|
|
78
101
|
|
|
79
|
-
A domain exception can carry its own problem by extending `ErrorResponseException
|
|
102
|
+
A domain exception can carry its own problem by extending `ErrorResponseException`; a plain `ResponseStatusException(NOT_FOUND, ...)` also renders as Problem Details with no extra handler. Never put stack traces, SQL text or an unexpected exception's message in `detail`. A catch-all on `Exception` also catches method-security failures, so rethrow `AccessDeniedException` and `AuthenticationException` before it, as above. To answer a duplicate with the field at fault, read `getConstraintName()` from the cause, `org.hibernate.exception.ConstraintViolationException`, and name constraints explicitly in migrations so that name is stable. Deleting a record that others still reference answers 409; it never cascades.
|
|
80
103
|
|
|
81
104
|
## Outbound HTTP
|
|
82
105
|
Blocking calls use `RestClient`; build it from the injected `RestClient.Builder` so Boot's customizers (timeouts, SSL, observability) apply.
|
|
@@ -109,4 +132,6 @@ Prefer one bean over scattered annotations. With Spring Security on the classpat
|
|
|
109
132
|
| Bad input | `@Valid` -> 400 Problem Details |
|
|
110
133
|
| Missing resource | 404 via your exception handler |
|
|
111
134
|
| Duplicate | 409 from the DB constraint |
|
|
135
|
+
| Stale update | 409 from `ObjectOptimisticLockingFailureException` |
|
|
136
|
+
| Unknown `sort` property | 400 from `PropertyReferenceException` |
|
|
112
137
|
| Slow upstream | `spring.http.clients.connect-timeout` / `read-timeout` |
|
|
@@ -21,7 +21,9 @@ Target stack: Spring Boot 4 / Spring Framework 7 / Spring Security 7 / Hibernate
|
|
|
21
21
|
- DTOs are records. JPA entities are not records. Never return an entity from a controller.
|
|
22
22
|
- `@Valid` on every request body; `@Transactional(readOnly = true)` on read services, `@Transactional` on mutating methods.
|
|
23
23
|
- Typed config: `@ConfigurationProperties` records instead of scattered `@Value`.
|
|
24
|
-
- Errors: one `@RestControllerAdvice`, Problem Details responses.
|
|
24
|
+
- Errors: one `@RestControllerAdvice`, Problem Details responses; the catch-all 500 never returns the exception message.
|
|
25
|
+
- List endpoints return `PagedModel`, never `Page`/`PageImpl` (their JSON is not a stable format).
|
|
26
|
+
- Relational database: the migration tool owns the schema, Hibernate only validates it (the spring-data-jpa skill).
|
|
25
27
|
- Blocking outbound HTTP: `RestClient`, or an `@HttpExchange` interface. `WebClient` only for reactive or streaming code. Do not mix blocking and reactive in one call path.
|
|
26
28
|
- Jakarta namespaces only (`jakarta.persistence`, `jakarta.validation`, `jakarta.servlet`).
|
|
27
29
|
- Secrets from the environment or mounted files, never committed config.
|
|
@@ -52,6 +54,6 @@ Removed or renamed in Boot 4 (do not write them): `@MockBean` and `@SpyBean`, `C
|
|
|
52
54
|
- **Logging and structured logs** -> read [spring-boot/logging.md](spring-boot/logging.md) and follow it.
|
|
53
55
|
|
|
54
56
|
## Done when
|
|
55
|
-
- The project's build and tests pass, read from real output; no deprecated Boot 2/3 idiom was introduced; every new endpoint validates input and has a negative test.
|
|
57
|
+
- The project's clean build and tests pass, read from real output (`./mvnw clean verify`: classes the IDE compiled into `target` can hide `javac` errors), with the integration tests run, not skipped (the spring-testing skill); no deprecated Boot 2/3 idiom was introduced; every new endpoint validates input and has a negative test.
|
|
56
58
|
|
|
57
59
|
<!-- INCLUDE: skills/_self-improvement.md -->
|
|
@@ -17,7 +17,9 @@ Target stack: Spring Boot 4, Hibernate 7, Jakarta Persistence (`jakarta.persiste
|
|
|
17
17
|
| N+1 SELECTs | `@EntityGraph(attributePaths = "books")` or `JOIN FETCH`; as a mitigation only, `hibernate.default_batch_fetch_size` (batch fetching mitigates N+1, it does not solve it) |
|
|
18
18
|
| `LazyInitializationException` | fetch what the use case needs inside the transaction (graph / `JOIN FETCH`) or return a DTO; do not flip associations to `EAGER` |
|
|
19
19
|
| Slow list endpoints | `Pageable` (`Slice` when no total is needed), interface or record projections, indexes |
|
|
20
|
-
| Lost updates | `@Version` (optimistic); `@Lock(LockModeType.PESSIMISTIC_WRITE)` only for hot rows |
|
|
20
|
+
| Lost updates | `@Version` (optimistic); `@Lock(LockModeType.PESSIMISTIC_WRITE)` only for hot rows; across HTTP requests compare the client's version explicitly (see Transactions) |
|
|
21
|
+
| 500 after a successful update of a relation | `LazyInitializationException` on a proxy: make the write `@Transactional` and map the response inside it |
|
|
22
|
+
| Entity lost from a `HashSet` after persist | `equals`/`hashCode` on a generated id: use a natural key, or a constant `hashCode` |
|
|
21
23
|
| Slow read-only service | `@Transactional(readOnly = true)` on the class, override on writes |
|
|
22
24
|
| Transaction ignored | self-invocation bypasses the proxy: call through another bean |
|
|
23
25
|
|
|
@@ -39,7 +41,9 @@ public class Author {
|
|
|
39
41
|
- Every to-one and to-many is `LAZY`; decide fetching per query, not on the mapping.
|
|
40
42
|
- `@SoftDelete(strategy = ...)` takes `ACTIVE`, `DELETED`, or `TIMESTAMP`; the default stores a deleted flag.
|
|
41
43
|
- `GenerationType.UUID` generates the id in Java; `IDENTITY` and `SEQUENCE` need the database.
|
|
42
|
-
- Equality on entities: id-based with a
|
|
44
|
+
- Equality on entities: a business key (`@NaturalId`), or id-based `equals` with a constant `hashCode` (for example `return 31;`) so the hash does not change when the id is assigned on persist. Use `instanceof`, not `getClass()`, in `equals`, and read the other side through `getId()`, not the field, so Hibernate proxies compare equal. Never include lazy collections in `equals`/`toString`.
|
|
45
|
+
- Bidirectional associations: helper methods (`addBook`/`removeBook`) keep both sides in sync. No cascade on the `@ManyToOne` side; `@ManyToMany` is a `Set` (a `List` deletes and re-inserts the whole join table) with `PERSIST`/`MERGE` only, never `REMOVE` or `ALL`. A link that carries data is its own entity.
|
|
46
|
+
- Audit timestamps are `Instant`, not `LocalDateTime`.
|
|
43
47
|
|
|
44
48
|
## Repositories and projections
|
|
45
49
|
|
|
@@ -58,18 +62,28 @@ public interface AuthorRepository extends JpaRepository<Author, UUID> {
|
|
|
58
62
|
```
|
|
59
63
|
|
|
60
64
|
- Interface projections are built from tuple queries; DTO records need an all-args constructor and no column aliases in `@Query` JPQL.
|
|
61
|
-
- Bulk `@Modifying` queries bypass the persistence context
|
|
65
|
+
- Bulk `@Modifying` queries bypass the persistence context, callbacks, cascades and `@Version`: `flushAutomatically = true` writes pending changes first, `clearAutomatically = true` detaches stale entities after; increment the version in the query (`set a.version = a.version + 1`) when concurrent writers rely on it.
|
|
66
|
+
- A `LIKE` built from user input escapes `%`, `_` and `\` (with `cb.like(expr, pattern, '\\')`), or `q=%` matches everything.
|
|
62
67
|
- Return DTOs from the web layer, never entities.
|
|
63
68
|
|
|
64
69
|
## Transactions and open-in-view
|
|
65
70
|
|
|
66
71
|
- Put `@Transactional` on service methods, not repositories or controllers.
|
|
67
72
|
- `spring.jpa.open-in-view` defaults to `true` in a web app (the EntityManager stays open through view rendering). Set it to `false` and fetch explicitly; it hides N+1 otherwise.
|
|
73
|
+
- With open-in-view off, a write that loads outside a transaction and then calls `save` merges a detached entity: a newly set `@ManyToOne` becomes an uninitialized proxy, and mapping the response throws after the commit. Load, change, save and map in one `@Transactional` method; read paths fetch the relation with `@EntityGraph`.
|
|
74
|
+
- Optimistic locking over HTTP: the client sends the `version` it read and the service compares it, then throws `ObjectOptimisticLockingFailureException` (409). Setting the version on a managed entity does not work, as Hibernate ignores it. Do not wrap `save()` in a `try/catch` inside the transaction: the `UPDATE` runs at flush or commit, after the block. Return the new version with `saveAndFlush`.
|
|
68
75
|
- Detect N+1: `spring.jpa.show-sql=true` is enough for a quick look; assert query counts in a `@DataJpaTest` for regressions.
|
|
69
76
|
|
|
70
77
|
## Migrations
|
|
71
78
|
|
|
72
|
-
Schema is owned by migrations, not `ddl-auto`: `spring.jpa.hibernate.ddl-auto=validate` (or `none`) with Flyway or Liquibase, whichever the project already uses. In Boot 4 add the starter (`spring-boot-starter-flyway`), not just the Flyway core jar, or auto-configuration does not apply; Postgres and MySQL also need `flyway-database-postgresql` / `flyway-mysql`.
|
|
79
|
+
Schema is owned by migrations, not `ddl-auto`: `spring.jpa.hibernate.ddl-auto=validate` (or `none`) with Flyway or Liquibase, whichever the project already uses. In Boot 4 add the starter (`spring-boot-starter-flyway`), not just the Flyway core jar, or auto-configuration does not apply; Postgres and MySQL also need `flyway-database-postgresql` / `flyway-mysql`. No persistence or NoSQL only: no migration tool at all.
|
|
80
|
+
|
|
81
|
+
- Migration files are immutable once applied; every change is a new `V<n>__<description>.sql`, shipped in the same commit as the entity change.
|
|
82
|
+
- Numeric database-generated ids are standard identity columns (`GENERATED BY DEFAULT AS IDENTITY`, `AUTO_INCREMENT` on MySQL), not `SERIAL`/`BIGSERIAL`.
|
|
83
|
+
- Name constraints and indexes (`pk_`, `uk_`, `fk_`, `ck_`, `ix_`) and index every foreign key column; the exception handler maps a unique violation by that name.
|
|
84
|
+
- A new `NOT NULL` column gets a `DEFAULT` or a backfill. Column defaults match entity defaults; validation rules get a matching `CHECK`.
|
|
85
|
+
- A database that predates the tool: export its schema as `V1`, or `spring.flyway.baseline-on-migrate: true`.
|
|
86
|
+
- Integration tests run the real migrations on the production engine and assert none is pending (`flyway.info().pending()` empty).
|
|
73
87
|
|
|
74
88
|
## Outbox, saga, CQRS
|
|
75
89
|
|
|
@@ -42,6 +42,8 @@ class UserControllerTests {
|
|
|
42
42
|
|
|
43
43
|
`MockMvcTester` is AssertJ-based (`assertThat(mvc.get().uri(...)).hasStatusOk()`); do not mix it with the `expectStatus()` chain, which belongs to the other clients. Security: `@WithMockUser` still works on slices; `@Import` your security config.
|
|
44
44
|
|
|
45
|
+
`@WebMvcTest` creates no services or repositories: every bean the controller injects needs a `@MockitoBean`, including a repository newly added to an existing controller. Assert error bodies as Problem Details fields (`$.status`, `$.title`; `$.errors[*].field` only when your handler adds an `errors` extension), never on message texts.
|
|
46
|
+
|
|
45
47
|
## Full-server test
|
|
46
48
|
|
|
47
49
|
```java
|
|
@@ -82,6 +84,8 @@ class AuthorRepositoryTests { /* ... */ }
|
|
|
82
84
|
- The default `replace = NON_TEST` already keeps a `@ServiceConnection` data source; `replace = NONE` is only needed for a non-test `DataSource` you defined yourself.
|
|
83
85
|
- Where `@ServiceConnection` has no support for the container, use `@Testcontainers` + `@Container static` + `@DynamicPropertySource` to register the properties.
|
|
84
86
|
- Share one container configuration across tests so the context cache is reused.
|
|
87
|
+
- `@Testcontainers(disabledWithoutDocker = true)` skips the class silently when no daemon answers: check the test report shows the integration tests as run. With Podman, point `DOCKER_HOST` at the Podman socket and set `TESTCONTAINERS_RYUK_DISABLED=true`.
|
|
88
|
+
- Beyond CRUD, the integration tests cover what a mocked slice cannot see: all migrations applied, a DB `CHECK` rejecting a bad row, none -> A, A -> B and A -> none for each relation a client can change, a stale `version` answering 409, a referenced delete answering 409 with the row still there.
|
|
85
89
|
|
|
86
90
|
## Rules
|
|
87
91
|
|
package/src/upstreams.json
CHANGED
|
@@ -8,21 +8,21 @@
|
|
|
8
8
|
},
|
|
9
9
|
"react-view-transitions": {
|
|
10
10
|
"repo": "vercel-labs/agent-skills",
|
|
11
|
-
"commit": "
|
|
11
|
+
"commit": "1a2c79d4e6c4a2283dc2c614b6538cbe1ed5ca62",
|
|
12
12
|
"author": "Vercel Engineering",
|
|
13
13
|
"license": "MIT",
|
|
14
14
|
"licenseFile": null
|
|
15
15
|
},
|
|
16
16
|
"diagram-design": {
|
|
17
17
|
"repo": "cathrynlavery/diagram-design",
|
|
18
|
-
"commit": "
|
|
18
|
+
"commit": "f6db0decea96de66b901331a0f79a8d4b147ebae",
|
|
19
19
|
"author": "Cathryn Lavery",
|
|
20
20
|
"license": "MIT",
|
|
21
21
|
"licenseFile": "skills/diagram-design/LICENSE"
|
|
22
22
|
},
|
|
23
23
|
"mattpocock-skills": {
|
|
24
24
|
"repo": "mattpocock/skills",
|
|
25
|
-
"commit": "
|
|
25
|
+
"commit": "5863806dd4e15c63174bee4e7515a4256792ecfa",
|
|
26
26
|
"author": "Matt Pocock",
|
|
27
27
|
"license": "MIT",
|
|
28
28
|
"licenseFile": "licenses/mattpocock-skills.txt"
|
|
@@ -58,7 +58,7 @@
|
|
|
58
58
|
},
|
|
59
59
|
"piomin-spring-boot": {
|
|
60
60
|
"repo": "piomin/claude-ai-spring-boot",
|
|
61
|
-
"commit": "
|
|
61
|
+
"commit": "647d768a5d333e15b6a50dc0e8fc41e41a330e92",
|
|
62
62
|
"author": "Piotr Mińkowski",
|
|
63
63
|
"license": "Apache-2.0",
|
|
64
64
|
"licenseFile": "licenses/piomin-spring-boot.txt"
|