@wildo-ai/framework-knowledge 1.1.6 → 1.1.8

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.
Files changed (25) hide show
  1. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
  2. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  3. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  4. package/dist/esm/framework-knowledge.definitions.js +1 -0
  5. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  6. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  7. package/dist/knowledge/manifest.json +7 -7
  8. package/dist/knowledge/references/presets.3d.focal-plane-settings.md +45 -0
  9. package/dist/knowledge/references/presets.3d.layout-contract.md +29 -7
  10. package/dist/knowledge/references/presets.3d.register-layout.md +5 -0
  11. package/dist/knowledge/references/saas.frontend.app-shell.building-blocks.md +7 -4
  12. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  13. package/dist/knowledge/registries/framework-topics.json +11 -1
  14. package/dist/knowledge/registries/playbooks.json +1 -1
  15. package/dist/knowledge/registries/source-tags.json +674 -656
  16. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-building-blocks-api.md +7 -4
  17. package/dist/knowledge/skills/layout-3d-adoption/SKILL.md +8 -4
  18. package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-focal-plane-settings-api.md +53 -0
  19. package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-layout-contract-api.md +29 -7
  20. package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-layout-registration-api.md +5 -0
  21. package/dist/knowledge/skills/layout-3d-adoption/references/framework-shell-building-blocks-api.md +7 -4
  22. package/dist/knowledge/skills/layout-3d-adoption/references/layouts-and-transitions.md +19 -5
  23. package/dist/knowledge/topic-index.json +41 -5
  24. package/dist/tsconfig.build.tsbuildinfo +1 -1
  25. package/package.json +4 -4
@@ -176,16 +176,19 @@ export function AppShellProviders({ layout, children }: AppShellProvidersProps):
176
176
  * are TRANSFORMED — a 3D placement. Render it once, inside the providers but OUTSIDE the transformed subtree; the
177
177
  * providers then prefer it to `<main>`. A layout that transforms nothing does not need it.
178
178
  *
179
- * It is a zero-size, untransformed, fixed box at the viewport's origin: an overlay positioned `fixed` resolves
180
- * against the viewport, one positioned `absolute` against the viewport's origin, so floating content lands where its
181
- * trigger is on screen. It carries the stacking tier overlays need above a layout's own layers.
179
+ * It is a zero-size, untransformed box at the shell root's origin (the root fills the viewport), with NO z-index and
180
+ * NOT `position: fixed`: either would make it a stacking context and cap every overlay inside it below anything
181
+ * positioned outside the shell — a consent prompt would paint over the shell's own dialogs (the reordering #1830
182
+ * measured and avoided). So each overlay keeps its own global z-index. An overlay positioned `fixed` still resolves
183
+ * against the viewport (nothing between it and the viewport is transformed), one positioned `absolute` against the
184
+ * root's origin, so floating content lands where its trigger is on screen. The layout's root must be positioned.
182
185
  */
183
186
  export function AppShellOverlayPortalLayer(): React.JSX.Element {
184
187
  const register = useContext(AppShellOverlayLayerTargetContext);
185
188
  if (!register) {
186
189
  throw new Error('AppShellOverlayPortalLayer must be rendered inside <AppShellProviders>, which exposes it as the portal container.');
187
190
  }
188
- return <div ref={register} data-shell-overlay-layer="" className="fixed left-0 top-0 z-50 h-0 w-0" />;
191
+ return <div ref={register} data-shell-overlay-layer="" className="absolute left-0 top-0 h-0 w-0" />;
189
192
  }
190
193
 
