@flyos/design-system 3.5.0 → 3.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flyos/design-system",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "FlyOS design system — shared components, directives, pipes, services, and models for Business App developers.",
   "keywords": [
     "flyos",

package/scss/_nova-glass.scss

@@ -63,9 +63,10 @@
 // compiled output, and this partial's whole contract is that it emits nothing.
 // stylelint-disable scss/at-mixin-pattern, scss/at-function-pattern
 
-// The three sanctioned blur tiers (skill §4) — chrome 36 / content panel 72 /
-// thin 16. Selected BY NAME; a fourth tier would have to be added here, in the
-// open, where `nova-glass.spec.ts` counts them.
+// The four sanctioned blur tiers (skill §4) — chrome 36 / content panel 72 /
+// thin 16 / window 50 (added when the window plate left the chrome family —
+// see `window` below). Selected BY NAME; a fifth tier would have to be added
+// here, in the open, where `nova-glass.spec.ts` counts them.
 @mixin _backdrop($tier) {
   @if $tier == chrome {
     -webkit-backdrop-filter: blur(36px) saturate(180%);
@@ -77,8 +78,14 @@
     // The ratified quartet value: blur(16px) saturate(180%) brightness(.95).
     -webkit-backdrop-filter: var(--glass2-blur);
     backdrop-filter: var(--glass2-blur);
+  } @else if $tier == window {
+    // Ratified from the window's own recipe (`window` mixin below) — 50px, one
+    // step heavier than chrome, because it is the single largest glass surface
+    // in the shell and carries the richer specular/edge treatment alongside it.
+    -webkit-backdrop-filter: blur(50px) saturate(180%);
+    backdrop-filter: blur(50px) saturate(180%);
   } @else {
-    @error 'nova-glass: unknown blur tier `#{$tier}`. The three sanctioned tiers are `chrome` (36px), `panel` (72px), `thin` (16px) — skill §4 says do not invent a fourth.';
+    @error 'nova-glass: unknown blur tier `#{$tier}`. The four sanctioned tiers are `chrome` (36px), `panel` (72px), `thin` (16px), `window` (50px) — skill §4 says do not invent a fifth.';
   }
 }
 
@@ -297,6 +304,76 @@
   @include _degrade;
 }
 
+// ── Window ───────────────────────────────────────────────────────────────────
+// The shared window plate (added when the one-glass-family ruling of
+// 2026-08-17 was superseded — skill §2/§4 carry the dated note). Originally a
+// bespoke, dark-theme-only material built by the Circles External App for its
+// own embedded window (conic-gradient specular rim, a layered gradient fill,
+// a distinct top/bottom edge split); promoted here as the platform default for
+// every window, in both themes, so it lives in ONE recipe instead of being
+// re-invented per app.
+// Consumes `--window-bg` / `--window-border` / `--window-shadow`
+// (`_theme-light.scss` / `_theme-dark.scss`, "Window chrome" section) — the
+// SAME names the pre-existing window family always used, not a parallel set:
+// `contextual-help-drawer`, `agent-overlay` and `agent-input` all deliberately
+// borrow those three tokens to read as extensions of the window's own glass,
+// so keeping the names carries the new recipe to them for free. Only
+// `--window-bg` (the fill) diverges per theme; border/shadow are one value in
+// both, exactly like before. The edge/rim treatment is new — a genuinely new
+// concept, so it gets new token names (`--window-edge-*`) nothing else reads.
+// This mixin does no Sass-side theme branching, same shape as `chrome`/`panel`
+// above; blur/saturate are a Sass-level literal via `_backdrop(window)`, same
+// as every other recipe here — `.window` no longer spends its own token pair
+// for them (retired; nothing else read those two names either).
+// Radius is deliberately NOT set here — `_window-shell.scss` keeps its own
+// `border-radius: var(--shell-window-radius)`. Glass material and window
+// corner geometry are separable; a 46px radius was tried once before (see that
+// file's own header comment) and reverted as a footgun, independent of this
+// mixin entirely.
+@mixin window {
+  border: 1px solid var(--window-border);
+  background-image: var(--window-bg);
+  box-shadow: var(--window-shadow);
+
+  @include _backdrop(window);
+
+  // Refractive rim — the conic specular stroke. Same masked-ring technique
+  // `material()` uses for its own rim (hazard 2 in the header: the
+  // `backdrop-filter` above already makes this element a containing block, so
+  // the pseudo resolves with no `position: relative` of its own needed here).
+  &::before {
+    content: '';
+    position: absolute;
+    z-index: 0;
+    inset: 0;
+    padding: 1px;
+    border-radius: inherit;
+    background: var(--window-edge-gradient);
+    pointer-events: none;
+    -webkit-mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
+    mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
+    -webkit-mask-composite: xor;
+    mask-composite: exclude;
+  }
+
+  // Top/bottom edge split — catches light along the top, grounds along the
+  // bottom, painted above content (z-index 3) so it reads at the outer 1px
+  // edge regardless of what the app renders underneath.
+  &::after {
+    content: '';
+    position: absolute;
+    z-index: 3;
+    inset: 0;
+    border-radius: inherit;
+    box-shadow:
+      inset 0 0.5px 0 var(--window-edge-top),
+      inset 0 -0.5px 0 var(--window-edge-bottom);
+    pointer-events: none;
+  }
+
+  @include _degrade;
+}
+
 // ── Content panel ────────────────────────────────────────────────────────────
 // The surface holding app content — the strongest blur in the language (72px),
 // on the quartet's layer stack with the `--mat-panel` fill.

