@lessly/sdk-app 46.0.0 → 47.0.1

package/docs/rules.md

@@ -47,10 +47,22 @@ MUST be declared as shared singletons, never bundled (FED-005), using
 `@module-federation/vite` pinned at exactly `1.16.12` (FED-006). The asset
 base in federation mode is the absolute path `/~/<id>/`. The build MUST
 produce one merged dual-mode `dist/` covering both standalone and federation
-artifacts (FED-007). An App MAY additionally expose a data-only `./navigation`
-module (FED-011). This rule states the contract; it does not restate FED-001,
-FED-004, FED-005, FED-006, FED-007, or FED-011 — see those rules for exact
-wording, rationale, and examples.
+artifacts (FED-007).
+
+`./App` is the **only** module an App exposes. There is no `./navigation`
+contract: the shell no longer loads such a module, there is no
+`subscribeNavItems` and no `navContractVersion` negotiation, and the extension
+menu the shell renders is static (a single Home row). FED-011 is **RETIRED
+(2026-08)**. Still mapping the expose is inert rather than an error — it just
+ships a chunk nobody fetches — but a new App MUST NOT add it, and an existing
+one SHOULD delete `src/federation/navigation.ts`, drop the expose, and move
+whatever that module fed the menu (environment lists, tool groups, badges,
+status dots, a settings gear) into its own pages under `./App`'s relative
+routes (FED-003).
+
+This rule states the contract; it does not restate FED-001, FED-004, FED-005,
+FED-006, or FED-007 — see those rules for exact wording, rationale, and
+examples.
 
 ### APP-005 (MUST) — Auth is ambient; an App does not own it
 
@@ -87,3 +99,137 @@ Use this exact `@latest` form — not `npm update`. `@lessly/sdk-app` is
 pre-1.0 and pinned with a caret range, so `npm update` never crosses a minor
 version; since this SDK also bumps its minor version whenever the platform
 ships a new tool, `npm update` would never actually deliver those updates.
