@wildo-ai/saas-frontend-lib 1.1.9 → 1.1.11

package/dist/esm/core/app-shell/shell-layout.d.ts

@@ -0,0 +1,138 @@
+import type React from 'react';
+import type { AppLayoutPreset_MainContainer_DefaultProps } from '../../components/app/AppLayout_MainContainer';
+import type { FrontendComponentRegistration } from '../runtime/domain-module.frontend.definitions';
+type MainContainerComponent = React.ComponentType<AppLayoutPreset_MainContainer_DefaultProps>;
+/** @wildo_source:part:start saas.frontend.app-shell.shell-layout-contract facet:layer:frontend facet:family:app-shell facet:audience:app-developer */
+/**
+ * How a shell layout disposes the regions of the signed-in shell.
+ *
+ * A layout never replaces a region, a provider or a context: an INHERIT layout renders the application's own main
+ * container unchanged, and a COMPOSED one renders a container built only from the shell building blocks
+ * (`AppShellProviders`, the region, content and overlays outlets, `AppShellLoadingState`,
+ * `AppShellOverlayPortalLayer`). So every navigation zone, portal and latch is the application's own either way.
+ */
+export declare enum ShellLayoutPlacementKind {
+    /** The main container the registration captured (the 2D default, or an application's own), rendered unchanged. */
+    INHERIT = "inherit",
+    /** A container of the layout's own, composed from the shell building blocks. */
+    COMPOSED = "composed"
+}
+/** A shell layout's disposal. */
+export type ShellLayoutPlacement = {
+    kind: ShellLayoutPlacementKind.INHERIT;
+} | {
+    kind: ShellLayoutPlacementKind.COMPOSED;
+    container: React.ComponentType<AppLayoutPreset_MainContainer_DefaultProps>;
+};
+/**
+ * A shell layout: an identity and a disposal. The family-neutral half every layout has — a 3D layout
+ * (`Layout3DDefinition` in `@wildo-ai/presets-components-3d`) extends it with its scene and transitions, and a 2D
+ * layout is this alone.
+ *
+ * An application uses ONE layout for its whole life, whatever its family: `registerShellLayout` refuses a second,
+ * different one, and so does `register3DLayout`, because both register the same main container.
+ */
+export interface ShellLayoutDefinition {
+    /** Stable identity. The one-layout rule compares ids, so an application's own layout needs an id of its own. */
+    id: string;
+    /** How the regions are disposed. */
+    placement: ShellLayoutPlacement;
+}
+/**
+ * The framework's layout families. A family is who DEFINES a layout — the plain registration, the animated 2D
+ * layouts, the 3D layouts — and it is part of a layout's identity: two layouts of different families are never the
+ * same layout, even under one id. An application authoring a family of its own names it with its own string.
+ */
+export declare enum ShellLayoutFamily {
+    /** A layout registered directly with `registerShellLayout`. */
+    SHELL = "shell",
+    /** The animated 2D layouts of `@wildo-ai/presets-components` (`register2DLayout`). */
+    LAYOUT_2D = "layout-2d",
+    /** The 3D layouts of `@wildo-ai/presets-components-3d` (`register3DLayout`). */
+    LAYOUT_3D = "layout-3d"
+}
+/** @wildo_source:part:end saas.frontend.app-shell.shell-layout-contract */
+/**
+ * The brand every layout main container carries. `Symbol.for`, not `Symbol`: the component registry lives on
+ * `globalThis` and survives a hot reload, while a reloaded module would mint a new `Symbol`, fail to recognise the
+ * container it registered last time, and capture it as "the 2D shell" — wrapping a layout inside itself.
+ */
+declare const SHELL_LAYOUT_MAIN_CONTAINER_BRAND: unique symbol;
+/** A layout main container: the component, the main container it captured, and the layout it draws. */
+export type ShellLayoutMainContainer<TLayout extends ShellLayoutDefinition = ShellLayoutDefinition> = MainContainerComponent & {
+    readonly [SHELL_LAYOUT_MAIN_CONTAINER_BRAND]: true;
+    /**
+     * The main container captured at registration: rendered unchanged by an INHERIT placement, and kept by every layout
+     * so a re-registration wraps IT rather than a layout container.
+     */
+    readonly captured: MainContainerComponent;
+    /** The layout this container draws. */
+    readonly layout: TLayout;
+    /** The family that defined the layout (a `ShellLayoutFamily` member, or an application family's own name). */
+    readonly layoutFamily: string;
+};
+/** Whether a registered main container is a layout one, of any family — and so carries the container it wraps. */
+export declare function isShellLayoutMainContainer(component: unknown): component is ShellLayoutMainContainer;
+/**
+ * The component a layout places: the captured container for INHERIT, the layout's own for COMPOSED. Resolved ONCE,
+ * at creation, and never inside a render: the placement keeps one component type for the application's life, so it
+ * never remounts — a remount would unmount every navigation zone and lose its state.
+ */
+export declare function resolveShellLayoutPlacement(captured: MainContainerComponent, layout: ShellLayoutDefinition): MainContainerComponent;
+/**
+ * Brand a rendered container as the layout container of `layout`, carrying the container it captured and any
+ * family-specific fields (`extra`). A layout family that renders more than the placement — the 3D frame under it,
+ * a settings context around it — builds its own component and brands it here, so the one-layout rule and the
+ * re-registration capture see it exactly as they see a 2D layout.
+ */
+export declare function brandShellLayoutMainContainer<TLayout extends ShellLayoutDefinition, TExtra extends object = Record<never, never>>(component: MainContainerComponent, captured: MainContainerComponent, layout: TLayout, family: string, extra?: TExtra): ShellLayoutMainContainer<TLayout> & TExtra;
+/**
+ * The layout main container of a layout that renders its placement and nothing else: the plain 2D case. It renders
+ * the placement directly — no wrapper element — so the placement's root stays the shell root, positioned, as the 2D
+ * shell's is (#1830).
+ */
+export declare function createShellLayoutMainContainer<TLayout extends ShellLayoutDefinition>(captured: MainContainerComponent, layout: TLayout, family?: string): ShellLayoutMainContainer<TLayout>;
+/** @wildo_source:part:start saas.frontend.app-shell.register-shell-layout facet:layer:frontend facet:family:app-shell facet:audience:app-developer */
+/** How `registerShellLayout` checks and builds a layout container. A layout family supplies these; a 2D layout needs none. */
+export interface ShellLayoutRegistrationOptions<TLayout extends ShellLayoutDefinition> {
+    /** The name refusals are reported under, so the developer reads the call they wrote (`register3DLayout()`). */
+    callerName?: string;
+    /**
+     * The family's built-in layouts, by id. An application's own layout may not borrow one of their ids: the one-layout
+     * rule compares ids, and a borrowed id would make two different layouts look like the same.
+     */
+    builtInLayouts?: Readonly<Record<string, ShellLayoutDefinition>>;
+    /**
+     * The family registering the layout (`ShellLayoutFamily.SHELL` by default). With the id, it is what makes a
+     * re-registration the SAME layout: a different family under the same id is refused, never taken for a hot reload.
+     */
+    family?: string;
+    /**
+     * Builds the container, branded with `family`. Defaults to `createShellLayoutMainContainer`, which renders the
+     * placement alone.
+     */
+    createContainer?: (captured: MainContainerComponent, layout: TLayout) => ShellLayoutMainContainer<TLayout>;
+}
+/**
+ * Give the signed-in shell a layout. Returned as a component registration, for the engine module's
+ * `componentRegistrations` — the entries `registerFrontendComponentRegistrations` runs AFTER the framework presets:
+ *
+ * ```ts
+ * export const engineComponentRegistrations: FrontendComponentRegistration[] = [registerShellLayout(MY_LAYOUT)];
+ * ```
+ *
+ * It registers under `Default` for `APP_LAYOUTS_MAIN_CONTAINER`, the only preset key the shell resolves, after
+ * capturing the container registered there before it.
+ *
+ * - **Refuses when nothing is registered yet**: capturing `null` would render no shell at all.
+ * - **One layout per application, across families**: a registration that finds a layout container of a DIFFERENT
+ *   layout already there — 2D or 3D — refuses; a silent replacement would hide which one the application is. The
+ *   same layout is the same id from the same FAMILY (`ShellLayoutFamily`), so an application's own layout named like
+ *   another family's built-in is refused too. The same layout again is idempotent: it wraps the container the FIRST
+ *   registration captured, never itself.
+ * - **Keeps the registration's metadata**: the captured container's `isConfigurable` is carried over.
+ */
+export declare function registerShellLayout<TLayout extends ShellLayoutDefinition>(layout: TLayout, options?: ShellLayoutRegistrationOptions<TLayout>): FrontendComponentRegistration;
+export {};
+/** @wildo_source:part:end saas.frontend.app-shell.register-shell-layout */
+//# sourceMappingURL=shell-layout.d.ts.map

