@wildo-ai/presets-components-3d 1.1.6

package/LICENSE

@@ -0,0 +1,34 @@
+Copyright (c) 2026 P2C Consulting, s.à r.l.-S
+RCS Luxembourg B307591
+6C, Porte de France, L-4360 Esch-sur-Alzette, Luxembourg
+
+All rights reserved.
+
+This software and its accompanying materials (the "Software") are the
+confidential and proprietary property of P2C Consulting, s.à r.l.-S (the
+"Licensor"). The Software is made available for viewing only. No licence,
+right, or permission of any kind is granted by its publication or by its
+availability on any package registry or source repository.
+
+Without the Licensor's prior written permission, you may not use, copy,
+reproduce, modify, adapt, translate, merge, publish, distribute, sublicense,
+sell, host, or create derivative works of the Software, in whole or in part,
+nor use it to provide a service to any third party.
+
+Publication of the Software in any public registry is for distribution to
+authorised recipients and for technical evaluation of its packaging only. It
+does not place the Software in the public domain, does not constitute an open
+source release, and does not waive any right of the Licensor.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Third-party components distributed with the Software remain governed by their
+own licences.
+
+Contact: P2C Consulting, s.à r.l.-S, 6C, Porte de France, L-4360
+Esch-sur-Alzette, Luxembourg.

package/dist/esm/frame/frame-3d-style.d.ts

@@ -0,0 +1,156 @@
+import { DesignSystemToken, ShellRegion } from '@wildo-ai/presets-components-models';
+/** @wildo_source:part:start presets.3d.frame-style-overrides facet:layer:frontend facet:family:layout-3d facet:audience:app-developer */
+/**
+ * What the frame draws under one shell region.
+ *
+ * A frame style is the 3D frame's OWN vocabulary: it says how a region's slab looks, never how the region
+ * itself looks. The region stays the 2D preset's HTML, with its recipes and Tailwind classes untouched; the
+ * engine's theme and recipe schemas are not extended for the frame.
+ */
+export declare enum Frame3DSurfaceKind {
+    /** A frosted slab: a translucent tint over the in-scene background, with a rim and an optional shadow. */
+    FROSTED = "frosted",
+    /** Nothing is drawn under the region. */
+    NONE = "none"
+}
+/** The rim: a thin edge line along the slab, emphasised while the pointer is over the region. */
+export interface Frame3DRimStyle {
+    /** The colour token of the rim. */
+    token: DesignSystemToken;
+    /** Rim opacity at rest, 0–1. */
+    opacity: number;
+    /** Rim opacity while the pointer is over the region, 0–1. The only thing hover changes. */
+    hoverOpacity: number;
+    /** Rim width as a multiple of the `border-width` token. */
+    widthScale: number;
+}
+/** The slab's shadow, drawn on the scene background just outside the slab. Its colour is black. */
+export interface Frame3DShadowStyle {
+    offsetXPx: number;
+    offsetYPx: number;
+    /** Blur radius in CSS pixels; 0 draws a hard shadow. */
+    blurPx: number;
+    /** Shadow opacity, 0–1. */
+    opacity: number;
+}
+/** How the frame draws under one region kind. */
+export interface Frame3DRegionStyle {
+    surface: Frame3DSurfaceKind;
+    /** The colour token the frost is tinted with. Ignored when `tintColor` is set. */
+    tintToken: DesignSystemToken;
+    /**
+     * An explicit CSS colour for the frost instead of a token: a brand colour, or the verification sentinel
+     * ({@link createSentinelFrameStyles}). The contrast bound still applies to it.
+     */
+    tintColor?: string;
+    /** Frost opacity over the scene background, 0–1. A glass theme's navigation material replaces it. */
+    frost: number;
+    /** How much lighter the lit side of the slab is than its shaded side, 0–1. */
+    gradient: number;
+    /** Corner radius as a multiple of the `radius` token. */
+    radiusScale: number;
+    rim: Frame3DRimStyle;
+    shadow: Frame3DShadowStyle;
+}
+/** The in-scene background the slabs sit on: the page's own `backgroundLayer` cannot be sampled by WebGL. */
+export interface Frame3DBackgroundStyle {
+    /** The base colour token. */
+    baseToken: DesignSystemToken;
+    /** The token of the glow on the lit side. */
+    glowToken: DesignSystemToken;
+    /** Glow strength: how far the lit side moves from the base colour toward the glow colour, 0–1. */
+    glow: number;
+}
+/** Everything the frame draws for one theme. `regions` is total over `ShellRegion`: a new region kind must be styled. */
+export interface Frame3DThemeStyle {
+    background: Frame3DBackgroundStyle;
+    /**
+     * The direction the light comes from, in degrees, y UP: 0 = from the right, 90 = from the top. (A glass
+     * navigation material replaces it, converted from the engine's y-down convention.)
+     */
+    lightAngleDeg: number;
+    /**
+     * The colour of the light: the lit side of every slab moves toward it. `primary` by default — the colour the
+     * background's glow uses too — so the lit side takes a cast of the theme's own light. (A surface token would be
+     * the frost's own colour, and a slab lit by itself shows no gradient at all.)
+     */
+    lightToken: DesignSystemToken;
+    /** In dark mode the lit side moves this share of the way it does in light mode (a dimmer light rig), 0–1. */
+    darkModeLightStrength: number;
+    regions: Record<ShellRegion, Frame3DRegionStyle>;
+}
+/**
+ * The ids of the themes the framework ships, which the built-in frame styles are keyed on. Theme ids are an
+ * open vocabulary (an application can author its own theme); any id not listed here takes the fallback style.
+ */
+export declare enum Frame3DBuiltInThemeId {
+    DEFAULT = "default",
+    COZY = "cozy",
+    DENSE = "dense",
+    EDITORIAL = "editorial",
+    GLASS = "glass",
+    NEO_BRUTALIST = "neo-brutalist",
+    TERMINAL = "terminal",
+    TRADING = "trading"
+}
+/** A partial frame style an application layers over a built-in one; nested objects merge key by key. */
+export interface Frame3DThemeStyleOverride {
+    background?: Partial<Frame3DBackgroundStyle>;
+    lightAngleDeg?: number;
+    lightToken?: DesignSystemToken;
+    darkModeLightStrength?: number;
+    regions?: Partial<Record<ShellRegion, Frame3DRegionStyleOverride>>;
+}
+export type Frame3DRegionStyleOverride = Partial<Omit<Frame3DRegionStyle, 'rim' | 'shadow'>> & {
+    rim?: Partial<Frame3DRimStyle>;
+    shadow?: Partial<Frame3DShadowStyle>;
+};
+/**
+ * An application's frame-style overrides, passed to `register3DLayout({ frameStyles })`. `all` applies to
+ * every theme; `byThemeId` applies to one theme id and is layered after `all`.
+ */
+export interface Frame3DStyleOverrides {
+    all?: Frame3DThemeStyleOverride;
+    byThemeId?: Partial<Record<string, Frame3DThemeStyleOverride>>;
+}
+/** @wildo_source:part:end presets.3d.frame-style-overrides */
+/** The styles a layout's scene ships: one per built-in theme, and the fallback for any other theme id. */
+export interface Frame3DStyleCatalog {
+    byThemeId: Record<Frame3DBuiltInThemeId, Frame3DThemeStyle>;
+    fallback: Frame3DThemeStyle;
+}
+/**
+ * The INHERIT layout's styles. Each built-in entry expresses its theme's character in the frame's own terms:
+ * cozy is softer and rounder, dense and trading are tight and flat, editorial is nearly square and quiet,
+ * neo-brutalist is solid with a heavy rim and a hard offset shadow, terminal is square with a primary rim.
+ * Colours always come from the tokens; a style only chooses WHICH token and how strongly.
+ */
+export declare const INHERIT_FRAME_STYLES: Frame3DStyleCatalog;
+/**
+ * The HEADER_FIRST layout's styles: the INHERIT styles, lit from straight above — the menubar spans the whole
+ * width over the rails in that disposal, so the light falls from the header down.
+ */
+export declare const HEADER_FIRST_FRAME_STYLES: Frame3DStyleCatalog;
+/**
+ * The frame style for the active theme: the layout's catalog entry for a built-in theme id (its fallback for any
+ * other id), then the application's `all` override, then its override for that theme id.
+ */
+export declare function resolveFrame3DThemeStyle(catalog: Frame3DStyleCatalog, themeId: string, overrides?: Frame3DStyleOverrides): Frame3DThemeStyle;
+/**
+ * The frame's verification sentinel: a neon green (`#39ff14`) that appears in no theme, token or palette in the
+ * framework or the dogfood applications (checked 2026-09-29 by a repository search).
+ *
+ * That absence is the point. A cover check counts sentinel pixels in a screenshot: one where a region is
+ * transparent over its slab is expected, one over a region's CONTENT means the canvas covered it — and a colour
+ * a theme could also produce would make that count meaningless.
+ */
+export declare const FRAME_SENTINEL_COLOR = "#39ff14";
+/**
+ * Frame-style overrides that draw every region as a flat, square, rimless, shadowless slab in
+ * {@link FRAME_SENTINEL_COLOR}, for a cover-and-alignment check: `register3DLayout({ frameStyles:
+ * createSentinelFrameStyles() })`. The contrast bound still applies, so run the check where the sentinel passes
+ * it against the foreground (a light mode, whose foreground is dark) — and assert the sentinel is actually
+ * visible where regions are transparent, or a bound-adjusted colour would read as "nothing covered".
+ */
+export declare function createSentinelFrameStyles(): Frame3DStyleOverrides;
+//# sourceMappingURL=frame-3d-style.d.ts.map