191
194
  /**
@@ -57,8 +57,9 @@ browser console.
57
57
  ### Step 1: Choose the layout
58
58
 
59
59
  Read `references/layouts-and-transitions.md`. `INHERIT_LAYOUT_3D` keeps the application's arrangement;
60
- `HEADER_FIRST_LAYOUT_3D` spans the menubar and status bars across the width. Each plays its own transitions on
61
- navigation and on sidebar collapse, and rims the focused zone of a split. An application uses one layout for its life.
60
+ `HEADER_FIRST_LAYOUT_3D` spans the menubar and status bars across the width; both draw a frame behind flat regions.
61
+ `FOCAL_PLANE_LAYOUT_3D` moves the panes and popups themselves in depth under one still camera, as glass windows. An
62
+ application uses one layout for its life.
62
63
 
63
64
  ### Step 2: Adopt it with one command
64
65
 
@@ -80,7 +81,9 @@ paint the regions transparent one by one.
80
81
 
81
82
  ### Step 4: Tune or author (optional)
82
83
 
83
- - Frame look: pass `frameStyles` (`references/framework-3d-frame-style-overrides-api.md`).
84
+ - Frame look (flat-frame layouts): pass `frameStyles` (`references/framework-3d-frame-style-overrides-api.md`).
85
+ - Focal-plane numbers (camera distance, layer depth, motion, dims, blurs, window opacity): pass `focalPlane`
86
+ (`references/framework-3d-focal-plane-settings-api.md`).
84
87
  - Own layout: spread a built-in with an `id` of its own (`references/framework-3d-layout-contract-api.md`); for an
85
88
  arrangement of its own, a `COMPOSED` placement built from `references/framework-shell-building-blocks-api.md`.
86
89
 
@@ -135,6 +138,7 @@ export const calmRegistrations: FrontendComponentRegistration[] = [register3DLay
135
138
  - `references/framework-3d-layout-registration-api.md` — `register3DLayout`, its options and its refusals
136
139
  - `references/framework-3d-layout-contract-api.md` — the layout contract, the built-ins and the transition vocabularies
137
140
  - `references/framework-3d-frame-style-overrides-api.md` — the frame styles an application may override
141
+ - `references/framework-3d-focal-plane-settings-api.md` — the focal plane's numbers and their checked ranges
138
142
  - `references/framework-shell-region-marker-api.md` — the marker the frame finds each region by
139
143
  - `references/framework-shell-building-blocks-api.md` — the building blocks a composed layout is made from
140
144
 
@@ -157,7 +161,7 @@ export const calmRegistrations: FrontendComponentRegistration[] = [register3DLay
157
161
  | Rationalization | Reality |
158
162
  |---|---|
159
163
  | "Add a toggle so people can pick 2D or 3D" | There is no dual mode: an application is 3D because it adopted the library. A switch would be a second product to maintain and test. |
160
- | "Tilt the sidebar a little at rest for more depth" | No region is ever transformed: a transform blurs text and misplaces popovers opened from it. All depth is drawn behind the regions. |
164
+ | "Tilt the sidebar a little at rest for more depth" | Nothing is ever angled. The flat-frame layouts draw all depth behind the regions; the focal plane moves objects straight toward or away from the camera, and whatever you work with rests at its true size. |
161
165
  | "Make the sidebar background transparent so the frame shows" | Painting regions one by one fights the theme. The theme's `shellAppearance` must be CONTINUOUS. |
162
166
  | "Register the header-first layout next to the inherit one and pick at runtime" | One layout per application; a second, different registration is refused at start-up. |
163
167
  | "Load a nice HDR environment from a CDN" | The library bundles everything and fetches nothing remote: a third-party fetch breaks the content security policy and adds a data recipient. |
@@ -0,0 +1,53 @@
1
+ # Framework Focal Plane Settings API
2
+
3
+ The numbers of the focal-plane layout (`FOCAL_PLANE_LAYOUT_3D`): how far the still camera stands from the focal
4
+ plane, how far a layer steps back, how long an object travels, how much a receding object dims and blurs, how much
5
+ everything blurs behind a modal popup, and how opaque a glass window is. The defaults are the values the layout was
6
+ designed with; pass only what you change.
7
+
8
+ Read this when you pass `focalPlane` to `register3DLayout`. Each value is checked at registration: an unknown key or
9
+ a value outside its range is refused with a message naming it.
10
+
11
+ ## Import Origins
12
+
13
+ - `@wildo-ai/presets-components-3d`
14
+
15
+ ## Source Excerpts
16
+
17
+ ### Origin Package: `@wildo-ai/presets-components-3d`
18
+
19
+ ```typescript
20
+ /**
21
+ * The focal plane's numbers (#2049). The defaults are the values Paul settled on in the prototype on 2026-09-30.
22
+ * They reach the stylesheet as CSS custom properties on the layout's root, so every object reads one source.
23
+ */
24
+ export interface FocalPlaneSettings {
25
+ /** The still camera's distance from the focal plane, in CSS pixels: the `perspective()` every object is seen through. */
26
+ cameraDistancePx: number;
27
+ /** How far back one layer steps, in CSS pixels. A pane behind the focused one steps back part of it. */
28
+ layerDepthPx: number;
29
+ /** How long an object takes to travel, in milliseconds. */
30
+ motionMs: number;
31
+ /** How much a receding object dims per layer, 0-1. */
32
+ recedeDim: number;
33
+ /** How much a receding PANE blurs per layer, in CSS pixels (navigation; 0 keeps panes sharp). */
34
+ recedeBlurPx: number;
35
+ /** How much everything blurs behind a MODAL popup (dialog, sheet, command palette), in CSS pixels. */
36
+ modalBlurPx: number;
37
+ /** How opaque a glass window is, 0-1: the rest is the background blurred through it. */
38
+ windowOpacity: number;
39
+ /** How far a shell panel rises toward the camera under the pointer, in CSS pixels. */
40
+ hoverLiftPx: number;
41
+ }
42
+
43
+ export const FOCAL_PLANE_DEFAULTS: FocalPlaneSettings = {
44
+ cameraDistancePx: 1000,
45
+ layerDepthPx: 240,
46
+ motionMs: 580,
47
+ recedeDim: 0.18,
48
+ recedeBlurPx: 0,
49
+ modalBlurPx: 2.5,
50
+ windowOpacity: 0.56,
51
+ hoverLiftPx: 16,
52
+ };
53
+ ```
@@ -74,6 +74,23 @@ export const HEADER_FIRST_LAYOUT_3D: Layout3DDefinition = {
74
74
  },
75
75
  constraints: { requiredShellAppearance: ShellAppearance.CONTINUOUS, restPose: Layout3DRestPose.FLAT },
76
76
  };
77
+ /**
78
+ * The focal plane (#2049): the shell regions, each navigation pane and each popup are glass objects in depth under one
79
+ * still camera. Whatever you work with rests on the focal plane; the rest steps back. No WebGL frame: the depth is in
80
+ * the HTML objects themselves, so the frame styles and frame transitions below are not drawn.
81
+ */
82
+ export const FOCAL_PLANE_LAYOUT_3D: Layout3DDefinition = {
83
+ id: Layout3DId.FOCAL_PLANE,
84
+ placement: { kind: ShellLayoutPlacementKind.COMPOSED, container: FocalPlaneShellContainer },
85
+ scene: { camera: Layout3DCamera.STILL_PERSPECTIVE, frameStyles: INHERIT_FRAME_STYLES },
86
+ transitions: {
87
+ appearance: Layout3DAppearanceTransition.CROSS_FADE,
88
+ navigation: Layout3DFrameChoreography.NONE,
89
+ sidebarResize: Layout3DFrameChoreography.NONE,
90
+ zoneFocus: Layout3DZoneFocusTransition.NONE,
91
+ },
92
+ constraints: { requiredShellAppearance: ShellAppearance.CONTINUOUS, restPose: Layout3DRestPose.FLAT },
93
+ };
77
94
  ```