package/dist/esm/core/app-shell/shell-layout.d.ts.map

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

package/dist/esm/core/app-shell/shell-layout.js

@@ -0,0 +1,143 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { CorePresetNames, FrontendComponentType } from '@wildo-ai/presets-components-models';
+import { ComponentRegistryService } from '../components-registry/component-registry.frontend.service.js';
+/** @wildo_source:part:start saas.frontend.app-shell.shell-layout-contract facet:layer:frontend facet:family:app-shell facet:audience:app-developer */
+/**
+ * How a shell layout disposes the regions of the signed-in shell.
+ *
+ * A layout never replaces a region, a provider or a context: an INHERIT layout renders the application's own main
+ * container unchanged, and a COMPOSED one renders a container built only from the shell building blocks
+ * (`AppShellProviders`, the region, content and overlays outlets, `AppShellLoadingState`,
+ * `AppShellOverlayPortalLayer`). So every navigation zone, portal and latch is the application's own either way.
+ */
+export var ShellLayoutPlacementKind;
+(function (ShellLayoutPlacementKind) {
+    /** The main container the registration captured (the 2D default, or an application's own), rendered unchanged. */
+    ShellLayoutPlacementKind["INHERIT"] = "inherit";
+    /** A container of the layout's own, composed from the shell building blocks. */
+    ShellLayoutPlacementKind["COMPOSED"] = "composed";
+})(ShellLayoutPlacementKind || (ShellLayoutPlacementKind = {}));
+/**
+ * The framework's layout families. A family is who DEFINES a layout — the plain registration, the animated 2D
+ * layouts, the 3D layouts — and it is part of a layout's identity: two layouts of different families are never the
+ * same layout, even under one id. An application authoring a family of its own names it with its own string.
+ */
+export var ShellLayoutFamily;
+(function (ShellLayoutFamily) {
+    /** A layout registered directly with `registerShellLayout`. */
+    ShellLayoutFamily["SHELL"] = "shell";
+    /** The animated 2D layouts of `@wildo-ai/presets-components` (`register2DLayout`). */
+    ShellLayoutFamily["LAYOUT_2D"] = "layout-2d";
+    /** The 3D layouts of `@wildo-ai/presets-components-3d` (`register3DLayout`). */
+    ShellLayoutFamily["LAYOUT_3D"] = "layout-3d";
+})(ShellLayoutFamily || (ShellLayoutFamily = {}));
+/** @wildo_source:part:end saas.frontend.app-shell.shell-layout-contract */
+/**
+ * The brand every layout main container carries. `Symbol.for`, not `Symbol`: the component registry lives on
+ * `globalThis` and survives a hot reload, while a reloaded module would mint a new `Symbol`, fail to recognise the
+ * container it registered last time, and capture it as "the 2D shell" — wrapping a layout inside itself.
+ */
+const SHELL_LAYOUT_MAIN_CONTAINER_BRAND = Symbol.for('@wildo-ai/saas-frontend-lib/shell-layout-main-container');
+/** Whether a registered main container is a layout one, of any family — and so carries the container it wraps. */
+export function isShellLayoutMainContainer(component) {
+    return typeof component === 'function' && component[SHELL_LAYOUT_MAIN_CONTAINER_BRAND] === true;
+}
+/**
+ * The component a layout places: the captured container for INHERIT, the layout's own for COMPOSED. Resolved ONCE,
+ * at creation, and never inside a render: the placement keeps one component type for the application's life, so it
+ * never remounts — a remount would unmount every navigation zone and lose its state.
+ */
+export function resolveShellLayoutPlacement(captured, layout) {
+    switch (layout.placement.kind) {
+        case ShellLayoutPlacementKind.INHERIT:
+            return captured;
+        case ShellLayoutPlacementKind.COMPOSED:
+            return layout.placement.container;
+        default: {
+            const unknownPlacement = layout.placement;
+            throw new Error(`The shell layout '${layout.id}' has a placement this framework does not implement: ${JSON.stringify(unknownPlacement)}.`);
+        }
+    }
+}
+/**
+ * Brand a rendered container as the layout container of `layout`, carrying the container it captured and any
+ * family-specific fields (`extra`). A layout family that renders more than the placement — the 3D frame under it,
+ * a settings context around it — builds its own component and brands it here, so the one-layout rule and the
+ * re-registration capture see it exactly as they see a 2D layout.
+ */
+export function brandShellLayoutMainContainer(component, captured, layout, family, extra) {
+    return Object.assign(component, { ...(extra ?? {}), [SHELL_LAYOUT_MAIN_CONTAINER_BRAND]: true, captured, layout, layoutFamily: family });
+}
+/**
+ * The layout main container of a layout that renders its placement and nothing else: the plain 2D case. It renders
+ * the placement directly — no wrapper element — so the placement's root stays the shell root, positioned, as the 2D
+ * shell's is (#1830).
+ */
+export function createShellLayoutMainContainer(captured, layout, family = ShellLayoutFamily.SHELL) {
+    const Placement = resolveShellLayoutPlacement(captured, layout);
+    function ShellLayoutMainContainerComponent(props) {
+        return _jsx(Placement, { ...props });
+    }
+    return brandShellLayoutMainContainer(ShellLayoutMainContainerComponent, captured, layout, family);
+}
+/**
+ * Give the signed-in shell a layout. Returned as a component registration, for the engine module's
+ * `componentRegistrations` — the entries `registerFrontendComponentRegistrations` runs AFTER the framework presets:
+ *
+ * ```ts
+ * export const engineComponentRegistrations: FrontendComponentRegistration[] = [registerShellLayout(MY_LAYOUT)];
+ * ```
+ *
+ * It registers under `Default` for `APP_LAYOUTS_MAIN_CONTAINER`, the only preset key the shell resolves, after
+ * capturing the container registered there before it.
+ *
+ * - **Refuses when nothing is registered yet**: capturing `null` would render no shell at all.
+ * - **One layout per application, across families**: a registration that finds a layout container of a DIFFERENT
+ *   layout already there — 2D or 3D — refuses; a silent replacement would hide which one the application is. The
+ *   same layout is the same id from the same FAMILY (`ShellLayoutFamily`), so an application's own layout named like
+ *   another family's built-in is refused too. The same layout again is idempotent: it wraps the container the FIRST
+ *   registration captured, never itself.
+ * - **Keeps the registration's metadata**: the captured container's `isConfigurable` is carried over.
+ */
+export function registerShellLayout(layout, options = {}) {
+    const callerName = options.callerName ?? 'registerShellLayout()';
+    let capturedIsConfigurable = false;
+    return {
+        componentRef: FrontendComponentType.APP_LAYOUTS_MAIN_CONTAINER,
+        preset: CorePresetNames.DEFAULT,
+        get isConfigurable() {
+            return capturedIsConfigurable;
+        },
+        loadComponent: async () => {
+            const current = ComponentRegistryService.resolve(FrontendComponentType.APP_LAYOUTS_MAIN_CONTAINER, CorePresetNames.DEFAULT);
+            if (!current) {
+                throw new Error(`${callerName}: no Default APP_LAYOUTS_MAIN_CONTAINER is registered to capture. Call it from the engine module's `
+                    + '`componentRegistrations`, which run after the framework presets — not from a module evaluated before them.');
+            }
+            const family = options.family ?? ShellLayoutFamily.SHELL;
+            // Own keys only: an id such as `constructor` names no built-in.
+            const builtIn = options.builtInLayouts && Object.hasOwn(options.builtInLayouts, layout.id) ? options.builtInLayouts[layout.id] : undefined;
+            if (builtIn !== undefined && builtIn !== layout) {
+                throw new Error(`${callerName}: the layout id '${layout.id}' belongs to a built-in layout; give the application's own layout an id of its own.`);
+            }
+            // The same layout again (a second call, or the registry surviving a hot reload) is the same id FROM the same
+            // family. Anything else is a second layout — including a same-named layout of another family, which each
+            // family's built-in guard alone would not catch (`registerShellLayout({ id: 'inherit' })` then
+            // `register3DLayout()`).
+            if (isShellLayoutMainContainer(current) && (current.layout.id !== layout.id || current.layoutFamily !== family)) {
+                const named = (id, of) => (current.layout.id === layout.id ? `'${id}' (${of})` : `'${id}'`);
+                throw new Error(`${callerName}: this application already registered the layout ${named(current.layout.id, current.layoutFamily)} and now asks for ${named(layout.id, family)}. `
+                    + 'An application uses one layout: remove the other registration — or, if you just changed the layout in code, '
+                    + 'reload the page (the component registry outlives a hot reload).');
+            }
+            capturedIsConfigurable = ComponentRegistryService.getMetadata(FrontendComponentType.APP_LAYOUTS_MAIN_CONTAINER, CorePresetNames.DEFAULT)?.isConfigurable ?? false;
+            const captured = isShellLayoutMainContainer(current) ? current.captured : current;
+            const container = options.createContainer ? options.createContainer(captured, layout) : createShellLayoutMainContainer(captured, layout, family);
+            if (container.layoutFamily !== family) {
+                throw new Error(`${callerName}: the container was branded for the family '${container.layoutFamily}' while registering for '${family}'.`);
+            }
+            return container;
+        },
+    };
+}
+//# sourceMappingURL=shell-layout.js.map