package/dist/esm/frame/frame-3d-style.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-3d-style.d.ts","sourceRoot":"","sources":["../../../../src/frame/frame-3d-style.ts"],"names":[],"mappings":"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"}

package/dist/esm/frame/frame-3d-style.js

@@ -0,0 +1,229 @@
+import { DesignSystemToken, ShellRegion } from '@wildo-ai/presets-components-models';
+/** @wildo_source:part:start presets.3d.frame-style-overrides facet:layer:frontend facet:family:layout-3d facet:audience:app-developer */
+/**
+ * What the frame draws under one shell region.
+ *
+ * A frame style is the 3D frame's OWN vocabulary: it says how a region's slab looks, never how the region
+ * itself looks. The region stays the 2D preset's HTML, with its recipes and Tailwind classes untouched; the
+ * engine's theme and recipe schemas are not extended for the frame.
+ */
+export var Frame3DSurfaceKind;
+(function (Frame3DSurfaceKind) {
+    /** A frosted slab: a translucent tint over the in-scene background, with a rim and an optional shadow. */
+    Frame3DSurfaceKind["FROSTED"] = "frosted";
+    /** Nothing is drawn under the region. */
+    Frame3DSurfaceKind["NONE"] = "none";
+})(Frame3DSurfaceKind || (Frame3DSurfaceKind = {}));
+/**
+ * The ids of the themes the framework ships, which the built-in frame styles are keyed on. Theme ids are an
+ * open vocabulary (an application can author its own theme); any id not listed here takes the fallback style.
+ */
+export var Frame3DBuiltInThemeId;
+(function (Frame3DBuiltInThemeId) {
+    Frame3DBuiltInThemeId["DEFAULT"] = "default";
+    Frame3DBuiltInThemeId["COZY"] = "cozy";
+    Frame3DBuiltInThemeId["DENSE"] = "dense";
+    Frame3DBuiltInThemeId["EDITORIAL"] = "editorial";
+    Frame3DBuiltInThemeId["GLASS"] = "glass";
+    Frame3DBuiltInThemeId["NEO_BRUTALIST"] = "neo-brutalist";
+    Frame3DBuiltInThemeId["TERMINAL"] = "terminal";
+    Frame3DBuiltInThemeId["TRADING"] = "trading";
+})(Frame3DBuiltInThemeId || (Frame3DBuiltInThemeId = {}));
+const NO_SHADOW = { offsetXPx: 0, offsetYPx: 0, blurPx: 0, opacity: 0 };
+/**
+ * One theme's region table from a chrome style (the bars and rails) and a content style (the `<main>`). Written
+ * as an object literal over every `ShellRegion` member, so a member added to the enum fails to compile here
+ * instead of silently falling through to nothing.
+ */
+function regionStyles(chrome, content) {
+    return {
+        [ShellRegion.MENUBAR]: chrome,
+        [ShellRegion.SIDEBAR]: chrome,
+        [ShellRegion.TOOLBAR]: chrome,
+        [ShellRegion.ACTIVITY_BAR]: chrome,
+        [ShellRegion.UTILITY_PANEL]: chrome,
+        [ShellRegion.STATUS_BAR]: chrome,
+        [ShellRegion.CONTENT]: content,
+    };
+}
+function theme(input) {
+    const chrome = {
+        surface: Frame3DSurfaceKind.FROSTED,
+        tintToken: DesignSystemToken.SURFACE_RAISED,
+        frost: input.frost,
+        gradient: input.gradient,
+        radiusScale: input.radiusScale,
+        rim: input.rim,
+        shadow: input.shadow,
+    };
+    const content = { ...chrome, tintToken: DesignSystemToken.SURFACE_DEFAULT, frost: input.contentFrost };
+    return {
+        background: { baseToken: DesignSystemToken.BACKGROUND, glowToken: input.glowToken ?? DesignSystemToken.PRIMARY, glow: input.glow },
+        lightAngleDeg: input.lightAngleDeg ?? 110,
+        lightToken: DesignSystemToken.PRIMARY,
+        darkModeLightStrength: 0.5,
+        regions: regionStyles(chrome, content),
+    };
+}
+const DEFAULT_STYLE = theme({
+    radiusScale: 1,
+    frost: 0.5,
+    contentFrost: 0.55,
+    gradient: 0.06,
+    rim: { token: DesignSystemToken.BORDER, opacity: 0.5, hoverOpacity: 0.9, widthScale: 1 },
+    shadow: { offsetXPx: 0, offsetYPx: 6, blurPx: 18, opacity: 0.12 },
+    glow: 0.08,
+});
+/**
+ * The INHERIT layout's styles. Each built-in entry expresses its theme's character in the frame's own terms:
+ * cozy is softer and rounder, dense and trading are tight and flat, editorial is nearly square and quiet,
+ * neo-brutalist is solid with a heavy rim and a hard offset shadow, terminal is square with a primary rim.
+ * Colours always come from the tokens; a style only chooses WHICH token and how strongly.
+ */
+export const INHERIT_FRAME_STYLES = {
+    byThemeId: {
+        [Frame3DBuiltInThemeId.DEFAULT]: DEFAULT_STYLE,
+        [Frame3DBuiltInThemeId.COZY]: theme({
+            radiusScale: 1.5,
+            frost: 0.6,
+            contentFrost: 0.62,
+            gradient: 0.08,
+            rim: { token: DesignSystemToken.BORDER, opacity: 0.35, hoverOpacity: 0.75, widthScale: 1 },
+            shadow: { offsetXPx: 0, offsetYPx: 10, blurPx: 28, opacity: 0.1 },
+            glow: 0.1,
+        }),
+        [Frame3DBuiltInThemeId.DENSE]: theme({
+            radiusScale: 0.5,
+            frost: 0.4,
+            contentFrost: 0.45,
+            gradient: 0.03,
+            rim: { token: DesignSystemToken.BORDER, opacity: 0.6, hoverOpacity: 0.9, widthScale: 1 },
+            shadow: NO_SHADOW,
+            glow: 0.04,
+        }),
+        [Frame3DBuiltInThemeId.EDITORIAL]: theme({
+            radiusScale: 0.25,
+            frost: 0.3,
+            contentFrost: 0.35,
+            gradient: 0,
+            rim: { token: DesignSystemToken.BORDER, opacity: 0.25, hoverOpacity: 0.5, widthScale: 1 },
+            shadow: NO_SHADOW,
+            glow: 0.03,
+        }),
+        [Frame3DBuiltInThemeId.GLASS]: theme({
+            radiusScale: 1.25,
+            frost: 0.3,
+            contentFrost: 0.35,
+            gradient: 0.12,
+            rim: { token: DesignSystemToken.BORDER_STRONG, opacity: 0.6, hoverOpacity: 1, widthScale: 1 },
+            shadow: { offsetXPx: 0, offsetYPx: 8, blurPx: 24, opacity: 0.15 },
+            glow: 0.14,
+        }),
+        [Frame3DBuiltInThemeId.NEO_BRUTALIST]: theme({
+            radiusScale: 0,
+            frost: 0.92,
+            contentFrost: 0.92,
+            gradient: 0,
+            rim: { token: DesignSystemToken.FOREGROUND, opacity: 1, hoverOpacity: 1, widthScale: 2 },
+            shadow: { offsetXPx: 4, offsetYPx: 4, blurPx: 0, opacity: 1 },
+            glow: 0,
+        }),
+        [Frame3DBuiltInThemeId.TERMINAL]: theme({
+            radiusScale: 0,
+            frost: 0.25,
+            contentFrost: 0.3,
+            gradient: 0,
+            rim: { token: DesignSystemToken.PRIMARY, opacity: 0.5, hoverOpacity: 0.9, widthScale: 1 },
+            shadow: NO_SHADOW,
+            glow: 0.12,
+        }),
+        [Frame3DBuiltInThemeId.TRADING]: theme({
+            radiusScale: 0.5,
+            frost: 0.45,
+            contentFrost: 0.5,
+            gradient: 0.02,
+            rim: { token: DesignSystemToken.BORDER, opacity: 0.45, hoverOpacity: 0.8, widthScale: 1 },
+            shadow: NO_SHADOW,
+            glow: 0.05,
+        }),
+    },
+    fallback: DEFAULT_STYLE,
+};
+/**
+ * The HEADER_FIRST layout's styles: the INHERIT styles, lit from straight above — the menubar spans the whole
+ * width over the rails in that disposal, so the light falls from the header down.
+ */
+export const HEADER_FIRST_FRAME_STYLES = withLightAngle(INHERIT_FRAME_STYLES, 90);
+function withLightAngle(catalog, lightAngleDeg) {
+    const byThemeId = {};
+    for (const id of Object.values(Frame3DBuiltInThemeId))
+        byThemeId[id] = { ...catalog.byThemeId[id], lightAngleDeg };
+    return { byThemeId, fallback: { ...catalog.fallback, lightAngleDeg } };
+}
+function isBuiltInThemeId(id) {
+    return Object.values(Frame3DBuiltInThemeId).includes(id);
+}
+function mergeTheme(base, override) {
+    if (!override)
+        return base;
+    const regions = { ...base.regions };
+    for (const region of Object.values(ShellRegion)) {
+        const regionOverride = override.regions?.[region];
+        if (!regionOverride)
+            continue;
+        const current = regions[region];
+        regions[region] = {
+            ...current,
+            ...regionOverride,
+            rim: { ...current.rim, ...regionOverride.rim },
+            shadow: { ...current.shadow, ...regionOverride.shadow },
+        };
+    }
+    return {
+        background: { ...base.background, ...override.background },
+        lightAngleDeg: override.lightAngleDeg ?? base.lightAngleDeg,
+        lightToken: override.lightToken ?? base.lightToken,
+        darkModeLightStrength: override.darkModeLightStrength ?? base.darkModeLightStrength,
+        regions,
+    };
+}
+/**
+ * The frame style for the active theme: the layout's catalog entry for a built-in theme id (its fallback for any
+ * other id), then the application's `all` override, then its override for that theme id.
+ */
+export function resolveFrame3DThemeStyle(catalog, themeId, overrides) {
+    const base = isBuiltInThemeId(themeId) ? catalog.byThemeId[themeId] : catalog.fallback;
+    return mergeTheme(mergeTheme(base, overrides?.all), overrides?.byThemeId?.[themeId]);
+}
+/**
+ * The frame's verification sentinel: a neon green (`#39ff14`) that appears in no theme, token or palette in the
+ * framework or the dogfood applications (checked 2026-09-29 by a repository search).
+ *
+ * That absence is the point. A cover check counts sentinel pixels in a screenshot: one where a region is
+ * transparent over its slab is expected, one over a region's CONTENT means the canvas covered it — and a colour
+ * a theme could also produce would make that count meaningless.
+ */
+export const FRAME_SENTINEL_COLOR = '#39ff14';
+/**
+ * Frame-style overrides that draw every region as a flat, square, rimless, shadowless slab in
+ * {@link FRAME_SENTINEL_COLOR}, for a cover-and-alignment check: `register3DLayout({ frameStyles:
+ * createSentinelFrameStyles() })`. The contrast bound still applies, so run the check where the sentinel passes
+ * it against the foreground (a light mode, whose foreground is dark) — and assert the sentinel is actually
+ * visible where regions are transparent, or a bound-adjusted colour would read as "nothing covered".
+ */
+export function createSentinelFrameStyles() {
+    const sentinel = {
+        surface: Frame3DSurfaceKind.FROSTED,
+        tintColor: FRAME_SENTINEL_COLOR,
+        frost: 1,
+        gradient: 0,
+        radiusScale: 0,
+        rim: { opacity: 0, hoverOpacity: 0 },
+        shadow: NO_SHADOW,
+    };
+    const regions = {};
+    for (const region of Object.values(ShellRegion))
+        regions[region] = sentinel;
+    return { all: { regions } };
+}
+//# sourceMappingURL=frame-3d-style.js.map