78
95
 
79
96
  ### Origin Package: `@wildo-ai/presets-components-3d`
@@ -91,22 +108,27 @@ export enum Layout3DId {
91
108
  * panel) sit between them, beside the content. The default disposal is sidebar-first; this one is header-first.
92
109
  */
93
110
  HEADER_FIRST = 'header-first',
111
+ /**
112
+ * The focal plane (#2049): one still perspective camera; the shell regions, each navigation pane and each popup are
113
+ * separate glass objects that travel in depth. Whatever you work with rests on the focal plane at its true size;
114
+ * everything else steps back. Nothing is angled and the camera never moves (Paul, 2026-09-30).
115
+ */
116
+ FOCAL_PLANE = 'focal-plane',
94
117
  }
95
118
 
96
119
  /**
97
- * The cameras the frame renderer supports. The transitions need none beyond this one: every choreography is
98
- * drawn IN the flat frame (elevation, light, rims), so a slab never leaves its region's box.
120
+ * The cameras a 3D layout is seen through. The flat camera's transitions are all drawn IN the flat frame (elevation,
121
+ * light, rims), so a slab never leaves its region's box; the still-perspective camera moves the HTML objects instead.
99
122
  */
100
123
  export enum Layout3DCamera {
101
124
  /** Orthographic, matched 1:1 to CSS pixels: the frame lies flat under the regions, exactly on their boxes. */
102
125
  FLAT_ORTHOGRAPHIC = 'flat-orthographic',
103
126
  /**
104
- * PROTOTYPE (Paul, 2026-09-30: "a real camera aspect", clean spatial). A perspective camera looks at the shell's
105
- * panels placed in space: the content faces it (crisp at rest), side columns stand angled, and the camera MOVES on
106
- * transitions. The panels are the live HTML, in a CSS 3D stage driven by the same camera as the WebGL environment
107
- * around them. Only a placement that builds that stage can use it (`SPATIAL_PROTOTYPE_LAYOUT_3D`).
127
+ * A still perspective camera, in CSS: the HTML objects themselves carry depth, around one shared vanishing point, and
128
+ * no WebGL frame is drawn. The camera never moves; objects do (#2049). Only a placement that stages the objects can
129
+ * be seen through it.
108
130
  */
109
- SPATIAL_PERSPECTIVE = 'spatial-perspective',
131
+ STILL_PERSPECTIVE = 'still-perspective',
110
132
  }