package/scss/_theme-dark.scss

@@ -144,28 +144,87 @@ html.dark-theme {
   // family. No consumers in either theme; see `_theme-light.scss`.
 
   // ── Window chrome ───────────────────────────────────────────────────────────
-  // ONE GLASS FAMILY (RULED 2026-08-17, second window ruling of the day): the
-  // window wears the CHROME material — the magic bar / nav rail recipe — not the
-  // mock's content-panel plate. The first fidelity pass shipped `panelStyle`
-  // verbatim (quartet glow + sheen over `--mat-panel` .55, blur 72), and it WAS
-  // byte-exact — a pixel-accurate render over `tropical.jpg` reproduced the shell
-  // to the digit — but the .55 plate over the darker wallpaper midfield read as a
-  // separate, muddier glass beside the .38 chrome, and the owner ruled the shell
-  // shows one family: flat `--mat-rail` fill, `--w16` hairline, the `--w2`
-  // half-pixel inset, `blur(36px) saturate(180%)`. The drop pair stays the
-  // design's window shadow (16/40 + 4/10) — a floating window still needs a
-  // window's elevation, and the shadow does not touch the plate colour.
-  // The AA ladder re-measures on the thinner plate; sub-AA cells ride the exempt
-  // rails in `theme-contrast.ts` as measured rows, same as every other pin.
-  --window-bg: var(--mat-rail);
+  // SUPERSEDED 2026-08-2X — the window leaves the chrome family. The
+  // one-glass-family ruling below (2026-08-17) held that a window sharing the
+  // rail/header's `--mat-rail` plate reads as one coherent material. That call
+  // is now explicitly reversed: the window (both themes) takes its own
+  // `glass.window` recipe (`_nova-glass.scss`) — the visionOS-style rich
+  // material (conic specular rim, layered gradient fill, its own
+  // `--window-rich-*` token family below) originally built bespoke by the
+  // Circles External App for its dark-theme embedded window, promoted to the
+  // platform default. The rail/header/bottom-nav keep the flat chrome material
+  // unchanged; only the window plate diverges from them now — the opposite
+  // call from 2026-08-17, made deliberately, by informed choice, after the
+  // accessibility floor this ruling protected was re-measured against the new
+  // fill (`theme-contrast.spec.ts`'s SURFACES rows for window text). The old
+  // `'the window wears the CHROME dressing'` identity test is retired along
+  // with the identity it asserted.
+
+  // Original ruling, kept for history (RULED 2026-08-17, second window ruling
+  // of that day): the window wears the CHROME material — the magic bar / nav
+  // rail recipe — not the mock's content-panel plate. The first fidelity pass
+  // shipped `panelStyle` verbatim (quartet glow + sheen over `--mat-panel` .55,
+  // blur 72), and it WAS byte-exact — a pixel-accurate render over
+  // `tropical.jpg` reproduced the shell to the digit — but the .55 plate over
+  // the darker wallpaper midfield read as a separate, muddier glass beside the
+  // .38 chrome, and the owner ruled the shell shows one family: flat
+  // `--mat-rail` fill, `--w16` hairline, the `--w2` half-pixel inset,
+  // `blur(36px) saturate(180%)`.
   --window-radius: 24px;
-  --window-blur: 36px;
-  --window-backdrop-saturate: 180%;
-  --window-shadow: 0 16px 40px rgb(0 0 0 / 20%), 0 4px 10px rgb(0 0 0 / 10%);
-  --window-border: var(--w16);
-  --window-specular: inset 0 0.5px 0 var(--w2);
   --window-content-scrim: transparent;
 
+  // `--window-bg` / `--window-border` / `--window-shadow` are NOT renamed —
+  // `contextual-help-drawer.component.scss`, `agent-overlay.component.scss`
+  // and `agent-input.component.scss` all deliberately borrow these three to
+  // read as extensions of the window's own glass, so the shared names carry
+  // the new recipe forward to them for free. Only the FILL and the border step
+  // actually change value; the elevation shadow is untouched (Circles never
+  // redefined window-level elevation, only the plate).
+  --window-bg-alpha: 0.58;
+  --window-bg:
+    linear-gradient(180deg, var(--w05), transparent 20%),
+    linear-gradient(
+      rgb(22 22 24 / calc(var(--window-bg-alpha) * 100%)),
+      rgb(22 22 24 / calc(var(--window-bg-alpha) * 100%))
+    );
+  --window-border: var(--w2);
+  --window-shadow: 0 16px 40px rgb(0 0 0 / 20%), 0 4px 10px rgb(0 0 0 / 10%);
+
+  // `--window-blur` / `--window-backdrop-saturate` are RETIRED: `glass.window`
+  // (`_nova-glass.scss`) hardcodes its own tier via `_backdrop(window)`, same
+  // as every other nova-glass recipe (chrome/panel/thin never spent a token
+  // for their blur either) — `.window` no longer has its own hand-rolled
+  // backdrop-filter for a token to feed. Nothing else in the shell reads
+  // either name (`raw-backdrop-filter.spec.ts` confirms `_window-shell.scss`
+  // held the only consumer).
+
+  // `--window-specular` is RETIRED, replaced by the two-token edge split
+  // below — nothing else in the shell consumed it.
+
+  // ── Window edge / rim (`glass.window` only) ───────────────────────────────
+  // The conic specular rim + top/bottom edge split, extracted from Circles'
+  // shipped `circles-theme.scss` dark material and snapped to the nearest
+  // `--w*` ramp step (ramp law, skill §3: pick by name, never mint a new
+  // rgba) — Circles' stops (8/38/12/7/28/9%) land on exact or nearest-step
+  // matches (w08/w4/w12/w07/w28/w09). One value in both themes (mirrored
+  // verbatim in `_theme-light.scss`) — the ramp itself flips polarity per
+  // theme, which is the point of picking by step name.
+  --window-edge-gradient: conic-gradient(
+    from 210deg,
+    var(--w08),
+    var(--w4) 14%,
+    var(--w12) 34%,
+    var(--w07) 52%,
+    var(--w28) 74%,
+    var(--w09)
+  );
+  --window-edge-top: var(--w3);
+
+  // Grounding shadow, not ink — a literal, not a ramp step (the ramp is the
+  // ink/hairline family; this is a drop shadow, same convention `chrome`'s own
+  // box-shadow literals already use).
+  --window-edge-bottom: rgb(0 0 0 / 18%);
+
   // ── Titlebar ────────────────────────────────────────────────────────────────
   // The design's in-window header row (`MainContent.dc.html`): a `--w06` strip
   // over a `--w1` bottom hairline (the hairline is authored in
@@ -202,8 +261,14 @@ html.dark-theme {
     --glass-bg: #161618;
     --glass-bg-elevated: #1e1e22;
     --glass-blur: 0px;
+
+    // `--window-bg` still needs a flat opaque fallback here — the drawer/
+    // overlay/agent-input consumers above read this token directly, without
+    // going through `glass.window`'s own `_degrade()` ladder. `.window`
+    // itself is covered separately (the mixin's `_degrade()` flattens it to
+    // the generic `light-dark(#eef2f8, #2c2c2e)` plate, same as every other
+    // nova-glass recipe). `--window-blur` / `--window-backdrop-saturate` are
+    // retired above — nothing reads them any more, so no fallback needed.
     --window-bg: #141416;
-    --window-blur: 0px;
-    --window-backdrop-saturate: 100%;
   }
 }