package/dist/esm/frame/frame-3d-style.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-3d-style.js","sourceRoot":"","sources":["../../../../src/frame/frame-3d-style.ts"],"names":[],"mappings":"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","sourcesContent":["import { DesignSystemToken, ShellRegion } from '@wildo-ai/presets-components-models';\n\n/** @wildo_source:part:start presets.3d.frame-style-overrides facet:layer:frontend facet:family:layout-3d facet:audience:app-developer */\n/**\n * What the frame draws under one shell region.\n *\n * A frame style is the 3D frame's OWN vocabulary: it says how a region's slab looks, never how the region\n * itself looks. The region stays the 2D preset's HTML, with its recipes and Tailwind classes untouched; the\n * engine's theme and recipe schemas are not extended for the frame.\n */\nexport enum Frame3DSurfaceKind {\n  /** A frosted slab: a translucent tint over the in-scene background, with a rim and an optional shadow. */\n  FROSTED = 'frosted',\n  /** Nothing is drawn under the region. */\n  NONE = 'none',\n}\n\n/** The rim: a thin edge line along the slab, emphasised while the pointer is over the region. */\nexport interface Frame3DRimStyle {\n  /** The colour token of the rim. */\n  token: DesignSystemToken;\n  /** Rim opacity at rest, 0–1. */\n  opacity: number;\n  /** Rim opacity while the pointer is over the region, 0–1. The only thing hover changes. */\n  hoverOpacity: number;\n  /** Rim width as a multiple of the `border-width` token. */\n  widthScale: number;\n}\n\n/** The slab's shadow, drawn on the scene background just outside the slab. Its colour is black. */\nexport interface Frame3DShadowStyle {\n  offsetXPx: number;\n  offsetYPx: number;\n  /** Blur radius in CSS pixels; 0 draws a hard shadow. */\n  blurPx: number;\n  /** Shadow opacity, 0–1. */\n  opacity: number;\n}\n\n/** How the frame draws under one region kind. */\nexport interface Frame3DRegionStyle {\n  surface: Frame3DSurfaceKind;\n  /** The colour token the frost is tinted with. Ignored when `tintColor` is set. */\n  tintToken: DesignSystemToken;\n  /**\n   * An explicit CSS colour for the frost instead of a token: a brand colour, or the verification sentinel\n   * ({@link createSentinelFrameStyles}). The contrast bound still applies to it.\n   */\n  tintColor?: string;\n  /** Frost opacity over the scene background, 0–1. A glass theme's navigation material replaces it. */\n  frost: number;\n  /** How much lighter the lit side of the slab is than its shaded side, 0–1. */\n  gradient: number;\n  /** Corner radius as a multiple of the `radius` token. */\n  radiusScale: number;\n  rim: Frame3DRimStyle;\n  shadow: Frame3DShadowStyle;\n}\n\n/** The in-scene background the slabs sit on: the page's own `backgroundLayer` cannot be sampled by WebGL. */\nexport interface Frame3DBackgroundStyle {\n  /** The base colour token. */\n  baseToken: DesignSystemToken;\n  /** The token of the glow on the lit side. */\n  glowToken: DesignSystemToken;\n  /** Glow strength: how far the lit side moves from the base colour toward the glow colour, 0–1. */\n  glow: number;\n}\n\n/** Everything the frame draws for one theme. `regions` is total over `ShellRegion`: a new region kind must be styled. */\nexport interface Frame3DThemeStyle {\n  background: Frame3DBackgroundStyle;\n  /**\n   * The direction the light comes from, in degrees, y UP: 0 = from the right, 90 = from the top. (A glass\n   * navigation material replaces it, converted from the engine's y-down convention.)\n   */\n  lightAngleDeg: number;\n  /**\n   * The colour of the light: the lit side of every slab moves toward it. `primary` by default — the colour the\n   * background's glow uses too — so the lit side takes a cast of the theme's own light. (A surface token would be\n   * the frost's own colour, and a slab lit by itself shows no gradient at all.)\n   */\n  lightToken: DesignSystemToken;\n  /** In dark mode the lit side moves this share of the way it does in light mode (a dimmer light rig), 0–1. */\n  darkModeLightStrength: number;\n  regions: Record<ShellRegion, Frame3DRegionStyle>;\n}\n\n/**\n * The ids of the themes the framework ships, which the built-in frame styles are keyed on. Theme ids are an\n * open vocabulary (an application can author its own theme); any id not listed here takes the fallback style.\n */\nexport enum Frame3DBuiltInThemeId {\n  DEFAULT = 'default',\n  COZY = 'cozy',\n  DENSE = 'dense',\n  EDITORIAL = 'editorial',\n  GLASS = 'glass',\n  NEO_BRUTALIST = 'neo-brutalist',\n  TERMINAL = 'terminal',\n  TRADING = 'trading',\n}\n\n/** A partial frame style an application layers over a built-in one; nested objects merge key by key. */\nexport interface Frame3DThemeStyleOverride {\n  background?: Partial<Frame3DBackgroundStyle>;\n  lightAngleDeg?: number;\n  lightToken?: DesignSystemToken;\n  darkModeLightStrength?: number;\n  regions?: Partial<Record<ShellRegion, Frame3DRegionStyleOverride>>;\n}\n\nexport type Frame3DRegionStyleOverride = Partial<Omit<Frame3DRegionStyle, 'rim' | 'shadow'>> & {\n  rim?: Partial<Frame3DRimStyle>;\n  shadow?: Partial<Frame3DShadowStyle>;\n};\n\n/**\n * An application's frame-style overrides, passed to `register3DLayout({ frameStyles })`. `all` applies to\n * every theme; `byThemeId` applies to one theme id and is layered after `all`.\n */\nexport interface Frame3DStyleOverrides {\n  all?: Frame3DThemeStyleOverride;\n  byThemeId?: Partial<Record<string, Frame3DThemeStyleOverride>>;\n}\n/** @wildo_source:part:end presets.3d.frame-style-overrides */\n\n/** The styles a layout's scene ships: one per built-in theme, and the fallback for any other theme id. */\nexport interface Frame3DStyleCatalog {\n  byThemeId: Record<Frame3DBuiltInThemeId, Frame3DThemeStyle>;\n  fallback: Frame3DThemeStyle;\n}\n\nconst NO_SHADOW: Frame3DShadowStyle = { offsetXPx: 0, offsetYPx: 0, blurPx: 0, opacity: 0 };\n\n/**\n * One theme's region table from a chrome style (the bars and rails) and a content style (the `<main>`). Written\n * as an object literal over every `ShellRegion` member, so a member added to the enum fails to compile here\n * instead of silently falling through to nothing.\n */\nfunction regionStyles(chrome: Frame3DRegionStyle, content: Frame3DRegionStyle): Record<ShellRegion, Frame3DRegionStyle> {\n  return {\n    [ShellRegion.MENUBAR]: chrome,\n    [ShellRegion.SIDEBAR]: chrome,\n    [ShellRegion.TOOLBAR]: chrome,\n    [ShellRegion.ACTIVITY_BAR]: chrome,\n    [ShellRegion.UTILITY_PANEL]: chrome,\n    [ShellRegion.STATUS_BAR]: chrome,\n    [ShellRegion.CONTENT]: content,\n  };\n}\n\nfunction theme(input: {\n  radiusScale: number;\n  frost: number;\n  contentFrost: number;\n  gradient: number;\n  rim: Frame3DRimStyle;\n  shadow: Frame3DShadowStyle;\n  glow: number;\n  glowToken?: DesignSystemToken;\n  lightAngleDeg?: number;\n}): Frame3DThemeStyle {\n  const chrome: Frame3DRegionStyle = {\n    surface: Frame3DSurfaceKind.FROSTED,\n    tintToken: DesignSystemToken.SURFACE_RAISED,\n    frost: input.frost,\n    gradient: input.gradient,\n    radiusScale: input.radiusScale,\n    rim: input.rim,\n    shadow: input.shadow,\n  };\n  const content: Frame3DRegionStyle = { ...chrome, tintToken: DesignSystemToken.SURFACE_DEFAULT, frost: input.contentFrost };\n  return {\n    background: { baseToken: DesignSystemToken.BACKGROUND, glowToken: input.glowToken ?? DesignSystemToken.PRIMARY, glow: input.glow },\n    lightAngleDeg: input.lightAngleDeg ?? 110,\n    lightToken: DesignSystemToken.PRIMARY,\n    darkModeLightStrength: 0.5,\n    regions: regionStyles(chrome, content),\n  };\n}\n\nconst DEFAULT_STYLE = theme({\n  radiusScale: 1,\n  frost: 0.5,\n  contentFrost: 0.55,\n  gradient: 0.06,\n  rim: { token: DesignSystemToken.BORDER, opacity: 0.5, hoverOpacity: 0.9, widthScale: 1 },\n  shadow: { offsetXPx: 0, offsetYPx: 6, blurPx: 18, opacity: 0.12 },\n  glow: 0.08,\n});\n\n/**\n * The INHERIT layout's styles. Each built-in entry expresses its theme's character in the frame's own terms:\n * cozy is softer and rounder, dense and trading are tight and flat, editorial is nearly square and quiet,\n * neo-brutalist is solid with a heavy rim and a hard offset shadow, terminal is square with a primary rim.\n * Colours always come from the tokens; a style only chooses WHICH token and how strongly.\n */\nexport const INHERIT_FRAME_STYLES: Frame3DStyleCatalog = {\n  byThemeId: {\n    [Frame3DBuiltInThemeId.DEFAULT]: DEFAULT_STYLE,\n    [Frame3DBuiltInThemeId.COZY]: theme({\n      radiusScale: 1.5,\n      frost: 0.6,\n      contentFrost: 0.62,\n      gradient: 0.08,\n      rim: { token: DesignSystemToken.BORDER, opacity: 0.35, hoverOpacity: 0.75, widthScale: 1 },\n      shadow: { offsetXPx: 0, offsetYPx: 10, blurPx: 28, opacity: 0.1 },\n      glow: 0.1,\n    }),\n    [Frame3DBuiltInThemeId.DENSE]: theme({\n      radiusScale: 0.5,\n      frost: 0.4,\n      contentFrost: 0.45,\n      gradient: 0.03,\n      rim: { token: DesignSystemToken.BORDER, opacity: 0.6, hoverOpacity: 0.9, widthScale: 1 },\n      shadow: NO_SHADOW,\n      glow: 0.04,\n    }),\n    [Frame3DBuiltInThemeId.EDITORIAL]: theme({\n      radiusScale: 0.25,\n      frost: 0.3,\n      contentFrost: 0.35,\n      gradient: 0,\n      rim: { token: DesignSystemToken.BORDER, opacity: 0.25, hoverOpacity: 0.5, widthScale: 1 },\n      shadow: NO_SHADOW,\n      glow: 0.03,\n    }),\n    [Frame3DBuiltInThemeId.GLASS]: theme({\n      radiusScale: 1.25,\n      frost: 0.3,\n      contentFrost: 0.35,\n      gradient: 0.12,\n      rim: { token: DesignSystemToken.BORDER_STRONG, opacity: 0.6, hoverOpacity: 1, widthScale: 1 },\n      shadow: { offsetXPx: 0, offsetYPx: 8, blurPx: 24, opacity: 0.15 },\n      glow: 0.14,\n    }),\n    [Frame3DBuiltInThemeId.NEO_BRUTALIST]: theme({\n      radiusScale: 0,\n      frost: 0.92,\n      contentFrost: 0.92,\n      gradient: 0,\n      rim: { token: DesignSystemToken.FOREGROUND, opacity: 1, hoverOpacity: 1, widthScale: 2 },\n      shadow: { offsetXPx: 4, offsetYPx: 4, blurPx: 0, opacity: 1 },\n      glow: 0,\n    }),\n    [Frame3DBuiltInThemeId.TERMINAL]: theme({\n      radiusScale: 0,\n      frost: 0.25,\n      contentFrost: 0.3,\n      gradient: 0,\n      rim: { token: DesignSystemToken.PRIMARY, opacity: 0.5, hoverOpacity: 0.9, widthScale: 1 },\n      shadow: NO_SHADOW,\n      glow: 0.12,\n    }),\n    [Frame3DBuiltInThemeId.TRADING]: theme({\n      radiusScale: 0.5,\n      frost: 0.45,\n      contentFrost: 0.5,\n      gradient: 0.02,\n      rim: { token: DesignSystemToken.BORDER, opacity: 0.45, hoverOpacity: 0.8, widthScale: 1 },\n      shadow: NO_SHADOW,\n      glow: 0.05,\n    }),\n  },\n  fallback: DEFAULT_STYLE,\n};\n\n/**\n * The HEADER_FIRST layout's styles: the INHERIT styles, lit from straight above — the menubar spans the whole\n * width over the rails in that disposal, so the light falls from the header down.\n */\nexport const HEADER_FIRST_FRAME_STYLES: Frame3DStyleCatalog = withLightAngle(INHERIT_FRAME_STYLES, 90);\n\nfunction withLightAngle(catalog: Frame3DStyleCatalog, lightAngleDeg: number): Frame3DStyleCatalog {\n  const byThemeId = {} as Record<Frame3DBuiltInThemeId, Frame3DThemeStyle>;\n  for (const id of Object.values(Frame3DBuiltInThemeId)) byThemeId[id] = { ...catalog.byThemeId[id], lightAngleDeg };\n  return { byThemeId, fallback: { ...catalog.fallback, lightAngleDeg } };\n}\n\nfunction isBuiltInThemeId(id: string): id is Frame3DBuiltInThemeId {\n  return (Object.values(Frame3DBuiltInThemeId) as string[]).includes(id);\n}\n\nfunction mergeTheme(base: Frame3DThemeStyle, override: Frame3DThemeStyleOverride | undefined): Frame3DThemeStyle {\n  if (!override) return base;\n  const regions = { ...base.regions };\n  for (const region of Object.values(ShellRegion)) {\n    const regionOverride = override.regions?.[region];\n    if (!regionOverride) continue;\n    const current = regions[region];\n    regions[region] = {\n      ...current,\n      ...regionOverride,\n      rim: { ...current.rim, ...regionOverride.rim },\n      shadow: { ...current.shadow, ...regionOverride.shadow },\n    };\n  }\n  return {\n    background: { ...base.background, ...override.background },\n    lightAngleDeg: override.lightAngleDeg ?? base.lightAngleDeg,\n    lightToken: override.lightToken ?? base.lightToken,\n    darkModeLightStrength: override.darkModeLightStrength ?? base.darkModeLightStrength,\n    regions,\n  };\n}\n\n/**\n * The frame style for the active theme: the layout's catalog entry for a built-in theme id (its fallback for any\n * other id), then the application's `all` override, then its override for that theme id.\n */\nexport function resolveFrame3DThemeStyle(catalog: Frame3DStyleCatalog, themeId: string, overrides?: Frame3DStyleOverrides): Frame3DThemeStyle {\n  const base = isBuiltInThemeId(themeId) ? catalog.byThemeId[themeId] : catalog.fallback;\n  return mergeTheme(mergeTheme(base, overrides?.all), overrides?.byThemeId?.[themeId]);\n}\n\n/**\n * The frame's verification sentinel: a neon green (`#39ff14`) that appears in no theme, token or palette in the\n * framework or the dogfood applications (checked 2026-09-29 by a repository search).\n *\n * That absence is the point. A cover check counts sentinel pixels in a screenshot: one where a region is\n * transparent over its slab is expected, one over a region's CONTENT means the canvas covered it — and a colour\n * a theme could also produce would make that count meaningless.\n */\nexport const FRAME_SENTINEL_COLOR = '#39ff14';\n\n/**\n * Frame-style overrides that draw every region as a flat, square, rimless, shadowless slab in\n * {@link FRAME_SENTINEL_COLOR}, for a cover-and-alignment check: `register3DLayout({ frameStyles:\n * createSentinelFrameStyles() })`. The contrast bound still applies, so run the check where the sentinel passes\n * it against the foreground (a light mode, whose foreground is dark) — and assert the sentinel is actually\n * visible where regions are transparent, or a bound-adjusted colour would read as \"nothing covered\".\n */\nexport function createSentinelFrameStyles(): Frame3DStyleOverrides {\n  const sentinel: Frame3DRegionStyleOverride = {\n    surface: Frame3DSurfaceKind.FROSTED,\n    tintColor: FRAME_SENTINEL_COLOR,\n    frost: 1,\n    gradient: 0,\n    radiusScale: 0,\n    rim: { opacity: 0, hoverOpacity: 0 },\n    shadow: NO_SHADOW,\n  };\n  const regions: Partial<Record<ShellRegion, Frame3DRegionStyleOverride>> = {};\n  for (const region of Object.values(ShellRegion)) regions[region] = sentinel;\n  return { all: { regions } };\n}\n"]}