+
+### APP-008 (MUST) — The federation CSS entry is slim and global-free
+
+An App has two CSS entries: the **federation** entry (imported by the `./App`
+remote module) and the **standalone** entry (imported by the SPA entry). The
+federation entry's whole transitive graph — that stylesheet, everything it
+`@import`s, and every `@layer base { … }` block the App writes itself — MUST
+NOT contain:
+
+- `@font-face`;
+- a `@layer base { … }` block;
+- any rule declaring an inherited or visual property — `font-family`,
+  `font-size`, `line-height`, `color`, `background`, `margin`, `padding`,
+  `border-*`, `box-sizing`, `-webkit-text-size-adjust` — on `html`, `body`,
+  `:root` or `*`;
+- an `@import` of a web font, of `@lessly/ui/styles.css`, or of the full
+  `tailwindcss` entry (which bundles **preflight**).
+
+The prohibition holds wherever the rule comes from, `@apply` included:
+`body { @apply bg-bg-primary … }` in the App's own base layer is exactly as
+forbidden as an imported reset. The App's base layer belongs in a separate
+`src/base.css` that only the **standalone** entry imports. The standalone entry
+is unconstrained by this rule: it keeps the fonts, `@lessly/ui/styles.css`, the
+full `tailwindcss` import and the base layer, because there the App owns the
+page.
+
+**Custom properties are the boundary.** Declarations of `--*` on `html`,
+`body`, `:root` or `*` are fine — they paint nothing until something inside the
+App's own subtree reads them. Inherited and visual properties are what is
+forbidden, because the App is composed inside the shell's already-painted page
+and a `body` or `*` rule addresses the whole live document, shell chrome
+included. This line is load-bearing: `@lessly/ui/styles-federated.css`
+legitimately ships a `*, ::before, ::after, ::backdrop { --tw-*: … }` block
+(Tailwind v4's internal variable shim), and a guard written against selectors
+instead of declarations fails on the very import this rule prescribes.
+
+**Kit tokens.** An App that needs the design-system variables MUST import
+`@lessly/ui/styles-federated.css` — `styles.css` minus the `@font-face` blocks
+and the `@layer base`, keeping the token variables, the `--color-*` aliases,
+`.link`, the `.motion-*` helpers and the compiled tw-animate-css layer. Depend
+on `@lessly/ui` at `^4.0.0`, the range the shell itself runs. An App MUST NOT
+hand-copy the kit's tokens into a local `theme.css` (it silently drifts from
+the kit), and MUST NOT hand-filter `@lessly/ui/styles.css` with a prebuild
+script (it breaks on any restructure of a file the App does not own).
+
+**Scanning.** Tailwind generates only the classes it finds, and it scans the
+project, not `node_modules`. The federation entry MUST therefore
+`@source` the kit's compiled output
+(`@source '../node_modules/@lessly/ui/dist/index.js';`) or the classes
+`@lessly/ui` components use are never emitted — and it SHOULD exclude test
+files (`@source not '../src/**/*.test.tsx';`), since a utility class named as a
+test fixture is just a string to Tailwind and would otherwise be compiled into
+the shipped stylesheet.
+
+**Gate test.** The repository MUST carry a test asserting all of the above over
+the **built** federation CSS, not over the entry file's import list: the source
+imports can read clean while an imported stylesheet carries the base layer. Two
+shapes must not be confused — `@layer base, components;` (semicolon) only
+declares layer order and is harmless; the forbidden shape is the block,
+`@layer\s+base\s*\{`. And a universal rule is a violation only if it declares
+more than custom properties.
+
+For the production defect this comes from — a remote's late-loading `body`
+rule re-fonting the shell's chrome — see FED-008 in the extensions-guide.
+`recipes/federation.md` has the canonical stylesheets.
+
+### APP-009 (MUST) — One source of scale vocabulary: `lesslyPreset`
+
+An App takes its **scale vocabulary** — type, spacing, radii, font weight,
+line height, letter spacing — from the design-system preset the shell is built
+on: `lesslyPreset`, exported by `@lessly/ui/tailwind-preset`. Concretely:
+
+- `tailwind.config.ts` sets `presets: [lesslyPreset]`;
+- **both** CSS entries carry `@config '../tailwind.config.ts'`;
+- the App declares no scales of its own and keeps no `@theme` block bridging
+  to them;
+- the federation graph MUST NOT import `tailwindcss/theme.css` at all — not in
+  `layer(theme)`, and not with `theme(reference)`.
+
+**`theme(reference)` does not solve this.** It removes the `:root` emission,
+but Tailwind still inlines the literal as the utility's fallback
+(`var(--text-sm,.875rem)`), so the utility keeps its own value and keeps
+landing on the shell's markup. Measured: the emission went away and the page
+stayed broken.
+
+**The norm is "one source of vocabulary", not "no variables on `:root`".**
+Variables that coincide on `:root` between the App and the shell are expected
+and harmless — that is one source reaching the page twice. The absence
+criterion measures **green on a broken page**: the shell declares no `--text-*`
+variable at all (its preset compiles literals into the utilities), so three
+repositories passed that check while the shell's sidebar type was being resized
+by their sheets. Do not write a guard that way.
+
+When both sides build on the same preset, rules that share a class name compile
+identically and the collision stops existing. See FED-013 in the
+extensions-guide for the measurements (13px → 14px, line-height 19.5 → 20) and
+for the three wrong fixes it rules out.
+
+### APP-010 (MUST) — Federation utilities land in `layer(remote-utilities)`
+
+The **federation** entry MUST import Tailwind's utilities into a dedicated
+layer:
+
+```css
+@import 'tailwindcss/utilities.css' layer(remote-utilities);
+```
+
+never `layer(utilities)`. The **standalone** entry is exempt — it keeps the
+full `tailwindcss` import (APP-008), where the App owns the page and there is
+nothing to rank against.
+
+This works because the shell pre-declares the layer order in
+`lessly-workspace:apps/web/src/index.css`:
+
+```css
+@layer theme, base, components, remote-utilities, utilities;
+```
+
+so every App utility ranks below every shell utility whatever order the sheets
+happen to load in. The App's federation entry SHOULD repeat that same order
+declaration as its first line, so the layer positions are fixed before Tailwind
+emits its own.
+
+**Rollout order is strict and asymmetric.** That shell-side declaration MUST be
+in production before an App adopts the layer. Against a shell that has not
+declared the order, `remote-utilities` becomes the last-declared — and
+therefore **highest**-priority — layer, so every App utility beats every shell
+utility: strictly worse than the defect. Verify the shell first; adopting early
+is a regression, not a head start.
+
+See FED-014 in the extensions-guide for the measurement (App `.px-2` against
+shell `.sm:px-2.5` — different rule names, so no shared preset can reach them;
+5 of 283 shell chrome nodes affected) and for the accepted symmetric risk on
+the App's own nodes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessly/sdk-app",
-  "version": "46.0.0",
+  "version": "47.0.1",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -55,11 +55,6 @@
       "import": "./dist/consent/index.js",
       "require": "./dist/consent/index.cjs"
     },
-    "./content": {
-      "types": "./dist/content/index.d.ts",
-      "import": "./dist/content/index.js",
-      "require": "./dist/content/index.cjs"
-    },
     "./deployment": {
       "types": "./dist/deployment/index.d.ts",
       "import": "./dist/deployment/index.js",
@@ -80,11 +75,6 @@
       "import": "./dist/organization/index.js",
       "require": "./dist/organization/index.cjs"
     },
-    "./playground": {
-      "types": "./dist/playground/index.d.ts",
-      "import": "./dist/playground/index.js",
-      "require": "./dist/playground/index.cjs"
-    },
     "./realtime": {
       "types": "./dist/realtime/index.d.ts",
       "import": "./dist/realtime/index.js",
@@ -111,5 +101,5 @@
       "require": "./dist/waitlist/index.cjs"
     }
   },
-  "sdkContentHash": "sha256:4ceab38f2b4d4f07cc616a9ddd1df7f87e94a00c24317add22bfb36fa2c3bc97"
+  "sdkContentHash": "sha256:82da00e2c226a8955611954633868a0b341f2c4448c844865f0281540a68671b"
 }