package/scss/_theme-light.scss

@@ -161,38 +161,68 @@ html.light-theme {
   // the language actually has.
 
   // ── Window chrome ───────────────────────────────────────────────────────────
-  // ONE GLASS FAMILY, light half (2026-08-18). Dark's ruling put the window on
-  // the CHROME material — the magic bar / nav rail recipe — and this block kept
-  // the panel family whole: `.46`-class fill, the 72px panel blur, the `--w18`
-  // rim and the `--w22` inset. Only the FILL ever had a reason.
-  // —
-  // The fill genuinely diverges and stays: the mock's static `--mat-panel` plate
-  // (.46 pale slate) measures 2.74:1 for window BODY text over the dark-wallpaper
-  // majority — 2.0:1 for tertiary — which is app content unreadable in the light
-  // theme's common case, not a label on an adverse pairing. The exemption
-  // mechanism is for edges, not for the main reading surface, so the adaptive
-  // white `--fly-glass-alpha` composition stays: the thinnest white plate that
-  // holds the weakest body ink at AA over the CURRENT wallpaper (0.6 floor, one
-  // step more white over a dark room). Over bright rooms — the pairing the mock
-  // actually draws — the two plates are near-identical anyway.
-  // —
-  // The other three carried NO contrast argument. Blur radius, rim step and
-  // specular step do not enter a contrast calculation at all — they came along
-  // because the panel recipe was copied whole — and while they stayed, a light
-  // window read as a different glass from the light rail beside it: the exact
-  // complaint the dark ruling answered, still live on the other theme. They now
-  // match `glass.chrome`: 36px tier, `--w16` hairline, `--w2` inset.
-  // —
-  // What is left is one honest divergence (the fill, with a measured floor)
-  // instead of four, three of which nobody had decided.
-  --window-bg: rgb(255 255 255 / calc(var(--fly-glass-alpha) * 100%));
+  // SUPERSEDED 2026-08-2X — see `_theme-dark.scss`'s "Window chrome" section
+  // for the full supersession note; this is the light half of the same
+  // reversal. The window now takes `glass.window` in both themes instead of
+  // matching the rail/header chrome material. Only `--window-bg` diverges from
+  // dark — the adaptive `--fly-glass-alpha` white plate, kept for the same
+  // measured reason the pre-supersession note below records (kept for
+  // history) — everything else (border/shadow/edge/rim) is the identical
+  // value dark carries, mirrored verbatim rather than shared across files,
+  // matching how `--window-border`/`--window-shadow` always worked here.
+
+  // Original ruling, kept for history: ONE GLASS FAMILY, light half
+  // (2026-08-18). Dark's ruling put the window on the CHROME material — the
+  // magic bar / nav rail recipe — and this block kept the panel family whole:
+  // `.46`-class fill, the 72px panel blur, the `--w18` rim and the `--w22`
+  // inset. Only the FILL ever had a reason. The fill genuinely diverged and
+  // stayed: the mock's static `--mat-panel` plate (.46 pale slate) measured
+  // 2.74:1 for window BODY text over the dark-wallpaper majority — 2.0:1 for
+  // tertiary — which is app content unreadable in the light theme's common
+  // case, not a label on an adverse pairing, so the adaptive white
+  // `--fly-glass-alpha` composition stayed: the thinnest white plate that
+  // holds the weakest body ink at AA over the CURRENT wallpaper.
   --window-radius: 24px;
-  --window-blur: 36px;
-  --window-backdrop-saturate: 180%;
-  --window-shadow: 0 16px 40px rgb(0 0 0 / 20%), 0 4px 10px rgb(0 0 0 / 10%);
-  --window-border: var(--w16);
-  --window-specular: inset 0 0.5px 0 var(--w2);
   --window-content-scrim: transparent;
+
+  // `--window-bg` / `--window-border` / `--window-shadow` are NOT renamed —
+  // see the identical note in `_theme-dark.scss`. `--window-blur` /
+  // `--window-backdrop-saturate` are RETIRED (same reason: `glass.window`
+  // hardcodes its own tier, nothing else reads either name).
+
+  // UNCHANGED from before this recipe existed — deliberately, not an
+  // oversight: an earlier draft added dark's top-wash gradient layer here
+  // too (matching its two-layer shape), and it measured a real AA
+  // regression (`theme-contrast.spec.ts`, "window secondary text" dropped to
+  // 4.38:1 over the dark-wallpaper majority, needs 4.5) and broke the
+  // adaptive-alpha resolution `wallpaper-glass.service.ts` depends on (the
+  // knob test expects `--window-bg`'s alpha to resolve directly to
+  // `--fly-glass-alpha`, which a multi-layer composite no longer does
+  // simply). There is no Circles source for a light wash to extract in the
+  // first place (§ above), so the honest synthesis is: keep the proven-safe
+  // single-layer fill, and let the border/edge/rim carry the "richer in
+  // light too" story instead — none of those touch text contrast.
+  --window-bg: rgb(255 255 255 / calc(var(--fly-glass-alpha) * 100%));
+  --window-border: var(--w2);
+  --window-shadow: 0 16px 40px rgb(0 0 0 / 20%), 0 4px 10px rgb(0 0 0 / 10%);
+
+  // ── Window edge / rim (`glass.window` only) ───────────────────────────────
+  // No Circles source exists for light (its bespoke material only ever shipped
+  // scoped to `html.dark-theme`) — this is new design work, not extraction:
+  // the SAME `--w*` step names dark uses, letting the ramp's own per-theme
+  // polarity flip do the work (skill §3 — pick by name, never re-derive).
+  // `--window-specular` is RETIRED, replaced by the two-token edge split.
+  --window-edge-gradient: conic-gradient(
+    from 210deg,
+    var(--w08),
+    var(--w4) 14%,
+    var(--w12) 34%,
+    var(--w07) 52%,
+    var(--w28) 74%,
+    var(--w09)
+  );
+  --window-edge-top: var(--w3);
+  --window-edge-bottom: rgb(0 0 0 / 18%);
   --app-content-plate: transparent;
   --titlebar-bg: var(--w06);
   --titlebar-height: 44px;
@@ -269,8 +299,9 @@ html.light-theme {
     --glass-bg: #f7f8fa;
     --glass-bg-elevated: #fff;
     --glass-blur: 0px;
+
+    // `--window-blur` / `--window-backdrop-saturate` are retired — see the
+    // identical note in `_theme-dark.scss`'s reduced-transparency block.
     --window-bg: #f7f8fa;
-    --window-blur: 0px;
-    --window-backdrop-saturate: 100%;
   }
 }