package/dist/esm/core/app-shell/shell-layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-layout.js","sourceRoot":"","sources":["../../../../../src/core/app-shell/shell-layout.tsx"],"names":[],"mappings":"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","sourcesContent":["import type React from 'react';\n\nimport { CorePresetNames, FrontendComponentType } from '@wildo-ai/presets-components-models';\n\nimport type { AppLayoutPreset_MainContainer_DefaultProps } from '../../components/app/AppLayout_MainContainer';\nimport { ComponentRegistryService } from '../components-registry/component-registry.frontend.service';\nimport type { FrontendComponentRegistration } from '../runtime/domain-module.frontend.definitions';\n\ntype MainContainerComponent = React.ComponentType<AppLayoutPreset_MainContainer_DefaultProps>;\n\n/** @wildo_source:part:start saas.frontend.app-shell.shell-layout-contract facet:layer:frontend facet:family:app-shell facet:audience:app-developer */\n/**\n * How a shell layout disposes the regions of the signed-in shell.\n *\n * A layout never replaces a region, a provider or a context: an INHERIT layout renders the application's own main\n * container unchanged, and a COMPOSED one renders a container built only from the shell building blocks\n * (`AppShellProviders`, the region, content and overlays outlets, `AppShellLoadingState`,\n * `AppShellOverlayPortalLayer`). So every navigation zone, portal and latch is the application's own either way.\n */\nexport enum ShellLayoutPlacementKind {\n  /** The main container the registration captured (the 2D default, or an application's own), rendered unchanged. */\n  INHERIT = 'inherit',\n  /** A container of the layout's own, composed from the shell building blocks. */\n  COMPOSED = 'composed',\n}\n\n/** A shell layout's disposal. */\nexport type ShellLayoutPlacement =\n  | { kind: ShellLayoutPlacementKind.INHERIT }\n  | { kind: ShellLayoutPlacementKind.COMPOSED; container: React.ComponentType<AppLayoutPreset_MainContainer_DefaultProps> };\n\n/**\n * A shell layout: an identity and a disposal. The family-neutral half every layout has — a 3D layout\n * (`Layout3DDefinition` in `@wildo-ai/presets-components-3d`) extends it with its scene and transitions, and a 2D\n * layout is this alone.\n *\n * An application uses ONE layout for its whole life, whatever its family: `registerShellLayout` refuses a second,\n * different one, and so does `register3DLayout`, because both register the same main container.\n */\nexport interface ShellLayoutDefinition {\n  /** Stable identity. The one-layout rule compares ids, so an application's own layout needs an id of its own. */\n  id: string;\n  /** How the regions are disposed. */\n  placement: ShellLayoutPlacement;\n}\n\n/**\n * The framework's layout families. A family is who DEFINES a layout — the plain registration, the animated 2D\n * layouts, the 3D layouts — and it is part of a layout's identity: two layouts of different families are never the\n * same layout, even under one id. An application authoring a family of its own names it with its own string.\n */\nexport enum ShellLayoutFamily {\n  /** A layout registered directly with `registerShellLayout`. */\n  SHELL = 'shell',\n  /** The animated 2D layouts of `@wildo-ai/presets-components` (`register2DLayout`). */\n  LAYOUT_2D = 'layout-2d',\n  /** The 3D layouts of `@wildo-ai/presets-components-3d` (`register3DLayout`). */\n  LAYOUT_3D = 'layout-3d',\n}\n/** @wildo_source:part:end saas.frontend.app-shell.shell-layout-contract */\n\n/**\n * The brand every layout main container carries. `Symbol.for`, not `Symbol`: the component registry lives on\n * `globalThis` and survives a hot reload, while a reloaded module would mint a new `Symbol`, fail to recognise the\n * container it registered last time, and capture it as \"the 2D shell\" — wrapping a layout inside itself.\n */\nconst SHELL_LAYOUT_MAIN_CONTAINER_BRAND = Symbol.for('@wildo-ai/saas-frontend-lib/shell-layout-main-container');\n\n/** A layout main container: the component, the main container it captured, and the layout it draws. */\nexport type ShellLayoutMainContainer<TLayout extends ShellLayoutDefinition = ShellLayoutDefinition> = MainContainerComponent & {\n  readonly [SHELL_LAYOUT_MAIN_CONTAINER_BRAND]: true;\n  /**\n   * The main container captured at registration: rendered unchanged by an INHERIT placement, and kept by every layout\n   * so a re-registration wraps IT rather than a layout container.\n   */\n  readonly captured: MainContainerComponent;\n  /** The layout this container draws. */\n  readonly layout: TLayout;\n  /** The family that defined the layout (a `ShellLayoutFamily` member, or an application family's own name). */\n  readonly layoutFamily: string;\n};\n\n/** Whether a registered main container is a layout one, of any family — and so carries the container it wraps. */\nexport function isShellLayoutMainContainer(component: unknown): component is ShellLayoutMainContainer {\n  return typeof component === 'function' && (component as Partial<ShellLayoutMainContainer>)[SHELL_LAYOUT_MAIN_CONTAINER_BRAND] === true;\n}\n\n/**\n * The component a layout places: the captured container for INHERIT, the layout's own for COMPOSED. Resolved ONCE,\n * at creation, and never inside a render: the placement keeps one component type for the application's life, so it\n * never remounts — a remount would unmount every navigation zone and lose its state.\n */\nexport function resolveShellLayoutPlacement(captured: MainContainerComponent, layout: ShellLayoutDefinition): MainContainerComponent {\n  switch (layout.placement.kind) {\n    case ShellLayoutPlacementKind.INHERIT:\n      return captured;\n    case ShellLayoutPlacementKind.COMPOSED:\n      return layout.placement.container;\n    default: {\n      const unknownPlacement: never = layout.placement;\n      throw new Error(`The shell layout '${layout.id}' has a placement this framework does not implement: ${JSON.stringify(unknownPlacement)}.`);\n    }\n  }\n}\n\n/**\n * Brand a rendered container as the layout container of `layout`, carrying the container it captured and any\n * family-specific fields (`extra`). A layout family that renders more than the placement — the 3D frame under it,\n * a settings context around it — builds its own component and brands it here, so the one-layout rule and the\n * re-registration capture see it exactly as they see a 2D layout.\n */\nexport function brandShellLayoutMainContainer<TLayout extends ShellLayoutDefinition, TExtra extends object = Record<never, never>>(\n  component: MainContainerComponent,\n  captured: MainContainerComponent,\n  layout: TLayout,\n  family: string,\n  extra?: TExtra,\n): ShellLayoutMainContainer<TLayout> & TExtra {\n  return Object.assign(component, { ...(extra ?? ({} as TExtra)), [SHELL_LAYOUT_MAIN_CONTAINER_BRAND]: true as const, captured, layout, layoutFamily: family });\n}\n\n/**\n * The layout main container of a layout that renders its placement and nothing else: the plain 2D case. It renders\n * the placement directly — no wrapper element — so the placement's root stays the shell root, positioned, as the 2D\n * shell's is (#1830).\n */\nexport function createShellLayoutMainContainer<TLayout extends ShellLayoutDefinition>(\n  captured: MainContainerComponent,\n  layout: TLayout,\n  family: string = ShellLayoutFamily.SHELL,\n): ShellLayoutMainContainer<TLayout> {\n  const Placement = resolveShellLayoutPlacement(captured, layout);\n  function ShellLayoutMainContainerComponent(props: AppLayoutPreset_MainContainer_DefaultProps): React.JSX.Element {\n    return <Placement {...props} />;\n  }\n  return brandShellLayoutMainContainer(ShellLayoutMainContainerComponent, captured, layout, family);\n}\n\n/** @wildo_source:part:start saas.frontend.app-shell.register-shell-layout facet:layer:frontend facet:family:app-shell facet:audience:app-developer */\n/** How `registerShellLayout` checks and builds a layout container. A layout family supplies these; a 2D layout needs none. */\nexport interface ShellLayoutRegistrationOptions<TLayout extends ShellLayoutDefinition> {\n  /** The name refusals are reported under, so the developer reads the call they wrote (`register3DLayout()`). */\n  callerName?: string;\n  /**\n   * The family's built-in layouts, by id. An application's own layout may not borrow one of their ids: the one-layout\n   * rule compares ids, and a borrowed id would make two different layouts look like the same.\n   */\n  builtInLayouts?: Readonly<Record<string, ShellLayoutDefinition>>;\n  /**\n   * The family registering the layout (`ShellLayoutFamily.SHELL` by default). With the id, it is what makes a\n   * re-registration the SAME layout: a different family under the same id is refused, never taken for a hot reload.\n   */\n  family?: string;\n  /**\n   * Builds the container, branded with `family`. Defaults to `createShellLayoutMainContainer`, which renders the\n   * placement alone.\n   */\n  createContainer?: (captured: MainContainerComponent, layout: TLayout) => ShellLayoutMainContainer<TLayout>;\n}\n\n/**\n * Give the signed-in shell a layout. Returned as a component registration, for the engine module's\n * `componentRegistrations` — the entries `registerFrontendComponentRegistrations` runs AFTER the framework presets:\n *\n * ```ts\n * export const engineComponentRegistrations: FrontendComponentRegistration[] = [registerShellLayout(MY_LAYOUT)];\n * ```\n *\n * It registers under `Default` for `APP_LAYOUTS_MAIN_CONTAINER`, the only preset key the shell resolves, after\n * capturing the container registered there before it.\n *\n * - **Refuses when nothing is registered yet**: capturing `null` would render no shell at all.\n * - **One layout per application, across families**: a registration that finds a layout container of a DIFFERENT\n *   layout already there — 2D or 3D — refuses; a silent replacement would hide which one the application is. The\n *   same layout is the same id from the same FAMILY (`ShellLayoutFamily`), so an application's own layout named like\n *   another family's built-in is refused too. The same layout again is idempotent: it wraps the container the FIRST\n *   registration captured, never itself.\n * - **Keeps the registration's metadata**: the captured container's `isConfigurable` is carried over.\n */\nexport function registerShellLayout<TLayout extends ShellLayoutDefinition>(layout: TLayout, options: ShellLayoutRegistrationOptions<TLayout> = {}): FrontendComponentRegistration {\n  const callerName = options.callerName ?? 'registerShellLayout()';\n  let capturedIsConfigurable = false;\n  return {\n    componentRef: FrontendComponentType.APP_LAYOUTS_MAIN_CONTAINER,\n    preset: CorePresetNames.DEFAULT,\n    get isConfigurable(): boolean {\n      return capturedIsConfigurable;\n    },\n    loadComponent: async () => {\n      const current = ComponentRegistryService.resolve(FrontendComponentType.APP_LAYOUTS_MAIN_CONTAINER, CorePresetNames.DEFAULT);\n      if (!current) {\n        throw new Error(\n          `${callerName}: no Default APP_LAYOUTS_MAIN_CONTAINER is registered to capture. Call it from the engine module's `\n          + '`componentRegistrations`, which run after the framework presets — not from a module evaluated before them.',\n        );\n      }\n      const family = options.family ?? ShellLayoutFamily.SHELL;\n      // Own keys only: an id such as `constructor` names no built-in.\n      const builtIn = options.builtInLayouts && Object.hasOwn(options.builtInLayouts, layout.id) ? options.builtInLayouts[layout.id] : undefined;\n      if (builtIn !== undefined && builtIn !== layout) {\n        throw new Error(`${callerName}: the layout id '${layout.id}' belongs to a built-in layout; give the application's own layout an id of its own.`);\n      }\n      // The same layout again (a second call, or the registry surviving a hot reload) is the same id FROM the same\n      // family. Anything else is a second layout — including a same-named layout of another family, which each\n      // family's built-in guard alone would not catch (`registerShellLayout({ id: 'inherit' })` then\n      // `register3DLayout()`).\n      if (isShellLayoutMainContainer(current) && (current.layout.id !== layout.id || current.layoutFamily !== family)) {\n        const named = (id: string, of: string): string => (current.layout.id === layout.id ? `'${id}' (${of})` : `'${id}'`);\n        throw new Error(\n          `${callerName}: this application already registered the layout ${named(current.layout.id, current.layoutFamily)} and now asks for ${named(layout.id, family)}. `\n          + 'An application uses one layout: remove the other registration — or, if you just changed the layout in code, '\n          + 'reload the page (the component registry outlives a hot reload).',\n        );\n      }\n      capturedIsConfigurable = ComponentRegistryService.getMetadata(FrontendComponentType.APP_LAYOUTS_MAIN_CONTAINER, CorePresetNames.DEFAULT)?.isConfigurable ?? false;\n      const captured = isShellLayoutMainContainer(current) ? current.captured : current;\n      const container = options.createContainer ? options.createContainer(captured, layout) : createShellLayoutMainContainer(captured, layout, family);\n      if (container.layoutFamily !== family) {\n        throw new Error(`${callerName}: the container was branded for the family '${container.layoutFamily}' while registering for '${family}'.`);\n      }\n      return container;\n    },\n  };\n}\n/** @wildo_source:part:end saas.frontend.app-shell.register-shell-layout */\n"]}

package/dist/esm/core/app-shell/shell-motion/shell-layout-stylesheet.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Installs a layout's stylesheet while at least one instance of the layout is mounted, and removes it when the last
+ * one unmounts; returns the release function. `key` names the layout (one sheet per key, however many mount).
+ *
+ * The sheet goes through `document.adoptedStyleSheets`, which a content security policy without `'unsafe-inline'`
+ * does not block, where a `<style>` element would be. Where constructable stylesheets are missing, it falls back to a
+ * `<style data-shell-layout-stylesheet="<key>">` element — which such a policy WOULD block, so that fallback is for
+ * old engines and test DOMs, not a supported production path.
+ *
+ * Scope every rule under the layout's own root attribute: the sheet is document-wide.
+ */
+export declare function installShellLayoutStylesheet(key: string, css: string, doc?: Document): () => void;
+//# sourceMappingURL=shell-layout-stylesheet.d.ts.map

package/dist/esm/core/app-shell/shell-motion/shell-layout-stylesheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-layout-stylesheet.d.ts","sourceRoot":"","sources":["../../../../../../src/core/app-shell/shell-motion/shell-layout-stylesheet.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,QAAmB,GAAG,MAAM,IAAI,CA8B3G"}

package/dist/esm/core/app-shell/shell-motion/shell-layout-stylesheet.js

@@ -0,0 +1,49 @@
+const installedByKey = new Map();
+/**
+ * Installs a layout's stylesheet while at least one instance of the layout is mounted, and removes it when the last
+ * one unmounts; returns the release function. `key` names the layout (one sheet per key, however many mount).
+ *
+ * The sheet goes through `document.adoptedStyleSheets`, which a content security policy without `'unsafe-inline'`
+ * does not block, where a `<style>` element would be. Where constructable stylesheets are missing, it falls back to a
+ * `<style data-shell-layout-stylesheet="<key>">` element — which such a policy WOULD block, so that fallback is for
+ * old engines and test DOMs, not a supported production path.
+ *
+ * Scope every rule under the layout's own root attribute: the sheet is document-wide.
+ */
+export function installShellLayoutStylesheet(key, css, doc = document) {
+    const entry = installedByKey.get(key) ?? { sheet: null, users: 0 };
+    installedByKey.set(key, entry);
+    entry.users += 1;
+    if (entry.users === 1) {
+        if ('adoptedStyleSheets' in doc && typeof CSSStyleSheet !== 'undefined' && 'replaceSync' in CSSStyleSheet.prototype) {
+            entry.sheet = new CSSStyleSheet();
+            entry.sheet.replaceSync(css);
+            doc.adoptedStyleSheets = [...doc.adoptedStyleSheets, entry.sheet];
+        }
+        else {
+            const style = doc.createElement('style');
+            style.dataset.shellLayoutStylesheet = key;
+            style.textContent = css;
+            doc.head.appendChild(style);
+        }
+    }
+    let released = false;
+    return () => {
+        // Idempotent per call: a double release (a StrictMode effect replay) must not release another user's hold.
+        if (released)
+            return;
+        released = true;
+        entry.users -= 1;
+        if (entry.users > 0)
+            return;
+        const { sheet } = entry;
+        if (sheet)
+            doc.adoptedStyleSheets = doc.adoptedStyleSheets.filter((installed) => installed !== sheet);
+        for (const style of doc.head.querySelectorAll('style[data-shell-layout-stylesheet]')) {
+            if (style.dataset.shellLayoutStylesheet === key)
+                style.remove();
+        }
+        installedByKey.delete(key);
+    };
+}
+//# sourceMappingURL=shell-layout-stylesheet.js.map

package/dist/esm/core/app-shell/shell-motion/shell-layout-stylesheet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-layout-stylesheet.js","sourceRoot":"","sources":["../../../../../../src/core/app-shell/shell-motion/shell-layout-stylesheet.ts"],"names":[],"mappings":"AAKA,MAAM,cAAc,GAAG,IAAI,GAAG,EAA+B,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,4BAA4B,CAAC,GAAW,EAAE,GAAW,EAAE,MAAgB,QAAQ;IAC7F,MAAM,KAAK,GAAG,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IACnE,cAAc,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC/B,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;IACjB,IAAI,KAAK,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;QACtB,IAAI,oBAAoB,IAAI,GAAG,IAAI,OAAO,aAAa,KAAK,WAAW,IAAI,aAAa,IAAI,aAAa,CAAC,SAAS,EAAE,CAAC;YACpH,KAAK,CAAC,KAAK,GAAG,IAAI,aAAa,EAAE,CAAC;YAClC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;YAC7B,GAAG,CAAC,kBAAkB,GAAG,CAAC,GAAG,GAAG,CAAC,kBAAkB,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QACpE,CAAC;aAAM,CAAC;YACN,MAAM,KAAK,GAAG,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;YACzC,KAAK,CAAC,OAAO,CAAC,qBAAqB,GAAG,GAAG,CAAC;YAC1C,KAAK,CAAC,WAAW,GAAG,GAAG,CAAC;YACxB,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,OAAO,GAAG,EAAE;QACV,2GAA2G;QAC3G,IAAI,QAAQ;YAAE,OAAO;QACrB,QAAQ,GAAG,IAAI,CAAC;QAChB,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;QACjB,IAAI,KAAK,CAAC,KAAK,GAAG,CAAC;YAAE,OAAO;QAC5B,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;QACxB,IAAI,KAAK;YAAE,GAAG,CAAC,kBAAkB,GAAG,GAAG,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,KAAK,KAAK,CAAC,CAAC;QACtG,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,IAAI,CAAC,gBAAgB,CAAmB,qCAAqC,CAAC,EAAE,CAAC;YACvG,IAAI,KAAK,CAAC,OAAO,CAAC,qBAAqB,KAAK,GAAG;gBAAE,KAAK,CAAC,MAAM,EAAE,CAAC;QAClE,CAAC;QACD,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC,CAAC;AACJ,CAAC","sourcesContent":["interface InstalledStylesheet {\n  sheet: CSSStyleSheet | null;\n  users: number;\n}\n\nconst installedByKey = new Map<string, InstalledStylesheet>();\n\n/**\n * Installs a layout's stylesheet while at least one instance of the layout is mounted, and removes it when the last\n * one unmounts; returns the release function. `key` names the layout (one sheet per key, however many mount).\n *\n * The sheet goes through `document.adoptedStyleSheets`, which a content security policy without `'unsafe-inline'`\n * does not block, where a `<style>` element would be. Where constructable stylesheets are missing, it falls back to a\n * `<style data-shell-layout-stylesheet=\"<key>\">` element — which such a policy WOULD block, so that fallback is for\n * old engines and test DOMs, not a supported production path.\n *\n * Scope every rule under the layout's own root attribute: the sheet is document-wide.\n */\nexport function installShellLayoutStylesheet(key: string, css: string, doc: Document = document): () => void {\n  const entry = installedByKey.get(key) ?? { sheet: null, users: 0 };\n  installedByKey.set(key, entry);\n  entry.users += 1;\n  if (entry.users === 1) {\n    if ('adoptedStyleSheets' in doc && typeof CSSStyleSheet !== 'undefined' && 'replaceSync' in CSSStyleSheet.prototype) {\n      entry.sheet = new CSSStyleSheet();\n      entry.sheet.replaceSync(css);\n      doc.adoptedStyleSheets = [...doc.adoptedStyleSheets, entry.sheet];\n    } else {\n      const style = doc.createElement('style');\n      style.dataset.shellLayoutStylesheet = key;\n      style.textContent = css;\n      doc.head.appendChild(style);\n    }\n  }\n  let released = false;\n  return () => {\n    // Idempotent per call: a double release (a StrictMode effect replay) must not release another user's hold.\n    if (released) return;\n    released = true;\n    entry.users -= 1;\n    if (entry.users > 0) return;\n    const { sheet } = entry;\n    if (sheet) doc.adoptedStyleSheets = doc.adoptedStyleSheets.filter((installed) => installed !== sheet);\n    for (const style of doc.head.querySelectorAll<HTMLStyleElement>('style[data-shell-layout-stylesheet]')) {\n      if (style.dataset.shellLayoutStylesheet === key) style.remove();\n    }\n    installedByKey.delete(key);\n  };\n}\n"]}

package/dist/esm/core/app-shell/shell-motion/shell-motion-origins.d.ts

@@ -0,0 +1,95 @@
+import { type RefObject } from 'react';
+import { type ShellMotionAxis, type ShellStageRect } from './shell-motion-vocabulary';
+/**
+ * The motion building blocks that start from WHERE something was pressed (#2055): a pane or a dialog growing out of the
+ * row or button that opened it, an emphasized pane growing to its new width, and a pane's rows cascading in. Like the
+ * rest of the motion core they write nothing on an engine element but WAAPI animations, which leave nothing behind, and
+ * proxies of their own.
+ */
+/** A box in viewport coordinates. */
+export interface ShellViewportBox {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * How recent a press must be to be what opened a pane or a dialog. Short on purpose: a modal that opens later than
+ * this was not opened by that press (a timer, a websocket push), and must not fly from it.
+ */
+export declare const SHELL_PRESS_ORIGIN_MAX_AGE_MS = 800;
+/** A pressed box, with — for a row — a still picture of it taken at the press, which a proxy carries as it grows. */
+export interface ShellPressedBox extends ShellViewportBox {
+    picture?: HTMLElement;
+    /**
+     * The pressed row itself, live — for a view-transition arrival, which names the row BEFORE the commit so the browser
+     * captures it. It may have moved or unmounted since the press; the box above is where it was.
+     */
+    element?: HTMLElement;
+}
+/**
+ * The row an element belongs to, recognised by SHAPE: the nearest ancestor inside the pane that is row-high, wide, and
+ * one of a repeated group of such siblings. The engine renders no row marker, and its lists are tables, card lists or an
+ * application's own rows, so a marker could never cover them all while a shape does. The repeated-group rule keeps a
+ * full-width toolbar or header, which is alone of its kind, from passing for a row. `null` outside a pane, or when
+ * nothing on the way qualifies (a multi-column card grid, whose cards are narrower than half the pane).
+ */
+export declare function shellRowBox(target: Element): HTMLElement | null;
+/** The last press, as boxes to grow from. Each `take…` CONSUMES it, so one press opens at most one thing. */
+export interface ShellPressOrigin {
+    /** The row pressed within `maxAgeMs`, if any, with its picture. */
+    takeRow(maxAgeMs: number): ShellPressedBox | null;
+    /** The row pressed within `maxAgeMs`, WITHOUT consuming the press — to decide before taking it. */
+    peekRow(maxAgeMs: number): ShellPressedBox | null;
+    /** The control (button, link, menu item) pressed within `maxAgeMs`, if any. */
+    takeControl(maxAgeMs: number): ShellViewportBox | null;
+}
+/**
+ * Remembers the last press — a pointer press, or Enter / Space on a focused element — as the box of the row and of the
+ * control it happened in, measured AT the press, before anything re-renders (the row may move or unmount the moment what
+ * it opens mounts). ANY other key press forgets it: whatever opens next was opened by that key (a shortcut such as the
+ * command palette's), not by the earlier press, and must not grow out of it.
+ *
+ * Installs nothing while `enabled` is false — a layout whose axis never grows from a press pays no listener and no layout
+ * read on every press.
+ */
+export declare function useShellPressOrigin(enabled: boolean): ShellPressOrigin;
+/**
+ * Flies a proxy box from one viewport box to another inside the stage, for `SHELL_PROXY_FLIGHT_SHARE` of the axis's
+ * motion, then removes it. A pressed row's picture (`from.picture`) rides in it, fading as it grows. The proxy is the core's own element (`data-shell-proxy`, aria-hidden, no pointer events),
+ * painted inline from the theme's tokens so it reads as the surface it becomes.
+ *
+ * `arriving` — the pane or dialog the proxy stands for — is revealed on the SAME clock: hidden for the flight, then faded
+ * in over the rest of the motion, by a script animation that sits above whatever the layout's stylesheet plays on it.
+ * Two clocks (a stylesheet hold started at mount, a flight started later) drift apart; one cannot.
+ */
+export declare function flyShellProxy(stage: HTMLElement, from: ShellPressedBox, to: ShellViewportBox, axis: ShellMotionAxis, arriving?: Element): Promise<void>;
+/**
+ * An emphasized pane grows from the box it had (`before`, in stage coordinates) to the box it now fills: it is
+ * REVEALED through a clip that starts on the old box, so its content is never scaled or distorted on the way.
+ */
+export declare function growShellPane(pane: HTMLElement, before: ShellStageRect, stage: HTMLElement, axis: ShellMotionAxis): void;
+/** A pane given back its place slides home from where it stood while it had the width. */
+export declare function slideShellPaneHome(pane: HTMLElement, before: ShellStageRect, stage: HTMLElement, axis: ShellMotionAxis): void;
+/**
+ * The rows of a pane: the largest group of ALIKE, row-shaped siblings in it (at least two — a list of two items is a
+ * list — and most of their parent's children, so neither a toolbar of wide buttons nor a pane's own header strips pass
+ * for a list).
+ */
+export declare function shellPaneRows(pane: HTMLElement): HTMLElement[];
+/**
+ * Cascades a pane's rows in, one after another. Rows present now cascade at once. For `CASCADE_WATCH_MS` afterwards
+ * the pane is re-scanned after mutations — at most once per frame, in an animation-frame callback, which runs before
+ * that frame is painted — and rows not yet animated join the cascade. So rows that arrive with the data (after a loading
+ * skeleton, in a different container) cascade too, and a row never shows and then vanishes to start its entrance.
+ * Watching the WHOLE pane, not the first list found, is deliberate: the first list is often the skeleton.
+ */
+export declare function cascadeShellRows(pane: HTMLElement, axis: ShellMotionAxis): () => void;
+/**
+ * A modal popup grows out of the control that opened it, for an axis whose `dialogArrival` says so: when a modal content
+ * slot appears open in the stage's overlay layer, a proxy flies from the pressed control to the dialog's box, and the
+ * dialog is revealed on the flight's clock. Only the overlay layer is watched. A drawer is left alone: its library
+ * positions it with transforms of its own.
+ */
+export declare function useShellDialogArrival(rootRef: RefObject<HTMLElement | null>, axis: ShellMotionAxis, origin: ShellPressOrigin): void;
+//# sourceMappingURL=shell-motion-origins.d.ts.map

package/dist/esm/core/app-shell/shell-motion/shell-motion-origins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-motion-origins.d.ts","sourceRoot":"","sources":["../../../../../../src/core/app-shell/shell-motion/shell-motion-origins.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEnE,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAEnC;;;;;GAKG;AAEH,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAcD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,MAAM,CAAC;AAIjD,qHAAqH;AACrH,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AA4CD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAQ/D;AAUD,6GAA6G;AAC7G,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAAC;IAClD,mGAAmG;IACnG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAAC;IAClD,+EAA+E;IAC/E,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;CACxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,CAwCtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,gBAAgB,EAAE,IAAI,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCvJ;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,GAAG,IAAI,CAYxH;AAED,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,GAAG,IAAI,CAM7H;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,EAAE,CAkB9D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,IAAI,CAiCrF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAqBnI"}