111
133
 
112
134
  /**
@@ -26,6 +26,11 @@ export interface Layout3DOptions {
26
26
  layout?: Layout3DDefinition;
27
27
  /** Frame-style overrides layered over the layout's built-in styles. */
28
28
  frameStyles?: Frame3DStyleOverrides;
29
+ /**
30
+ * Overrides of the focal plane's numbers (camera distance, layer depth, motion, dims, blurs, window opacity), for
31
+ * {@link FOCAL_PLANE_LAYOUT_3D}; each is checked at registration. Omitted, the defaults.
32
+ */
33
+ focalPlane?: Partial<FocalPlaneSettings>;
29
34
  }
30
35
  ```
31
36
 
@@ -156,16 +156,19 @@ export function AppShellProviders({ layout, children }: AppShellProvidersProps):
156
156
  * are TRANSFORMED — a 3D placement. Render it once, inside the providers but OUTSIDE the transformed subtree; the
157
157
  * providers then prefer it to `<main>`. A layout that transforms nothing does not need it.
158
158
  *
159
- * It is a zero-size, untransformed, fixed box at the viewport's origin: an overlay positioned `fixed` resolves
160
- * against the viewport, one positioned `absolute` against the viewport's origin, so floating content lands where its
161
- * trigger is on screen. It carries the stacking tier overlays need above a layout's own layers.
159
+ * It is a zero-size, untransformed box at the shell root's origin (the root fills the viewport), with NO z-index and
160
+ * NOT `position: fixed`: either would make it a stacking context and cap every overlay inside it below anything
161
+ * positioned outside the shell — a consent prompt would paint over the shell's own dialogs (the reordering #1830
162
+ * measured and avoided). So each overlay keeps its own global z-index. An overlay positioned `fixed` still resolves
163
+ * against the viewport (nothing between it and the viewport is transformed), one positioned `absolute` against the
164
+ * root's origin, so floating content lands where its trigger is on screen. The layout's root must be positioned.
162
165
  */
163
166
  export function AppShellOverlayPortalLayer(): React.JSX.Element {
164
167
  const register = useContext(AppShellOverlayLayerTargetContext);
165
168
  if (!register) {
166
169
  throw new Error('AppShellOverlayPortalLayer must be rendered inside <AppShellProviders>, which exposes it as the portal container.');
167
170
  }
168
- return <div ref={register} data-shell-overlay-layer="" className="fixed left-0 top-0 z-50 h-0 w-0" />;
171
+ return <div ref={register} data-shell-overlay-layer="" className="absolute left-0 top-0 h-0 w-0" />;
169
172
  }
170
173
 
171
174
  /**
@@ -1,22 +1,36 @@
1
1
  # Choosing a 3D Layout
2
2
 
3
3
  An application uses ONE layout for its whole life. Every layout keeps the regions as the application's existing
4
- HTML; only their arrangement and what is drawn behind them differ.
4
+ HTML, with every context; the layouts differ in how they arrange them and where the depth is.
5
+
6
+ - The **flat-frame** layouts (`INHERIT_LAYOUT_3D`, `HEADER_FIRST_LAYOUT_3D`) draw a WebGL frame BEHIND flat regions;
7
+ no region ever moves.
8
+ - The **focal plane** (`FOCAL_PLANE_LAYOUT_3D`) moves the regions themselves in depth, under one still camera: the
9
+ shell panels, each navigation pane and each popup are glass objects, and whatever you work with rests on the focal
10
+ plane at its true size while everything else steps back. Nothing is ever angled, and the camera never moves.
5
11
 
6
12
  | Layout | Arrangement | On navigation | On sidebar collapse or expand | Focused zone of a split |
7
13
  |---|---|---|---|---|
8
14
  | `INHERIT_LAYOUT_3D` (default) | the application's own 2D arrangement, unchanged | the content panel lifts toward the reader and settles | the light swings across the frame and back | a rim around the focused zone |
9
15
  | `HEADER_FIRST_LAYOUT_3D` | menubar and status bars span the full width; the navigation rails sit between them, beside the content | the light swings from the header and returns | the content panel lifts and settles | a rim around the focused zone |
16
+ | `FOCAL_PLANE_LAYOUT_3D` | floating glass windows over an ambient background, with margins and gaps | a pane that changes place dips back and returns; a pane that opens arrives from depth; a discarded pane flies away | the column dips back while the panes re-arrange | the pane you work in rests on the focal plane; the other steps back and dims |
17
+
18
+ The focal plane also moves popups: a menu lifts off its trigger, a dialog (the command palette is one) rises from
19
+ depth, a sheet arrives from in front, and behind a modal popup everything steps back and blurs lightly. An expanded
20
+ pane stands in front of a still image of the panes it hides; the pane's restore control (or Escape) returns to side
21
+ by side. Tune its
22
+ numbers with `focalPlane` (see `framework-3d-focal-plane-settings-api.md`).
10
23
 
11
24
  ## What every layout guarantees
12
25
 
13
26
  | Guarantee | Why it matters |
14
27
  |---|---|
15
- | No region is ever moved, scaled or tilted — all motion is drawn behind the regions | a transform blurs text and misplaces popovers and dialogs opened from the region |
16
- | Text stays at or above 4.5:1 contrast over the frame, in every theme and during every transition | the library weakens a style rather than the minimum |
17
- | Reduced motion plays no transition at all | the frame is static under the reader's setting |
28
+ | Flat-frame layouts: no region is ever moved, scaled or tilted — all motion is drawn behind the regions | a transform blurs text and misplaces popovers and dialogs opened from the region |
29
+ | Focal plane: whatever you work with rests at its true size and faces the camera; popups render on a layer outside every moved object | text stays crisp where you read it, and a dialog or menu is placed and stacked exactly as in 2D |
30
+ | Flat-frame layouts: text stays at or above 4.5:1 contrast over the frame, in every theme and during every transition | the library weakens a style rather than the minimum |
31
+ | Reduced motion plays no transition at all | nothing travels under the reader's setting; the focal plane still shows depth, instantly |
18
32
  | The frame costs nothing while nothing moves | it redraws only when a region moved or a transition runs |
19
- | A browser without WebGL shows the application without the frame | the frame is decoration; every region keeps working |
33
+ | A browser without WebGL shows the application without the frame | the frame is decoration; every region keeps working (the focal plane needs no WebGL at all) |
20
34
 
21
35
  ## When to author your own layout
22
36
 
@@ -6615,6 +6615,7 @@
6615
6615
  "referenceFiles": [],
6616
6616
  "skillFiles": [
6617
6617
  "layout-3d-adoption/SKILL.md",
6618
+ "layout-3d-adoption/references/framework-3d-focal-plane-settings-api.md",
6618
6619
  "layout-3d-adoption/references/framework-3d-frame-style-overrides-api.md",
6619
6620
  "layout-3d-adoption/references/framework-3d-layout-contract-api.md",
6620
6621
  "layout-3d-adoption/references/framework-3d-layout-registration-api.md",
@@ -8577,6 +8578,41 @@
8577
8578
  "framework-topics"
8578
8579
  ]
8579
8580
  },
8581
+ {
8582
+ "topicId": "presets.3d.focal-plane-settings",
8583
+ "title": "Presets 3d Focal Plane Settings",
8584
+ "tags": [
8585
+ "presets",
8586
+ "3d",
8587
+ "focal-plane-settings"
8588
+ ],
8589
+ "facets": [
8590
+ "audience:app-developer",
8591
+ "family:layout-3d",
8592
+ "layer:frontend"
8593
+ ],
8594
+ "categories": [
8595
+ "presets",
8596
+ "presets.3d"
8597
+ ],
8598
+ "sourceReferences": [
8599
+ {
8600
+ "kind": "part-range",
8601
+ "tagName": "presets.3d.focal-plane-settings",
8602
+ "filePath": "engine/presets-components-3d/src/focal-plane/focal-plane-settings.ts",
8603
+ "startLine": 3,
8604
+ "endLine": 37
8605
+ }
8606
+ ],
8607
+ "referenceFiles": [
8608
+ "presets.3d.focal-plane-settings.md"
8609
+ ],
8610
+ "skillFiles": [],
8611
+ "registryKeys": [
8612
+ "source-tags",
8613
+ "framework-topics"
8614
+ ]
8615
+ },
8580
8616
  {
8581
8617
  "topicId": "presets.3d.frame-style-overrides",
8582
8618
  "title": "Presets 3d Frame Style Overrides",
@@ -8635,14 +8671,14 @@
8635
8671
  "tagName": "presets.3d.layout-contract",
8636
8672
  "filePath": "engine/presets-components-3d/src/layout/layout-3d-definition.ts",
8637
8673
  "startLine": 18,
8638
- "endLine": 74
8674
+ "endLine": 91
8639
8675
  },
8640
8676
  {
8641
8677
  "kind": "part-range",
8642
8678
  "tagName": "presets.3d.layout-contract",
8643
8679
  "filePath": "engine/presets-components-3d/src/layout/layout-3d-vocabulary.ts",
8644
8680
  "startLine": 6,
8645
- "endLine": 124
8681
+ "endLine": 129
8646
8682
  },
8647
8683
  {
8648
8684
  "kind": "part-range",
@@ -8683,8 +8719,8 @@
8683
8719
  "kind": "part-range",
8684
8720
  "tagName": "presets.3d.register-layout",
8685
8721
  "filePath": "engine/presets-components-3d/src/layout-3d-main-container.tsx",
8686
- "startLine": 22,
8687
- "endLine": 33
8722
+ "startLine": 23,
8723
+ "endLine": 39
8688
8724
  },
8689
8725
  {
8690
8726
  "kind": "part-range",
@@ -11922,7 +11958,7 @@
11922
11958
  "tagName": "saas.frontend.app-shell.building-blocks",
11923
11959
  "filePath": "engine/saas-frontend-lib/src/core/app-shell/AppShellBuildingBlocks.tsx",
11924
11960
  "startLine": 23,
11925
- "endLine": 262
11961
+ "endLine": 265
11926
11962
  }
11927
11963
  ],
11928
11964
  "referenceFiles": [