package/types/flyos-design-system.d.ts

@@ -8790,6 +8790,22 @@ declare class FlyMagicActionsComponent {
  * string instead — {@link MagicBarActionSpec.iconPath} stays `string`.
  */
 declare const FLY_MAGIC_BAR_ICONS: {
+    /**
+     * "Download …" — an action that hands the user a FILE (Export to Excel/PDF, a
+     * generated report). Arrow down onto a baseline, the Material-style download mark.
+     *
+     * Distinct from {@link VERBATIM_FROM_UX_DROP.export} on purpose, and the distinction
+     * is the point of this entry. The drop's Export/Import pair reads the tray as the
+     * APP — data leaves it upward on export — which is coherent but inverts the reading
+     * users bring to a file transfer, where down means "arriving on my machine". Every
+     * consumer of `export` on the platform is in fact a download, so the up arrow was
+     * being read as "upload" on all of them. `export` keeps its drop geometry for a
+     * genuine data-exchange pair; anything that produces a file for the user takes this.
+     *
+     * The baseline rather than a tray also keeps it apart from `import`, which is the
+     * tray-and-down-arrow shape a download glyph would otherwise collide with.
+     */
+    readonly download: "<path d=\"M12 4v11M7.5 10.5l4.5 4.5 4.5-4.5\"/><path d=\"M5 20h14\"/>";
     /** Signal-detail "View trace" — no standalone path in the drop; an activity/pulse line. */
     readonly viewTrace: "<path d=\"M3 12h4l2-7 4 14 2-7h6\"/>";
     /** Signal-detail "Archive". */
@@ -8829,6 +8845,15 @@ declare const FLY_MAGIC_BAR_ICONS: {
     readonly export: "<path d=\"M12 16V7M8 11l4-4 4 4\"/><path d=\"M4 15v3a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-3\"/>";
     /** `Home.dc.html:616`. */
     readonly import: "<path d=\"M12 4v9M8 9l4 4 4-4\"/><path d=\"M4 15v3a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-3\"/>";
+    /**
+     * `Home.dc.html:362` — the chrome's own reload arrow, reused verbatim so a
+     * contributed "Refresh" action reads identically to the shell's reload button
+     * sitting a few pixels away in the same bar.
+     *
+     * NEVER mirror this under RTL. Its arrow is circular, and the mirrored form reads
+     * as "undo" (design §9 rule 7: only directional arrow/chevron glyphs mirror).
+     */
+    readonly refresh: "<path d=\"M20.2 12a8.2 8.2 0 1 1-2.7-6.1\"/><path d=\"M20.4 4.1v4.6h-4.6\"/>";
     /** `Home.dc.html:547` — "Mark as complete". */
     readonly check: "<circle cx=\"12\" cy=\"12\" r=\"8.6\"/><path d=\"M8.4 12.3l2.6 2.6 4.6-5\"/>";
     /** `Home.dc.html:550` — "Watch task". */
@@ -12737,10 +12762,15 @@ declare class FlyModuleIconDirective {
  * Standalone (no dock anywhere above), nothing happens and the bar renders as the
  * app's own first row, exactly as before.
  *
- * a11y: the trigger is `aria-haspopup="menu"` + `aria-expanded`; the popover is
- * `role="menu"` with `role="menuitem"` rows carrying `aria-current="page"` on
- * the active one. Arrow keys rove (RTL-aware, wrapping, skipping disabled),
- * Home/End jump, Escape closes and returns focus to the trigger, and a click
+ * The trigger is split in two: the anchor (icon + label) is a breadcrumb —
+ * click it and it re-activates the current module, the same "back to the
+ * register" nav a popover row for it already performs, without opening the
+ * popover. The chevron alone is the switcher's `aria-haspopup="menu"` +
+ * `aria-expanded` trigger. The popover is `role="menu"` with `role="menuitem"`
+ * rows carrying `aria-current="page"` on the active one.
+ *
+ * a11y: arrow keys rove the popover (RTL-aware, wrapping, skipping disabled),
+ * Home/End jump, Escape closes and returns focus to the chevron, and a click
  * outside closes. Only the topmost overlay answers Escape, so a switcher opened
  * over a drawer closes alone.
  */
@@ -12784,12 +12814,21 @@ declare class FlyAppTopbarComponent {
     protected readonly activeModule: _angular_core.Signal<FlyAppModule | null>;
     protected readonly brandAriaLabel: _angular_core.Signal<string>;
     protected readonly switchAriaLabel: _angular_core.Signal<string>;
-    protected readonly triggerAriaLabel: _angular_core.Signal<string>;
     constructor();
     private dockIntoHostChrome;
     protected iconFor(key: string): TemplateRef<unknown> | null;
     protected indexOf(mod: FlyAppModule): number;
     protected toggle(): void;
+    /**
+     * The anchor (icon + label) is a breadcrumb crumb, not the switcher's
+     * trigger — that's the chevron's job now. Clicking it re-activates the
+     * CURRENT module, the same "back to the register" navigation a click on its
+     * own row in the popover already performs, without opening the popover to
+     * get there. Only when nothing is active yet (the neutral "Select a
+     * module" state, nothing to go back to) does it fall back to opening the
+     * switcher, matching the old combined-trigger behaviour for that state.
+     */
+    protected onAnchorClick(): void;
     private openMenu;
     protected close(restoreFocus?: boolean): void;
     protected select(mod: FlyAppModule): void;