@floegence/floe-webapp-init 0.35.17 → 0.35.19

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 (7) hide show
  1. package/package.json +1 -1
  2. package/skills/floe-webapp/SKILL.md +65 -18
  3. package/skills/floe-webapp/references/playbooks.md +101 -48
  4. package/templates/full/skills/floe-webapp/SKILL.md +65 -18
  5. package/templates/full/skills/floe-webapp/references/playbooks.md +101 -48
  6. package/templates/minimal/skills/floe-webapp/SKILL.md +65 -18
  7. package/templates/minimal/skills/floe-webapp/references/playbooks.md +101 -48
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@floegence/floe-webapp-init",
3
- "version": "0.35.17",
3
+ "version": "0.35.19",
4
4
  "type": "module",
5
5
  "description": "Scaffolding tool for Floe Webapp applications",
6
6
  "repository": {
package/skills/floe-webapp/SKILL.md CHANGED
@@ -1,30 +1,72 @@
1
1
  ---
2
2
  name: floe-webapp
3
- description: Implement, refactor, and debug Floe-Webapp Solid.js applications with @floegence/floe-webapp-core public exports. Use for FloeApp shell wiring, FloeComponent sidebar or command registration, lifecycle hooks, design-token-first styling, and build or typecheck failures in Floe-Webapp projects.
3
+ description: Implement, refactor, and debug Floe-Webapp apps and this monorepo using only public @floegence/floe-webapp-core exports. Use for FloeApp or FloeRegistryRuntime wiring, component registry flows, interaction-architecture guardrails, design-token-first styling, and local CI or verify failures.
4
4
  ---
5
5
 
6
6
  # Floe-Webapp Skill
7
7
 
8
8
  ## Scope
9
9
 
10
- - Implement or refactor pages/components in a Floe-Webapp app.
11
- - Add or update `FloeComponent` registration (`sidebar`, `commands`, lifecycle hooks).
12
- - Diagnose framework-usage issues and local build/lint/typecheck/test failures.
10
+ - Implement or refactor repo workspace packages/apps and scaffolded Floe-Webapp apps.
11
+ - Add or update registry-driven navigation (`FloeComponent`, `commands`, `statusBar`, lifecycle hooks, app-level command contributions).
12
+ - Diagnose framework-usage issues and local lint/typecheck/test/build/verify failures.
13
13
 
14
14
  ## Required Inputs
15
15
 
16
16
  - Read project-root `AGENTS.md` first when available.
17
17
  - If `AGENTS.md` is absent, read `README.md` and `docs/getting-started.md`.
18
+ - Read the closest source-of-truth docs for the task:
19
+ - `docs/component-registry.md` for registry/runtime/commands/lifecycle guidance.
20
+ - `docs/interaction-architecture.md` for UI-first, overlay, drag/resize, and hot-path rules.
21
+ - `docs/configuration.md`, `docs/protocol.md`, and `docs/runtime.md` when config, protocol, or boot behavior is involved.
18
22
  - Load [references/playbooks.md](references/playbooks.md) and pick the closest playbook for the task.
19
23
 
20
24
  ## Execution Protocol
21
25
 
22
- 1. Verify package versions in `package.json` and lockfile before using any API surface.
23
- 2. Locate entry points and registration flow (`src/App.tsx`, component modules, command handlers).
24
- 3. Implement using only public exports from `@floegence/floe-webapp-core` (`/app`, `/ui`, `/layout`, `/icons`, root).
25
- 4. Align `FloeComponent.id`, sidebar items, and command navigation targets.
26
- 5. Keep styling on design tokens (`text-foreground`, `bg-card`, `border-border`, etc.).
27
- 6. Run deterministic checks before finishing:
26
+ 1. Verify package versions in `package.json` and the lockfile before using any API surface.
27
+ 2. Classify the target shape before editing:
28
+ - Repo workspace: `apps/*/src/App.tsx`, `apps/*/src/**/*`, `packages/*/src/**/*`, `packages/init/templates/**/*`.
29
+ - Scaffolded app: `src/App.tsx`, `src/**/*`.
30
+ 3. Use only public exports declared by `@floegence/floe-webapp-core` package exports. Current official surfaces:
31
+ - `@floegence/floe-webapp-core`
32
+ - `@floegence/floe-webapp-core/app`
33
+ - `@floegence/floe-webapp-core/full`
34
+ - `@floegence/floe-webapp-core/layout`
35
+ - `@floegence/floe-webapp-core/deck`
36
+ - `@floegence/floe-webapp-core/ui`
37
+ - `@floegence/floe-webapp-core/icons`
38
+ - `@floegence/floe-webapp-core/loading`
39
+ - `@floegence/floe-webapp-core/launchpad`
40
+ - `@floegence/floe-webapp-core/file-browser`
41
+ - `@floegence/floe-webapp-core/chat`
42
+ - `@floegence/floe-webapp-core/editor`
43
+ - `@floegence/floe-webapp-core/widgets`
44
+ - `@floegence/floe-webapp-core/terminal`
45
+ - `@floegence/floe-webapp-core/styles`
46
+ - `@floegence/floe-webapp-core/tailwind`
47
+ 4. Align registry behavior end-to-end:
48
+ - Keep `FloeComponent.id`, sidebar items, command targets, and layout navigation consistent.
49
+ - Use `ActivityAppsMain` for `sidebar.fullScreen` or `sidebar.renderIn === 'main'` page flows when appropriate.
50
+ - Use `FloeRegistryRuntime` when a custom shell is required but registry lifecycle still needs symmetric register/mount/cleanup behavior.
51
+ 5. Follow current interaction guardrails:
52
+ - UI first: let the visual state update before heavier work.
53
+ - Reuse `deferAfterPaint()` or `deferNonBlocking()` for deferred host logic.
54
+ - Reuse `useOverlayMask()` for overlays.
55
+ - Reuse `startHotInteraction()` and preview/commit separation for drag or resize flows.
56
+ 6. Keep styling on design tokens and official CSS entrypoints:
57
+ - Preferred: `@floegence/floe-webapp-core/tailwind`
58
+ - Fallback: `@floegence/floe-webapp-core/styles`
59
+ 7. When editing this repo's skill package, treat `skills/floe-webapp/*` as the source of truth and sync these mirrors before finishing:
60
+ - `packages/init/skills/floe-webapp/*`
61
+ - `packages/init/templates/full/skills/floe-webapp/*`
62
+ - `packages/init/templates/minimal/skills/floe-webapp/*`
63
+ 8. Run deterministic checks before finishing:
64
+
65
+ ```bash
66
+ make check
67
+ ```
68
+
69
+ If `make check` is unavailable in a downstream app, run:
28
70
 
29
71
  ```bash
30
72
  pnpm lint
@@ -33,21 +75,25 @@ pnpm test -- --run
33
75
  pnpm build
34
76
  ```
35
77
 
78
+ When editing this repository, `make check` already includes `pnpm verify`; if you run commands individually, include `pnpm verify` before finishing.
79
+
36
80
  ## Constraints
37
81
 
38
- - Solid.js only: do not use React hooks/patterns.
82
+ - Solid.js only: do not use React hooks or React component patterns.
39
83
  - Use `class=` in JSX, not `className=`.
40
84
  - Do not import `@floegence/floe-webapp-core/src/...` internal paths.
41
85
  - Keep command navigation ids aligned with registered component ids.
42
- - Prefer Solid control flow in JSX (`<For>`, `<Show>`, `<Switch>/<Match>`).
43
- - If API behavior is unclear, inspect installed type declarations before guessing.
86
+ - Prefer Solid control flow in JSX (`<For>`, `<Show>`, `<Switch>/<Match>`) when it improves clarity.
87
+ - Respect component-registry lifecycle symmetry (`registerAll()` cleanup, `onMount`, `onUnmount`) and use `useCommandContributions()` for app-level command groups not tied to a `FloeComponent`.
88
+ - If API behavior is unclear, inspect installed type declarations and the relevant public docs before guessing.
44
89
 
45
90
  ## Mobile Compatibility
46
91
 
47
92
  - Treat mobile as first-class behavior, not a fallback.
48
93
  - For sidebar components that should not appear on small screens, set `sidebar.hiddenOnMobile: true`.
94
+ - Keep `sidebar.fullScreen`, `sidebar.renderIn`, and `sidebar.collapseBehavior` aligned with the intended mobile/desktop navigation behavior.
49
95
  - Ensure primary navigation actions remain reachable on small screens (top bar or mobile tab bar paths).
50
- - Avoid hover-only interactions; provide click/tap equivalent behavior.
96
+ - Avoid hover-only interactions; provide click or tap equivalents.
51
97
  - Avoid fixed-width layouts that can overflow narrow viewports.
52
98
  - Keep interactive targets comfortably tappable (buttons, menu items, toggles).
53
99
  - Validate behavior at common widths before finishing:
@@ -56,21 +102,22 @@ pnpm build
56
102
  - Tablet: `768x1024`
57
103
  - Desktop: `>=1280px`
58
104
 
59
- ## Styling Guidelines
105
+ ## Styling And Interaction Guidelines
60
106
 
61
107
  - Use design tokens for color, border, and background (`text-*`, `bg-*`, `border-*` token classes).
62
108
  - Avoid raw hex colors and ad-hoc opacity values unless product requirements explicitly demand them.
63
109
  - Keep spacing and sizing on a consistent scale (`gap-*`, `p-*`, `m-*`, `rounded-*`).
64
110
  - Ensure readable contrast in both light and dark themes.
65
111
  - Define clear interactive states for controls (default, hover, active, focus, disabled).
66
- - Keep motion subtle and optional; avoid animations that block core interaction.
112
+ - Keep motion subtle and optional; do not reintroduce hot-path geometry transitions that violate `docs/interaction-architecture.md`.
67
113
  - When introducing new visual patterns, keep them consistent across pages and components.
68
114
 
69
115
  ## Failure Handling
70
116
 
71
- - If checks fail, report the exact failing command and first actionable error.
117
+ - If checks fail, report the exact failing command and the first actionable error.
72
118
  - Fix root causes instead of adding compatibility shims for old code paths.
73
- - If task requires risky incompatible behavior change, stop and ask for confirmation.
119
+ - If `pnpm verify` fails on skill drift, sync the root skill package and mirrors instead of patching only one copy.
120
+ - If the task requires a risky incompatible behavior change, stop and ask for confirmation.
74
121
 
75
122
  ## Output Format
76
123
 
package/skills/floe-webapp/references/playbooks.md CHANGED
@@ -2,85 +2,138 @@
2
2
 
3
3
  Use this file after reading `../SKILL.md`.
4
4
 
5
- ## Playbook A: Add Or Update A FloeComponent
5
+ ## Playbook A: Choose The Right Workspace Surface
6
6
 
7
- 1. Find the registration list:
7
+ 1. Classify the target before editing:
8
8
 
9
9
  ```bash
10
- rg "const components|FloeComponent\\[]" src --hidden
10
+ if [ -d apps ] || [ -d packages ]; then
11
+ printf 'repo workspace\n'
12
+ find apps packages -maxdepth 3 -type f 2>/dev/null | sort | sed -n '1,200p'
13
+ fi
14
+ if [ -d src ]; then
15
+ printf '\nscaffolded app\n'
16
+ find src -maxdepth 3 -type f | sort | sed -n '1,200p'
17
+ fi
11
18
  ```
12
19
 
13
- 2. Keep every component entry aligned:
14
- - Stable `id` string.
15
- - `sidebar` metadata (`order`, `renderIn`, `fullScreen`, optional `badge`).
16
- - `commands` targets using the same `id`.
17
-
18
- 3. Validate shell wiring still renders through:
19
- - `FloeApp`
20
- - `ActivityAppsMain`
21
-
22
- ## Playbook B: Add Command Navigation
23
-
24
- 1. Search command contribution points:
20
+ 2. Use repo-workspace searches for this monorepo:
25
21
 
26
22
  ```bash
27
- rg "commands|useCommand|command" src --hidden
23
+ rg "FloeApp|FloeRegistryRuntime|const components|FloeComponent\[]|useCommandContributions" apps packages packages/init/templates --hidden
28
24
  ```
29
25
 
30
- 2. Ensure each command action targets a registered component id.
31
- 3. Keep labels, ids, and sidebar destination consistent.
26
+ 3. Use generated-app searches for scaffolded projects:
32
27
 
33
- ## Playbook C: Implement UI With Public Exports
28
+ ```bash
29
+ rg "FloeApp|FloeRegistryRuntime|const components|FloeComponent\[]|useCommandContributions" src --hidden
30
+ ```
34
31
 
35
- Allowed imports:
36
- - `@floegence/floe-webapp-core`
37
- - `@floegence/floe-webapp-core/app`
38
- - `@floegence/floe-webapp-core/ui`
39
- - `@floegence/floe-webapp-core/layout`
40
- - `@floegence/floe-webapp-core/icons`
32
+ ## Playbook B: Add Or Update Registry-Driven Navigation
41
33
 
42
- Forbidden:
43
- - `@floegence/floe-webapp-core/src/...`
34
+ 1. Find the registration flow in the correct workspace surface.
35
+ 2. Keep every component contribution aligned:
36
+ - Stable `id` string.
37
+ - `sidebar` metadata (`order`, `renderIn`, `fullScreen`, `hiddenOnMobile`, optional `badge`, optional `collapseBehavior`).
38
+ - `commands` targets using the same registered ids.
39
+ - `statusBar` ordering and placement when applicable.
40
+ 3. Validate the shell wiring still renders through the intended runtime:
41
+ - `FloeApp` for the standard shell.
42
+ - `FloeRegistryRuntime` for custom shell assembly.
43
+ - `ActivityAppsMain` or `KeepAliveStack` for main-view keep-alive flows.
44
+ 4. If you touch manual registry lifecycle, keep `ComponentRegistry.registerAll()` cleanup symmetry intact.
44
45
 
45
- ## Playbook D: Verify And Diagnose
46
+ ## Playbook C: Add Commands And Lifecycle Hooks
46
47
 
47
- Run:
48
+ 1. Search contribution points:
48
49
 
49
50
  ```bash
50
- pnpm lint
51
- pnpm typecheck
52
- pnpm test -- --run
53
- pnpm build
51
+ for dir in apps packages src; do
52
+ [ -d "$dir" ] || continue
53
+ rg "commands|useCommandContributions|CommandPalette|setSidebarActiveTab|registerAll|onMount|onUnmount" "$dir" --hidden
54
+ done
54
55
  ```
55
56
 
56
- If a command fails:
57
- 1. Capture the first actionable error.
58
- 2. Fix the nearest root cause.
59
- 3. Re-run from the failed command onward.
57
+ 2. Use the right command pattern:
58
+ - `FloeComponent.commands[].execute(ctx)` for component-owned commands.
59
+ - `useCommandContributions()` for app-level command groups that are not tied to a `FloeComponent`.
60
+ 3. Ensure command labels, ids, categories, keybinds, and navigation targets remain consistent.
61
+ 4. If protocol/config context is involved, trace it through `wrapAfterTheme`, `getProtocol`, and component context docs before editing.
60
62
 
61
- ## Playbook E: Mobile And Styling QA
63
+ ## Playbook D: Select Public Exports Deliberately
62
64
 
63
- 1. Check mobile-related configuration:
65
+ 1. Treat `packages/core/package.json` `exports` as the source of truth.
66
+ 2. Prefer the most specific public subpath that matches the feature:
67
+ - `@floegence/floe-webapp-core/app`
68
+ - `@floegence/floe-webapp-core/layout`
69
+ - `@floegence/floe-webapp-core/ui`
70
+ - `@floegence/floe-webapp-core/icons`
71
+ - `@floegence/floe-webapp-core/loading`
72
+ - `@floegence/floe-webapp-core/launchpad`
73
+ - `@floegence/floe-webapp-core/file-browser`
74
+ - `@floegence/floe-webapp-core/chat`
75
+ - `@floegence/floe-webapp-core/editor`
76
+ - `@floegence/floe-webapp-core/widgets`
77
+ - `@floegence/floe-webapp-core/terminal`
78
+ - `@floegence/floe-webapp-core/deck`
79
+ - `@floegence/floe-webapp-core/full`
80
+ - `@floegence/floe-webapp-core/styles`
81
+ - `@floegence/floe-webapp-core/tailwind`
82
+ 3. Do not import `@floegence/floe-webapp-core/src/...`.
83
+ 4. Prefer `@floegence/floe-webapp-core/tailwind` for Tailwind v4 apps; use `@floegence/floe-webapp-core/styles` only as the no-Tailwind fallback.
84
+
85
+ ## Playbook E: Interaction Architecture And Responsive QA
86
+
87
+ 1. Search for interaction-sensitive code paths:
64
88
 
65
89
  ```bash
66
- rg "hiddenOnMobile|renderIn|fullScreen|MobileTabBar|sidebar" src --hidden
90
+ for dir in apps packages src; do
91
+ [ -d "$dir" ] || continue
92
+ rg "useOverlayMask|startHotInteraction|deferAfterPaint|deferNonBlocking|data-floe-geometry-surface|hiddenOnMobile|renderIn|fullScreen|collapseBehavior" "$dir" --hidden
93
+ done
67
94
  ```
68
95
 
69
- 2. Validate responsive behavior manually in browser devtools at:
96
+ 2. Apply the current guardrails from `docs/interaction-architecture.md`:
97
+ - UI first for click/open/selection flows.
98
+ - `useOverlayMask()` for overlays and drawers.
99
+ - `startHotInteraction()` plus preview/commit separation for drag or resize flows.
100
+ - No hot-path `transition-all` or geometry-following animation regressions.
101
+ 3. Validate responsive behavior manually in browser devtools at:
70
102
  - `390x844`
71
103
  - `430x932`
72
104
  - `768x1024`
73
105
  - `>=1280px`
106
+ 4. Verify interaction behavior on touch-like flows:
107
+ - Navigation still reachable without hover.
108
+ - Buttons, menus, and toggles remain usable on small screens.
109
+ - No clipped text or horizontal overflow in primary views.
74
110
 
75
- 3. Check style tokens and prevent hardcoded color drift:
111
+ ## Playbook F: Verify, Sync, And Diagnose
112
+
113
+ 1. Prefer the repo-local CI entrypoint when available:
76
114
 
77
115
  ```bash
78
- rg "#[0-9A-Fa-f]{3,8}|rgba\\(|hsla\\(" src --hidden
116
+ make check
79
117
  ```
80
118
 
81
- 4. Verify interaction behavior on touch-like flows:
82
- - Navigation still reachable without hover.
83
- - Buttons, menus, and toggles remain usable on small screens.
84
- - No clipped text or horizontal overflow in primary views.
119
+ 2. If `make check` is unavailable, run deterministic fallback commands:
120
+
121
+ ```bash
122
+ pnpm lint
123
+ pnpm typecheck
124
+ pnpm test -- --run
125
+ pnpm build
126
+ ```
127
+
128
+ 3. When editing this repository's skill package, sync mirrors first:
129
+
130
+ ```bash
131
+ pnpm sync:skills
132
+ pnpm verify
133
+ ```
85
134
 
86
- 5. Finalize only after lint/typecheck/test/build pass.
135
+ 4. If a command fails:
136
+ - Capture the first actionable error.
137
+ - Fix the nearest root cause.
138
+ - Re-run from the failed command onward.
139
+ - Do a final review of the changed files for consistency and completeness before committing.
package/templates/full/skills/floe-webapp/SKILL.md CHANGED
@@ -1,30 +1,72 @@
1
1
  ---
2
2
  name: floe-webapp
3
- description: Implement, refactor, and debug Floe-Webapp Solid.js applications with @floegence/floe-webapp-core public exports. Use for FloeApp shell wiring, FloeComponent sidebar or command registration, lifecycle hooks, design-token-first styling, and build or typecheck failures in Floe-Webapp projects.
3
+ description: Implement, refactor, and debug Floe-Webapp apps and this monorepo using only public @floegence/floe-webapp-core exports. Use for FloeApp or FloeRegistryRuntime wiring, component registry flows, interaction-architecture guardrails, design-token-first styling, and local CI or verify failures.
4
4
  ---
5
5
 
6
6
  # Floe-Webapp Skill
7
7
 
8
8
  ## Scope
9
9
 
10
- - Implement or refactor pages/components in a Floe-Webapp app.
11
- - Add or update `FloeComponent` registration (`sidebar`, `commands`, lifecycle hooks).
12
- - Diagnose framework-usage issues and local build/lint/typecheck/test failures.
10
+ - Implement or refactor repo workspace packages/apps and scaffolded Floe-Webapp apps.
11
+ - Add or update registry-driven navigation (`FloeComponent`, `commands`, `statusBar`, lifecycle hooks, app-level command contributions).
12
+ - Diagnose framework-usage issues and local lint/typecheck/test/build/verify failures.
13
13
 
14
14
  ## Required Inputs
15
15
 
16
16
  - Read project-root `AGENTS.md` first when available.
17
17
  - If `AGENTS.md` is absent, read `README.md` and `docs/getting-started.md`.
18
+ - Read the closest source-of-truth docs for the task:
19
+ - `docs/component-registry.md` for registry/runtime/commands/lifecycle guidance.
20
+ - `docs/interaction-architecture.md` for UI-first, overlay, drag/resize, and hot-path rules.
21
+ - `docs/configuration.md`, `docs/protocol.md`, and `docs/runtime.md` when config, protocol, or boot behavior is involved.
18
22
  - Load [references/playbooks.md](references/playbooks.md) and pick the closest playbook for the task.
19
23
 
20
24
  ## Execution Protocol
21
25
 
22
- 1. Verify package versions in `package.json` and lockfile before using any API surface.
23
- 2. Locate entry points and registration flow (`src/App.tsx`, component modules, command handlers).
24
- 3. Implement using only public exports from `@floegence/floe-webapp-core` (`/app`, `/ui`, `/layout`, `/icons`, root).
25
- 4. Align `FloeComponent.id`, sidebar items, and command navigation targets.
26
- 5. Keep styling on design tokens (`text-foreground`, `bg-card`, `border-border`, etc.).
27
- 6. Run deterministic checks before finishing:
26
+ 1. Verify package versions in `package.json` and the lockfile before using any API surface.
27
+ 2. Classify the target shape before editing:
28
+ - Repo workspace: `apps/*/src/App.tsx`, `apps/*/src/**/*`, `packages/*/src/**/*`, `packages/init/templates/**/*`.
29
+ - Scaffolded app: `src/App.tsx`, `src/**/*`.
30
+ 3. Use only public exports declared by `@floegence/floe-webapp-core` package exports. Current official surfaces:
31
+ - `@floegence/floe-webapp-core`
32
+ - `@floegence/floe-webapp-core/app`
33
+ - `@floegence/floe-webapp-core/full`
34
+ - `@floegence/floe-webapp-core/layout`
35
+ - `@floegence/floe-webapp-core/deck`
36
+ - `@floegence/floe-webapp-core/ui`
37
+ - `@floegence/floe-webapp-core/icons`
38
+ - `@floegence/floe-webapp-core/loading`
39
+ - `@floegence/floe-webapp-core/launchpad`
40
+ - `@floegence/floe-webapp-core/file-browser`
41
+ - `@floegence/floe-webapp-core/chat`
42
+ - `@floegence/floe-webapp-core/editor`
43
+ - `@floegence/floe-webapp-core/widgets`
44
+ - `@floegence/floe-webapp-core/terminal`
45
+ - `@floegence/floe-webapp-core/styles`
46
+ - `@floegence/floe-webapp-core/tailwind`
47
+ 4. Align registry behavior end-to-end:
48
+ - Keep `FloeComponent.id`, sidebar items, command targets, and layout navigation consistent.
49
+ - Use `ActivityAppsMain` for `sidebar.fullScreen` or `sidebar.renderIn === 'main'` page flows when appropriate.
50
+ - Use `FloeRegistryRuntime` when a custom shell is required but registry lifecycle still needs symmetric register/mount/cleanup behavior.
51
+ 5. Follow current interaction guardrails:
52
+ - UI first: let the visual state update before heavier work.
53
+ - Reuse `deferAfterPaint()` or `deferNonBlocking()` for deferred host logic.
54
+ - Reuse `useOverlayMask()` for overlays.
55
+ - Reuse `startHotInteraction()` and preview/commit separation for drag or resize flows.
56
+ 6. Keep styling on design tokens and official CSS entrypoints:
57
+ - Preferred: `@floegence/floe-webapp-core/tailwind`
58
+ - Fallback: `@floegence/floe-webapp-core/styles`
59
+ 7. When editing this repo's skill package, treat `skills/floe-webapp/*` as the source of truth and sync these mirrors before finishing:
60
+ - `packages/init/skills/floe-webapp/*`
61
+ - `packages/init/templates/full/skills/floe-webapp/*`
62
+ - `packages/init/templates/minimal/skills/floe-webapp/*`
63
+ 8. Run deterministic checks before finishing:
64
+
65
+ ```bash
66
+ make check
67
+ ```
68
+
69
+ If `make check` is unavailable in a downstream app, run:
28
70
 
29
71
  ```bash
30
72
  pnpm lint
@@ -33,21 +75,25 @@ pnpm test -- --run
33
75
  pnpm build
34
76
  ```
35
77
 
78
+ When editing this repository, `make check` already includes `pnpm verify`; if you run commands individually, include `pnpm verify` before finishing.
79
+
36
80
  ## Constraints
37
81
 
38
- - Solid.js only: do not use React hooks/patterns.
82
+ - Solid.js only: do not use React hooks or React component patterns.
39
83
  - Use `class=` in JSX, not `className=`.
40
84
  - Do not import `@floegence/floe-webapp-core/src/...` internal paths.
41
85
  - Keep command navigation ids aligned with registered component ids.
42
- - Prefer Solid control flow in JSX (`<For>`, `<Show>`, `<Switch>/<Match>`).
43
- - If API behavior is unclear, inspect installed type declarations before guessing.
86
+ - Prefer Solid control flow in JSX (`<For>`, `<Show>`, `<Switch>/<Match>`) when it improves clarity.
87
+ - Respect component-registry lifecycle symmetry (`registerAll()` cleanup, `onMount`, `onUnmount`) and use `useCommandContributions()` for app-level command groups not tied to a `FloeComponent`.
88
+ - If API behavior is unclear, inspect installed type declarations and the relevant public docs before guessing.
44
89
 
45
90
  ## Mobile Compatibility
46
91
 
47
92
  - Treat mobile as first-class behavior, not a fallback.
48
93
  - For sidebar components that should not appear on small screens, set `sidebar.hiddenOnMobile: true`.
94
+ - Keep `sidebar.fullScreen`, `sidebar.renderIn`, and `sidebar.collapseBehavior` aligned with the intended mobile/desktop navigation behavior.
49
95
  - Ensure primary navigation actions remain reachable on small screens (top bar or mobile tab bar paths).
50
- - Avoid hover-only interactions; provide click/tap equivalent behavior.
96
+ - Avoid hover-only interactions; provide click or tap equivalents.
51
97
  - Avoid fixed-width layouts that can overflow narrow viewports.
52
98
  - Keep interactive targets comfortably tappable (buttons, menu items, toggles).
53
99
  - Validate behavior at common widths before finishing:
@@ -56,21 +102,22 @@ pnpm build
56
102
  - Tablet: `768x1024`
57
103
  - Desktop: `>=1280px`
58
104
 
59
- ## Styling Guidelines
105
+ ## Styling And Interaction Guidelines
60
106
 
61
107
  - Use design tokens for color, border, and background (`text-*`, `bg-*`, `border-*` token classes).
62
108
  - Avoid raw hex colors and ad-hoc opacity values unless product requirements explicitly demand them.
63
109
  - Keep spacing and sizing on a consistent scale (`gap-*`, `p-*`, `m-*`, `rounded-*`).
64
110
  - Ensure readable contrast in both light and dark themes.
65
111
  - Define clear interactive states for controls (default, hover, active, focus, disabled).
66
- - Keep motion subtle and optional; avoid animations that block core interaction.
112
+ - Keep motion subtle and optional; do not reintroduce hot-path geometry transitions that violate `docs/interaction-architecture.md`.
67
113
  - When introducing new visual patterns, keep them consistent across pages and components.
68
114
 
69
115
  ## Failure Handling
70
116
 
71
- - If checks fail, report the exact failing command and first actionable error.
117
+ - If checks fail, report the exact failing command and the first actionable error.
72
118
  - Fix root causes instead of adding compatibility shims for old code paths.
73
- - If task requires risky incompatible behavior change, stop and ask for confirmation.
119
+ - If `pnpm verify` fails on skill drift, sync the root skill package and mirrors instead of patching only one copy.
120
+ - If the task requires a risky incompatible behavior change, stop and ask for confirmation.
74
121
 
75
122
  ## Output Format
76
123
 
package/templates/full/skills/floe-webapp/references/playbooks.md CHANGED
@@ -2,85 +2,138 @@
2
2
 
3
3
  Use this file after reading `../SKILL.md`.
4
4
 
5
- ## Playbook A: Add Or Update A FloeComponent
5
+ ## Playbook A: Choose The Right Workspace Surface
6
6
 
7
- 1. Find the registration list:
7
+ 1. Classify the target before editing:
8
8
 
9
9
  ```bash
10
- rg "const components|FloeComponent\\[]" src --hidden
10
+ if [ -d apps ] || [ -d packages ]; then
11
+ printf 'repo workspace\n'
12
+ find apps packages -maxdepth 3 -type f 2>/dev/null | sort | sed -n '1,200p'
13
+ fi
14
+ if [ -d src ]; then
15
+ printf '\nscaffolded app\n'
16
+ find src -maxdepth 3 -type f | sort | sed -n '1,200p'
17
+ fi
11
18
  ```
12
19
 
13
- 2. Keep every component entry aligned:
14
- - Stable `id` string.
15
- - `sidebar` metadata (`order`, `renderIn`, `fullScreen`, optional `badge`).
16
- - `commands` targets using the same `id`.
17
-
18
- 3. Validate shell wiring still renders through:
19
- - `FloeApp`
20
- - `ActivityAppsMain`
21
-
22
- ## Playbook B: Add Command Navigation
23
-
24
- 1. Search command contribution points:
20
+ 2. Use repo-workspace searches for this monorepo:
25
21
 
26
22
  ```bash
27
- rg "commands|useCommand|command" src --hidden
23
+ rg "FloeApp|FloeRegistryRuntime|const components|FloeComponent\[]|useCommandContributions" apps packages packages/init/templates --hidden
28
24
  ```
29
25
 
30
- 2. Ensure each command action targets a registered component id.
31
- 3. Keep labels, ids, and sidebar destination consistent.
26
+ 3. Use generated-app searches for scaffolded projects:
32
27
 
33
- ## Playbook C: Implement UI With Public Exports
28
+ ```bash
29
+ rg "FloeApp|FloeRegistryRuntime|const components|FloeComponent\[]|useCommandContributions" src --hidden
30
+ ```
34
31
 
35
- Allowed imports:
36
- - `@floegence/floe-webapp-core`
37
- - `@floegence/floe-webapp-core/app`
38
- - `@floegence/floe-webapp-core/ui`
39
- - `@floegence/floe-webapp-core/layout`
40
- - `@floegence/floe-webapp-core/icons`
32
+ ## Playbook B: Add Or Update Registry-Driven Navigation
41
33
 
42
- Forbidden:
43
- - `@floegence/floe-webapp-core/src/...`
34
+ 1. Find the registration flow in the correct workspace surface.
35
+ 2. Keep every component contribution aligned:
36
+ - Stable `id` string.
37
+ - `sidebar` metadata (`order`, `renderIn`, `fullScreen`, `hiddenOnMobile`, optional `badge`, optional `collapseBehavior`).
38
+ - `commands` targets using the same registered ids.
39
+ - `statusBar` ordering and placement when applicable.
40
+ 3. Validate the shell wiring still renders through the intended runtime:
41
+ - `FloeApp` for the standard shell.
42
+ - `FloeRegistryRuntime` for custom shell assembly.
43
+ - `ActivityAppsMain` or `KeepAliveStack` for main-view keep-alive flows.
44
+ 4. If you touch manual registry lifecycle, keep `ComponentRegistry.registerAll()` cleanup symmetry intact.
44
45
 
45
- ## Playbook D: Verify And Diagnose
46
+ ## Playbook C: Add Commands And Lifecycle Hooks
46
47
 
47
- Run:
48
+ 1. Search contribution points:
48
49
 
49
50
  ```bash
50
- pnpm lint
51
- pnpm typecheck
52
- pnpm test -- --run
53
- pnpm build
51
+ for dir in apps packages src; do
52
+ [ -d "$dir" ] || continue
53
+ rg "commands|useCommandContributions|CommandPalette|setSidebarActiveTab|registerAll|onMount|onUnmount" "$dir" --hidden
54
+ done
54
55
  ```
55
56
 
56
- If a command fails:
57
- 1. Capture the first actionable error.
58
- 2. Fix the nearest root cause.
59
- 3. Re-run from the failed command onward.
57
+ 2. Use the right command pattern:
58
+ - `FloeComponent.commands[].execute(ctx)` for component-owned commands.
59
+ - `useCommandContributions()` for app-level command groups that are not tied to a `FloeComponent`.
60
+ 3. Ensure command labels, ids, categories, keybinds, and navigation targets remain consistent.
61
+ 4. If protocol/config context is involved, trace it through `wrapAfterTheme`, `getProtocol`, and component context docs before editing.
60
62
 
61
- ## Playbook E: Mobile And Styling QA
63
+ ## Playbook D: Select Public Exports Deliberately
62
64
 
63
- 1. Check mobile-related configuration:
65
+ 1. Treat `packages/core/package.json` `exports` as the source of truth.
66
+ 2. Prefer the most specific public subpath that matches the feature:
67
+ - `@floegence/floe-webapp-core/app`
68
+ - `@floegence/floe-webapp-core/layout`
69
+ - `@floegence/floe-webapp-core/ui`
70
+ - `@floegence/floe-webapp-core/icons`
71
+ - `@floegence/floe-webapp-core/loading`
72
+ - `@floegence/floe-webapp-core/launchpad`
73
+ - `@floegence/floe-webapp-core/file-browser`
74
+ - `@floegence/floe-webapp-core/chat`
75
+ - `@floegence/floe-webapp-core/editor`
76
+ - `@floegence/floe-webapp-core/widgets`
77
+ - `@floegence/floe-webapp-core/terminal`
78
+ - `@floegence/floe-webapp-core/deck`
79
+ - `@floegence/floe-webapp-core/full`
80
+ - `@floegence/floe-webapp-core/styles`
81
+ - `@floegence/floe-webapp-core/tailwind`
82
+ 3. Do not import `@floegence/floe-webapp-core/src/...`.
83
+ 4. Prefer `@floegence/floe-webapp-core/tailwind` for Tailwind v4 apps; use `@floegence/floe-webapp-core/styles` only as the no-Tailwind fallback.
84
+
85
+ ## Playbook E: Interaction Architecture And Responsive QA
86
+
87
+ 1. Search for interaction-sensitive code paths:
64
88
 
65
89
  ```bash
66
- rg "hiddenOnMobile|renderIn|fullScreen|MobileTabBar|sidebar" src --hidden
90
+ for dir in apps packages src; do
91
+ [ -d "$dir" ] || continue
92
+ rg "useOverlayMask|startHotInteraction|deferAfterPaint|deferNonBlocking|data-floe-geometry-surface|hiddenOnMobile|renderIn|fullScreen|collapseBehavior" "$dir" --hidden
93
+ done
67
94
  ```
68
95
 
69
- 2. Validate responsive behavior manually in browser devtools at:
96
+ 2. Apply the current guardrails from `docs/interaction-architecture.md`:
97
+ - UI first for click/open/selection flows.
98
+ - `useOverlayMask()` for overlays and drawers.
99
+ - `startHotInteraction()` plus preview/commit separation for drag or resize flows.
100
+ - No hot-path `transition-all` or geometry-following animation regressions.
101
+ 3. Validate responsive behavior manually in browser devtools at:
70
102
  - `390x844`
71
103
  - `430x932`
72
104
  - `768x1024`
73
105
  - `>=1280px`
106
+ 4. Verify interaction behavior on touch-like flows:
107
+ - Navigation still reachable without hover.
108
+ - Buttons, menus, and toggles remain usable on small screens.
109
+ - No clipped text or horizontal overflow in primary views.
74
110
 
75
- 3. Check style tokens and prevent hardcoded color drift:
111
+ ## Playbook F: Verify, Sync, And Diagnose
112
+
113
+ 1. Prefer the repo-local CI entrypoint when available:
76
114
 
77
115
  ```bash
78
- rg "#[0-9A-Fa-f]{3,8}|rgba\\(|hsla\\(" src --hidden
116
+ make check
79
117
  ```
80
118
 
81
- 4. Verify interaction behavior on touch-like flows:
82
- - Navigation still reachable without hover.
83
- - Buttons, menus, and toggles remain usable on small screens.
84
- - No clipped text or horizontal overflow in primary views.
119
+ 2. If `make check` is unavailable, run deterministic fallback commands:
120
+
121
+ ```bash
122
+ pnpm lint
123
+ pnpm typecheck
124
+ pnpm test -- --run
125
+ pnpm build
126
+ ```
127
+
128
+ 3. When editing this repository's skill package, sync mirrors first:
129
+
130
+ ```bash
131
+ pnpm sync:skills
132
+ pnpm verify
133
+ ```
85
134
 
86
- 5. Finalize only after lint/typecheck/test/build pass.
135
+ 4. If a command fails:
136
+ - Capture the first actionable error.
137
+ - Fix the nearest root cause.
138
+ - Re-run from the failed command onward.
139
+ - Do a final review of the changed files for consistency and completeness before committing.
package/templates/minimal/skills/floe-webapp/SKILL.md CHANGED
@@ -1,30 +1,72 @@
1
1
  ---
2
2
  name: floe-webapp
3
- description: Implement, refactor, and debug Floe-Webapp Solid.js applications with @floegence/floe-webapp-core public exports. Use for FloeApp shell wiring, FloeComponent sidebar or command registration, lifecycle hooks, design-token-first styling, and build or typecheck failures in Floe-Webapp projects.
3
+ description: Implement, refactor, and debug Floe-Webapp apps and this monorepo using only public @floegence/floe-webapp-core exports. Use for FloeApp or FloeRegistryRuntime wiring, component registry flows, interaction-architecture guardrails, design-token-first styling, and local CI or verify failures.
4
4
  ---
5
5
 
6
6
  # Floe-Webapp Skill
7
7
 
8
8
  ## Scope
9
9
 
10
- - Implement or refactor pages/components in a Floe-Webapp app.
11
- - Add or update `FloeComponent` registration (`sidebar`, `commands`, lifecycle hooks).
12
- - Diagnose framework-usage issues and local build/lint/typecheck/test failures.
10
+ - Implement or refactor repo workspace packages/apps and scaffolded Floe-Webapp apps.
11
+ - Add or update registry-driven navigation (`FloeComponent`, `commands`, `statusBar`, lifecycle hooks, app-level command contributions).
12
+ - Diagnose framework-usage issues and local lint/typecheck/test/build/verify failures.
13
13
 
14
14
  ## Required Inputs
15
15
 
16
16
  - Read project-root `AGENTS.md` first when available.
17
17
  - If `AGENTS.md` is absent, read `README.md` and `docs/getting-started.md`.
18
+ - Read the closest source-of-truth docs for the task:
19
+ - `docs/component-registry.md` for registry/runtime/commands/lifecycle guidance.
20
+ - `docs/interaction-architecture.md` for UI-first, overlay, drag/resize, and hot-path rules.
21
+ - `docs/configuration.md`, `docs/protocol.md`, and `docs/runtime.md` when config, protocol, or boot behavior is involved.
18
22
  - Load [references/playbooks.md](references/playbooks.md) and pick the closest playbook for the task.
19
23
 
20
24
  ## Execution Protocol
21
25
 
22
- 1. Verify package versions in `package.json` and lockfile before using any API surface.
23
- 2. Locate entry points and registration flow (`src/App.tsx`, component modules, command handlers).
24
- 3. Implement using only public exports from `@floegence/floe-webapp-core` (`/app`, `/ui`, `/layout`, `/icons`, root).
25
- 4. Align `FloeComponent.id`, sidebar items, and command navigation targets.
26
- 5. Keep styling on design tokens (`text-foreground`, `bg-card`, `border-border`, etc.).
27
- 6. Run deterministic checks before finishing:
26
+ 1. Verify package versions in `package.json` and the lockfile before using any API surface.
27
+ 2. Classify the target shape before editing:
28
+ - Repo workspace: `apps/*/src/App.tsx`, `apps/*/src/**/*`, `packages/*/src/**/*`, `packages/init/templates/**/*`.
29
+ - Scaffolded app: `src/App.tsx`, `src/**/*`.
30
+ 3. Use only public exports declared by `@floegence/floe-webapp-core` package exports. Current official surfaces:
31
+ - `@floegence/floe-webapp-core`
32
+ - `@floegence/floe-webapp-core/app`
33
+ - `@floegence/floe-webapp-core/full`
34
+ - `@floegence/floe-webapp-core/layout`
35
+ - `@floegence/floe-webapp-core/deck`
36
+ - `@floegence/floe-webapp-core/ui`
37
+ - `@floegence/floe-webapp-core/icons`
38
+ - `@floegence/floe-webapp-core/loading`
39
+ - `@floegence/floe-webapp-core/launchpad`
40
+ - `@floegence/floe-webapp-core/file-browser`
41
+ - `@floegence/floe-webapp-core/chat`
42
+ - `@floegence/floe-webapp-core/editor`
43
+ - `@floegence/floe-webapp-core/widgets`
44
+ - `@floegence/floe-webapp-core/terminal`
45
+ - `@floegence/floe-webapp-core/styles`
46
+ - `@floegence/floe-webapp-core/tailwind`
47
+ 4. Align registry behavior end-to-end:
48
+ - Keep `FloeComponent.id`, sidebar items, command targets, and layout navigation consistent.
49
+ - Use `ActivityAppsMain` for `sidebar.fullScreen` or `sidebar.renderIn === 'main'` page flows when appropriate.
50
+ - Use `FloeRegistryRuntime` when a custom shell is required but registry lifecycle still needs symmetric register/mount/cleanup behavior.
51
+ 5. Follow current interaction guardrails:
52
+ - UI first: let the visual state update before heavier work.
53
+ - Reuse `deferAfterPaint()` or `deferNonBlocking()` for deferred host logic.
54
+ - Reuse `useOverlayMask()` for overlays.
55
+ - Reuse `startHotInteraction()` and preview/commit separation for drag or resize flows.
56
+ 6. Keep styling on design tokens and official CSS entrypoints:
57
+ - Preferred: `@floegence/floe-webapp-core/tailwind`
58
+ - Fallback: `@floegence/floe-webapp-core/styles`
59
+ 7. When editing this repo's skill package, treat `skills/floe-webapp/*` as the source of truth and sync these mirrors before finishing:
60
+ - `packages/init/skills/floe-webapp/*`
61
+ - `packages/init/templates/full/skills/floe-webapp/*`
62
+ - `packages/init/templates/minimal/skills/floe-webapp/*`
63
+ 8. Run deterministic checks before finishing:
64
+
65
+ ```bash
66
+ make check
67
+ ```
68
+
69
+ If `make check` is unavailable in a downstream app, run:
28
70
 
29
71
  ```bash
30
72
  pnpm lint
@@ -33,21 +75,25 @@ pnpm test -- --run
33
75
  pnpm build
34
76
  ```
35
77
 
78
+ When editing this repository, `make check` already includes `pnpm verify`; if you run commands individually, include `pnpm verify` before finishing.
79
+
36
80
  ## Constraints
37
81
 
38
- - Solid.js only: do not use React hooks/patterns.
82
+ - Solid.js only: do not use React hooks or React component patterns.
39
83
  - Use `class=` in JSX, not `className=`.
40
84
  - Do not import `@floegence/floe-webapp-core/src/...` internal paths.
41
85
  - Keep command navigation ids aligned with registered component ids.
42
- - Prefer Solid control flow in JSX (`<For>`, `<Show>`, `<Switch>/<Match>`).
43
- - If API behavior is unclear, inspect installed type declarations before guessing.
86
+ - Prefer Solid control flow in JSX (`<For>`, `<Show>`, `<Switch>/<Match>`) when it improves clarity.
87
+ - Respect component-registry lifecycle symmetry (`registerAll()` cleanup, `onMount`, `onUnmount`) and use `useCommandContributions()` for app-level command groups not tied to a `FloeComponent`.
88
+ - If API behavior is unclear, inspect installed type declarations and the relevant public docs before guessing.
44
89
 
45
90
  ## Mobile Compatibility
46
91
 
47
92
  - Treat mobile as first-class behavior, not a fallback.
48
93
  - For sidebar components that should not appear on small screens, set `sidebar.hiddenOnMobile: true`.
94
+ - Keep `sidebar.fullScreen`, `sidebar.renderIn`, and `sidebar.collapseBehavior` aligned with the intended mobile/desktop navigation behavior.
49
95
  - Ensure primary navigation actions remain reachable on small screens (top bar or mobile tab bar paths).
50
- - Avoid hover-only interactions; provide click/tap equivalent behavior.
96
+ - Avoid hover-only interactions; provide click or tap equivalents.
51
97
  - Avoid fixed-width layouts that can overflow narrow viewports.
52
98
  - Keep interactive targets comfortably tappable (buttons, menu items, toggles).
53
99
  - Validate behavior at common widths before finishing:
@@ -56,21 +102,22 @@ pnpm build
56
102
  - Tablet: `768x1024`
57
103
  - Desktop: `>=1280px`
58
104
 
59
- ## Styling Guidelines
105
+ ## Styling And Interaction Guidelines
60
106
 
61
107
  - Use design tokens for color, border, and background (`text-*`, `bg-*`, `border-*` token classes).
62
108
  - Avoid raw hex colors and ad-hoc opacity values unless product requirements explicitly demand them.
63
109
  - Keep spacing and sizing on a consistent scale (`gap-*`, `p-*`, `m-*`, `rounded-*`).
64
110
  - Ensure readable contrast in both light and dark themes.
65
111
  - Define clear interactive states for controls (default, hover, active, focus, disabled).
66
- - Keep motion subtle and optional; avoid animations that block core interaction.
112
+ - Keep motion subtle and optional; do not reintroduce hot-path geometry transitions that violate `docs/interaction-architecture.md`.
67
113
  - When introducing new visual patterns, keep them consistent across pages and components.
68
114
 
69
115
  ## Failure Handling
70
116
 
71
- - If checks fail, report the exact failing command and first actionable error.
117
+ - If checks fail, report the exact failing command and the first actionable error.
72
118
  - Fix root causes instead of adding compatibility shims for old code paths.
73
- - If task requires risky incompatible behavior change, stop and ask for confirmation.
119
+ - If `pnpm verify` fails on skill drift, sync the root skill package and mirrors instead of patching only one copy.
120
+ - If the task requires a risky incompatible behavior change, stop and ask for confirmation.
74
121
 
75
122
  ## Output Format
76
123
 
package/templates/minimal/skills/floe-webapp/references/playbooks.md CHANGED
@@ -2,85 +2,138 @@
2
2
 
3
3
  Use this file after reading `../SKILL.md`.
4
4
 
5
- ## Playbook A: Add Or Update A FloeComponent
5
+ ## Playbook A: Choose The Right Workspace Surface
6
6
 
7
- 1. Find the registration list:
7
+ 1. Classify the target before editing:
8
8
 
9
9
  ```bash
10
- rg "const components|FloeComponent\\[]" src --hidden
10
+ if [ -d apps ] || [ -d packages ]; then
11
+ printf 'repo workspace\n'
12
+ find apps packages -maxdepth 3 -type f 2>/dev/null | sort | sed -n '1,200p'
13
+ fi
14
+ if [ -d src ]; then
15
+ printf '\nscaffolded app\n'
16
+ find src -maxdepth 3 -type f | sort | sed -n '1,200p'
17
+ fi
11
18
  ```
12
19
 
13
- 2. Keep every component entry aligned:
14
- - Stable `id` string.
15
- - `sidebar` metadata (`order`, `renderIn`, `fullScreen`, optional `badge`).
16
- - `commands` targets using the same `id`.
17
-
18
- 3. Validate shell wiring still renders through:
19
- - `FloeApp`
20
- - `ActivityAppsMain`
21
-
22
- ## Playbook B: Add Command Navigation
23
-
24
- 1. Search command contribution points:
20
+ 2. Use repo-workspace searches for this monorepo:
25
21
 
26
22
  ```bash
27
- rg "commands|useCommand|command" src --hidden
23
+ rg "FloeApp|FloeRegistryRuntime|const components|FloeComponent\[]|useCommandContributions" apps packages packages/init/templates --hidden
28
24
  ```
29
25
 
30
- 2. Ensure each command action targets a registered component id.
31
- 3. Keep labels, ids, and sidebar destination consistent.
26
+ 3. Use generated-app searches for scaffolded projects:
32
27
 
33
- ## Playbook C: Implement UI With Public Exports
28
+ ```bash
29
+ rg "FloeApp|FloeRegistryRuntime|const components|FloeComponent\[]|useCommandContributions" src --hidden
30
+ ```
34
31
 
35
- Allowed imports:
36
- - `@floegence/floe-webapp-core`
37
- - `@floegence/floe-webapp-core/app`
38
- - `@floegence/floe-webapp-core/ui`
39
- - `@floegence/floe-webapp-core/layout`
40
- - `@floegence/floe-webapp-core/icons`
32
+ ## Playbook B: Add Or Update Registry-Driven Navigation
41
33
 
42
- Forbidden:
43
- - `@floegence/floe-webapp-core/src/...`
34
+ 1. Find the registration flow in the correct workspace surface.
35
+ 2. Keep every component contribution aligned:
36
+ - Stable `id` string.
37
+ - `sidebar` metadata (`order`, `renderIn`, `fullScreen`, `hiddenOnMobile`, optional `badge`, optional `collapseBehavior`).
38
+ - `commands` targets using the same registered ids.
39
+ - `statusBar` ordering and placement when applicable.
40
+ 3. Validate the shell wiring still renders through the intended runtime:
41
+ - `FloeApp` for the standard shell.
42
+ - `FloeRegistryRuntime` for custom shell assembly.
43
+ - `ActivityAppsMain` or `KeepAliveStack` for main-view keep-alive flows.
44
+ 4. If you touch manual registry lifecycle, keep `ComponentRegistry.registerAll()` cleanup symmetry intact.
44
45
 
45
- ## Playbook D: Verify And Diagnose
46
+ ## Playbook C: Add Commands And Lifecycle Hooks
46
47
 
47
- Run:
48
+ 1. Search contribution points:
48
49
 
49
50
  ```bash
50
- pnpm lint
51
- pnpm typecheck
52
- pnpm test -- --run
53
- pnpm build
51
+ for dir in apps packages src; do
52
+ [ -d "$dir" ] || continue
53
+ rg "commands|useCommandContributions|CommandPalette|setSidebarActiveTab|registerAll|onMount|onUnmount" "$dir" --hidden
54
+ done
54
55
  ```
55
56
 
56
- If a command fails:
57
- 1. Capture the first actionable error.
58
- 2. Fix the nearest root cause.
59
- 3. Re-run from the failed command onward.
57
+ 2. Use the right command pattern:
58
+ - `FloeComponent.commands[].execute(ctx)` for component-owned commands.
59
+ - `useCommandContributions()` for app-level command groups that are not tied to a `FloeComponent`.
60
+ 3. Ensure command labels, ids, categories, keybinds, and navigation targets remain consistent.
61
+ 4. If protocol/config context is involved, trace it through `wrapAfterTheme`, `getProtocol`, and component context docs before editing.
60
62
 
61
- ## Playbook E: Mobile And Styling QA
63
+ ## Playbook D: Select Public Exports Deliberately
62
64
 
63
- 1. Check mobile-related configuration:
65
+ 1. Treat `packages/core/package.json` `exports` as the source of truth.
66
+ 2. Prefer the most specific public subpath that matches the feature:
67
+ - `@floegence/floe-webapp-core/app`
68
+ - `@floegence/floe-webapp-core/layout`
69
+ - `@floegence/floe-webapp-core/ui`
70
+ - `@floegence/floe-webapp-core/icons`
71
+ - `@floegence/floe-webapp-core/loading`
72
+ - `@floegence/floe-webapp-core/launchpad`
73
+ - `@floegence/floe-webapp-core/file-browser`
74
+ - `@floegence/floe-webapp-core/chat`
75
+ - `@floegence/floe-webapp-core/editor`
76
+ - `@floegence/floe-webapp-core/widgets`
77
+ - `@floegence/floe-webapp-core/terminal`
78
+ - `@floegence/floe-webapp-core/deck`
79
+ - `@floegence/floe-webapp-core/full`
80
+ - `@floegence/floe-webapp-core/styles`
81
+ - `@floegence/floe-webapp-core/tailwind`
82
+ 3. Do not import `@floegence/floe-webapp-core/src/...`.
83
+ 4. Prefer `@floegence/floe-webapp-core/tailwind` for Tailwind v4 apps; use `@floegence/floe-webapp-core/styles` only as the no-Tailwind fallback.
84
+
85
+ ## Playbook E: Interaction Architecture And Responsive QA
86
+
87
+ 1. Search for interaction-sensitive code paths:
64
88
 
65
89
  ```bash
66
- rg "hiddenOnMobile|renderIn|fullScreen|MobileTabBar|sidebar" src --hidden
90
+ for dir in apps packages src; do
91
+ [ -d "$dir" ] || continue
92
+ rg "useOverlayMask|startHotInteraction|deferAfterPaint|deferNonBlocking|data-floe-geometry-surface|hiddenOnMobile|renderIn|fullScreen|collapseBehavior" "$dir" --hidden
93
+ done
67
94
  ```
68
95
 
69
- 2. Validate responsive behavior manually in browser devtools at:
96
+ 2. Apply the current guardrails from `docs/interaction-architecture.md`:
97
+ - UI first for click/open/selection flows.
98
+ - `useOverlayMask()` for overlays and drawers.
99
+ - `startHotInteraction()` plus preview/commit separation for drag or resize flows.
100
+ - No hot-path `transition-all` or geometry-following animation regressions.
101
+ 3. Validate responsive behavior manually in browser devtools at:
70
102
  - `390x844`
71
103
  - `430x932`
72
104
  - `768x1024`
73
105
  - `>=1280px`
106
+ 4. Verify interaction behavior on touch-like flows:
107
+ - Navigation still reachable without hover.
108
+ - Buttons, menus, and toggles remain usable on small screens.
109
+ - No clipped text or horizontal overflow in primary views.
74
110
 
75
- 3. Check style tokens and prevent hardcoded color drift:
111
+ ## Playbook F: Verify, Sync, And Diagnose
112
+
113
+ 1. Prefer the repo-local CI entrypoint when available:
76
114
 
77
115
  ```bash
78
- rg "#[0-9A-Fa-f]{3,8}|rgba\\(|hsla\\(" src --hidden
116
+ make check
79
117
  ```
80
118
 
81
- 4. Verify interaction behavior on touch-like flows:
82
- - Navigation still reachable without hover.
83
- - Buttons, menus, and toggles remain usable on small screens.
84
- - No clipped text or horizontal overflow in primary views.
119
+ 2. If `make check` is unavailable, run deterministic fallback commands:
120
+
121
+ ```bash
122
+ pnpm lint
123
+ pnpm typecheck
124
+ pnpm test -- --run
125
+ pnpm build
126
+ ```
127
+
128
+ 3. When editing this repository's skill package, sync mirrors first:
129
+
130
+ ```bash
131
+ pnpm sync:skills
132
+ pnpm verify
133
+ ```
85
134
 
86
- 5. Finalize only after lint/typecheck/test/build pass.
135
+ 4. If a command fails:
136
+ - Capture the first actionable error.
137
+ - Fix the nearest root cause.
138
+ - Re-run from the failed command onward.
139
+ - Do a final review of the changed files for consistency and completeness before committing.