package/dist/esm/frame/frame-appearance.d.ts

@@ -0,0 +1,99 @@
+import { DesignSystemToken, ShellRegion, type MaterialProfile } from '@wildo-ai/presets-components-models';
+import { type Frame3DThemeStyle } from './frame-3d-style';
+import { type FrameColor } from './frame-color';
+import { type DesignTokenResolution } from '../tokens/design-token-resolution';
+export type { FrameColor } from './frame-color';
+/** How one region kind's slab is drawn, in frame units (CSS pixels, sRGB-encoded colours). */
+export interface FrameSlabAppearance {
+    /** False when the style draws nothing here, or a colour it needs did not resolve. */
+    visible: boolean;
+    /** The shaded side of the frost. */
+    fillFrom: FrameColor;
+    /** The lit side of the frost. */
+    fillTo: FrameColor;
+    fillAlpha: number;
+    rim: FrameColor;
+    rimAlpha: number;
+    rimHoverAlpha: number;
+    rimWidthPx: number;
+    radiusPx: number;
+    shadowOffsetXPx: number;
+    shadowOffsetYPx: number;
+    shadowBlurPx: number;
+    shadowAlpha: number;
+}
+/** A cubic-Bézier easing, as its four control points. */
+export type FrameEasing = readonly [number, number, number, number];
+/** A damped spring, as motion.dev's gesture `transition` declares one. */
+export interface FrameSpring {
+    stiffness: number;
+    damping: number;
+    mass: number;
+}
+/**
+ * Everything the frame draws, as plain data. It is computed in the DOM tree from the theme and handed to the
+ * canvas as props, so the canvas holds meshes only and reads no context (#1823).
+ */
+export interface FrameAppearance {
+    /** The `--foreground` the bound was computed against. A change of it (a mode switch) is applied at once. */
+    foreground: FrameColor;
+    /** The in-scene background, shaded side then lit side. */
+    background: {
+        from: FrameColor;
+        to: FrameColor;
+    } | null;
+    /** The light direction in the FRAME's convention: degrees, 0 = from the right, 90 = from the top (y up). */
+    lightAngleDeg: number;
+    regions: Record<ShellRegion, FrameSlabAppearance>;
+    /** A theme change cross-fades over this. 0 under reduced motion. */
+    transitionSeconds: number;
+    transitionEasing: FrameEasing;
+    /** The rim's hover emphasis animates over this, when no spring is declared. */
+    hoverSeconds: number;
+    hoverEasing: FrameEasing;
+    /** The theme's surface gesture spring: when declared, the rim's hover emphasis follows it instead. */
+    hoverSpring: FrameSpring | null;
+    /** False under reduced motion: the frame is static, so the rim does not respond to hover at all. */
+    hoverResponse: boolean;
+    /**
+     * How long a shell CSS transition may run before the frame stops following it without a `transitionend`:
+     * the slowest motion-duration token, with half again as margin. The shell's own transitions use those tokens.
+     */
+    transitionCeilingSeconds: number;
+}
+export interface FrameAppearanceInputs {
+    resolutions: ReadonlyMap<DesignSystemToken, DesignTokenResolution>;
+    style: Frame3DThemeStyle;
+    /** The theme's navigation material (`MaterialProfileRole.GLASS_NAVIGATION`), when it has one. */
+    navigationMaterial: MaterialProfile | undefined;
+    /** The theme's surface gesture `transition` (motion.dev), when its surface recipe declares one. */
+    surfaceGestureTransition: Readonly<Record<string, string | number>> | undefined;
+    isDark: boolean;
+    prefersReducedMotion: boolean;
+    /** Converts the material's device-pixel rim width into CSS pixels. */
+    devicePixelRatio: number;
+}
+/**
+ * The lowest contrast any colour the frame can put behind text may have against `--foreground`: WCAG 2.x's
+ * AA minimum for normal text.
+ * spec-cite: WCAG 2.2 SC 1.4.3 Contrast (Minimum) — https://www.w3.org/TR/WCAG22/#contrast-minimum
+ */
+export declare const FRAME_MINIMUM_CONTRAST = 4.5;
+/**
+ * Derive the frame's appearance from the active theme, or `null` when the foreground did not resolve — without
+ * it no colour can be shown to be readable, and a frame that cannot be shown readable is not drawn.
+ *
+ * **The contrast bound** is part of the derivation, not a check after it. Every colour text can sit on is
+ * composited the way the framebuffer blends — in sRGB-encoded space, each written layer rounded to 8 bits — and
+ * must reach the target against `--foreground`:
+ * - the background, at several points along its gradient;
+ * - the background under a shadow (shadows combine by MAXIMUM in the renderer, never by stacking, so one
+ *   shadow at its full opacity is the darkest a point can be);
+ * - the frost over either, along its own gradient;
+ * - the rim at its HOVER opacity over the frost.
+ *
+ * A style value that would break it is WEAKENED — a colour moved toward the pole with the most contrast, a
+ * shadow or rim made fainter — and the bound is never relaxed. A style is a preference; the bound is a guarantee.
+ */
+export declare function deriveFrameAppearance(inputs: FrameAppearanceInputs): FrameAppearance | null;
+//# sourceMappingURL=frame-appearance.d.ts.map

package/dist/esm/frame/frame-appearance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-appearance.d.ts","sourceRoot":"","sources":["../../../../src/frame/frame-appearance.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAgB,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAEzH,OAAO,EAA+C,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACvG,OAAO,EAAgG,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAC9I,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAExG,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,8FAA8F;AAC9F,MAAM,WAAW,mBAAmB;IAClC,qFAAqF;IACrF,OAAO,EAAE,OAAO,CAAC;IACjB,oCAAoC;IACpC,QAAQ,EAAE,UAAU,CAAC;IACrB,iCAAiC;IACjC,MAAM,EAAE,UAAU,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,UAAU,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,yDAAyD;AACzD,MAAM,MAAM,WAAW,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAEpE,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,4GAA4G;IAC5G,UAAU,EAAE,UAAU,CAAC;IACvB,0DAA0D;IAC1D,UAAU,EAAE;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,EAAE,EAAE,UAAU,CAAA;KAAE,GAAG,IAAI,CAAC;IACxD,4GAA4G;IAC5G,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,WAAW,EAAE,mBAAmB,CAAC,CAAC;IAClD,oEAAoE;IACpE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,WAAW,CAAC;IAC9B,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,WAAW,CAAC;IACzB,sGAAsG;IACtG,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,oGAAoG;IACpG,aAAa,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,wBAAwB,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,WAAW,CAAC,iBAAiB,EAAE,qBAAqB,CAAC,CAAC;IACnE,KAAK,EAAE,iBAAiB,CAAC;IACzB,iGAAiG;IACjG,kBAAkB,EAAE,eAAe,GAAG,SAAS,CAAC;IAChD,mGAAmG;IACnG,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IAChF,MAAM,EAAE,OAAO,CAAC;IAChB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,sEAAsE;IACtE,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAmB1C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,GAAG,IAAI,CA6G3F"}