@mhmo91/schmancy 0.10.24 → 0.10.25

package/dist/skills/directives.md

@@ -5,11 +5,47 @@
 Lit directives that snap onto any element to add behavior. No components to wrap, no CSS to write — just `${directiveName()}` in your template.
 
 ```typescript
+import { fill, overflowWithin } from '@mhmo91/schmancy/directives'
 import { magnetic, cursorGlow, gravity, reveal } from '@mhmo91/schmancy/directives'
 ```
 
 ---
 
+## Layout (2 directives — use these for every app shell)
+
+> These replace the deleted `<schmancy-page>` primitive. See `layout.md` for the full paradigm.
+
+### `fill()` — Viewport-anchor a container
+
+Measures the element's position against `visualViewport` and applies an exact `height` (and `width`) in pixels — cascade-independent. Tracks `visualViewport` resize/scroll, orientation change, iOS soft-keyboard (via `focusout`), and `theme.bottomOffset$` for safe-area padding.
+
+```html
+<!-- Root area — anchored to the full viewport -->
+<schmancy-area ${fill()} name="root" .default=${...}>...</schmancy-area>
+
+<!-- Custom element shell — fill() bypasses display:inline collapse -->
+<my-shell class="grid grid-cols-[auto_1fr]" ${fill()}>...</my-shell>
+```
+
+**Sets:** `height: Npx`, `width: Npx`, `overflow: hidden`, `min-height/width: 0`, `box-sizing: border-box`, `padding-bottom` (safe area).
+**Does NOT set:** `display`, `grid-template-*` — put Tailwind layout classes on the same element.
+
+### `overflowWithin()` — Contained scroll region
+
+Turns a grid cell or flex child into a scroll container with `overscroll-behavior: contain`.
+
+```html
+<div ${overflowWithin()} class="grid grid-rows-[auto_1fr] min-h-0">
+  <header>...</header>
+  <schmancy-area name="app">...</schmancy-area>
+</div>
+```
+
+**Sets:** `overflow-y/x: auto`, `overscroll-behavior: contain`, `scroll-behavior: smooth`, `min-height/width: 0`, `box-sizing: border-box`.
+Dispatches debounced `schmancy:scroll` event; listens for `@schmancy:scrollTo` command.
+
+---
+
 ## Physics & Interaction (6 directives)
 
 ### `magnetic` — Elements lean toward the cursor

package/dist/skills/icons.md

@@ -1,44 +1,108 @@
 # schmancy-icon
 
-> Material Symbols icon with configurable fill, weight, grade, variant, and size tokens.
+Renders a Material Symbol as an inline SVG. Path data is supplied at build
+time by the `schmancy-icons` Vite plugin — no font file, no network request,
+works offline from first byte.
 
 ## Usage
+
+```html
+<schmancy-icon>home</schmancy-icon>
+<schmancy-icon>delete</schmancy-icon>
+```
+
+Slot text IS the icon name (Material Symbols ligature name). No properties needed.
+
+## Sizing
+
+Size is set with Tailwind `text-*` on the host. Default is `24px` (`text-2xl`).
+`width` and `height` track `font-size` via `1em`.
+
 ```html
-<schmancy-icon>settings</schmancy-icon>
+<schmancy-icon class="text-base">close</schmancy-icon>   <!-- 16px -->
+<schmancy-icon class="text-xl">search</schmancy-icon>    <!-- 20px -->
+<schmancy-icon class="text-2xl">home</schmancy-icon>     <!-- 24px (default) -->
+<schmancy-icon class="text-4xl">check_circle</schmancy-icon> <!-- 36px -->
 ```
 
-## Properties
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| icon | string | `undefined` | Icon name (alternative to slot content, translation-safe) |
-| size | `'xxs'\|'xs'\|'sm'\|'md'\|'lg'\|string` | `'md'` | Icon size (12/16/20/24/32px or custom) |
-| fill | number (0-1) | `0` | Fill level (0=outlined, 1=filled) |
-| weight | number (100-700) | `400` | Stroke thickness |
-| grade | number (-50 to 200) | `0` | Visual weight adjustment |
-| variant | `'outlined'\|'rounded'\|'sharp'` | `'outlined'` | Icon style variant |
-
-## Size Tokens
-| Token | Size | Optical Size | Best For |
-|-------|------|-------------|----------|
-| xxs | 12px | 20 | Ultra-compact UIs |
-| xs | 16px | 20 | 32px buttons |
-| sm | 20px | 20 | 40px buttons |
-| md | 24px | 24 | Default (48px buttons) |
-| lg | 32px | 40 | 56px buttons |
-
-## Examples
+## Color
+
+Inherits `currentColor`. Override with Tailwind color utilities:
+
+```html
+<schmancy-icon class="text-primary-default">star</schmancy-icon>
+<schmancy-icon class="opacity-50">info</schmancy-icon>
+```
+
+## Fill variant (active states)
+
+Append `-fill` to the icon name for the filled variant. No CSS animation —
+a clean swap between outlined and filled symbols:
+
 ```html
-<!-- Filled icon -->
-<schmancy-icon .fill=${1}>favorite</schmancy-icon>
+<!-- Static filled -->
+<schmancy-icon>favorite-fill</schmancy-icon>
 
-<!-- Large rounded icon -->
-<schmancy-icon size="lg" variant="rounded">home</schmancy-icon>
+<!-- Dynamic active state -->
+<schmancy-icon>${active ? 'home-fill' : 'home'}</schmancy-icon>
+```
+
+The plugin auto-includes `-fill` variants for every detected base icon.
+
+## Vite plugin setup (web workspace)
+
+The plugin scans all `.ts` source files at build start and injects
+`window.__siIcons = { name: 'svgPathData', ... }` inline in `<head>`.
+
+```typescript
+// web/vite.config.ts
+import { schmancyIcons } from './plugins/schmancy-icons.ts'
+
+export default defineConfig({
+  plugins: [
+    schmancyIcons({
+      // Icon names used in runtime variables (not statically detectable).
+      // Type them as SchmancyIconName in consuming code.
+      additional: ['widgets', 'inventory_2', 'description'],
+    }),
+  ],
+})
+```
 
-<!-- Custom size -->
-<schmancy-icon size="48px" .weight=${300}>search</schmancy-icon>
+### Adding icons for dynamic usage
 
-<!-- Translation-safe (use icon property instead of slot) -->
-<schmancy-icon icon="delete"></schmancy-icon>
+Any icon name carried in a variable at runtime must be declared in `additional`.
+TypeScript enforcement: the plugin generates `src/types/icon-name.d.ts` with
+a `SchmancyIconName` union of every icon in the bundle. Type dynamic icon props
+as `SchmancyIconName` to get compile-time coverage.
+
+```typescript
+import type { SchmancyIconName } from './types/icon-name'
+
+@property({ type: String }) icon: SchmancyIconName = 'home'
 ```
 
-Auto-loads Google Fonts on first use. Translation-protected via `translate="no"` and `notranslate` class.
+## What was removed
+
+The following properties are **gone** — the component has no public API beyond
+slot text content:
+
+| Removed | Replacement |
+|---------|-------------|
+| `size="lg"` | `class="text-4xl"` (Tailwind) |
+| `fill`, `weight`, `grade`, `variant` | n/a — use `-fill` suffix for filled, rest unsupported |
+| `icon="name"` prop | slot text: `<schmancy-icon>name</schmancy-icon>` |
+| Google Fonts auto-load | n/a — self-contained inline SVG |
+
+## How it works
+
+1. Vite plugin walks `web/src/**/*.ts`, extracts icon names from
+   `<schmancy-icon>name</schmancy-icon>` and `icon="name"` patterns.
+2. Reads `@material-symbols/svg-400/outlined/{name}.svg`, extracts the `d`
+   attribute from each `<path>`.
+3. Injects `<script>window.__siIcons={...}</script>` before `</head>`.
+4. `schmancy-icon.connectedCallback` reads `this.textContent`, looks up
+   `window.__siIcons[name]`, and renders `<svg><path d="..."/></svg>` inside
+   its shadow DOM.
+
+No `<use>` references — those can't cross shadow DOM boundaries.

package/dist/skills/layout.md

@@ -1,63 +1,46 @@
-# Schmancy Layout
+# Layout Directives
 
-> Layout primitives: `schmancy-grid`, `schmancy-flex`, `schmancy-scroll`, plus `sch-grid` / `sch-flex` v2 variants.
+```typescript
+import { fill, overflowWithin } from '@mhmo91/schmancy/directives'
+```
 
-> **Prefer Tailwind classes directly** for layout in new code. These components exist for quick composition and design-token consistency (`gap="sm|md|lg"` maps to theme spacing).
+## `fill()` — viewport-anchor an element
 
-## schmancy-grid
-```html
-<schmancy-grid cols="1fr 2fr 1fr" gap="md" align="center">
-  <div>Left</div><div>Center</div><div>Right</div>
-</schmancy-grid>
-```
+Measures against `visualViewport` and writes exact `height`/`width` in px. Cascade-independent — works even when parent custom elements default to `display: inline`. Tracks iOS keyboard, orientation change, and `theme.bottomOffset$`.
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `flow` | `'row' \| 'col' \| 'dense' \| 'row-dense' \| 'col-dense'` | `'row'` | Grid auto-flow |
-| `align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | `'stretch'` | Item alignment |
-| `justify` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` | Item justification |
-| `content` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'around' \| 'evenly' \| 'between'` | — | Align-content |
-| `gap` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg'` | `'none'` | Grid gap |
-| `cols` | string | — | grid-template-columns (e.g. `"1fr 2fr"`) |
-| `rows` | string | — | grid-template-rows |
-| `rcols` | object | — | Responsive cols: `{ sm: '1fr', md: '1fr 1fr', lg: '1fr 2fr 1fr' }` |
-| `wrap` | boolean | `false` | Grid auto-wrap |
-
-## schmancy-flex
-```html
-<schmancy-flex flow="row" justify="between" align="center" gap="md">
-  <div>Logo</div><div>Nav</div>
-</schmancy-flex>
-```
+Sets: `height: Npx`, `width: Npx`, `overflow: hidden`, `min-h/w: 0`, `box-sizing: border-box`, `padding-bottom` (safe area).  
+Does **not** set `display` or `grid-template-*` — use Tailwind classes on the same element.
 
-| Property | Type | Default |
-|----------|------|---------|
-| `flow` | `'row' \| 'row-reverse' \| 'col' \| 'col-reverse'` | `'col'` |
-| `wrap` | `'wrap' \| 'nowrap' \| 'wrap-reverse'` | `'wrap'` |
-| `align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | `'start'` |
-| `justify` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'between'` | `'start'` |
-| `gap` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'none'` |
-
-## schmancy-scroll
-```html
-<schmancy-scroll hide direction="vertical" name="main">
-  <!-- long content -->
-</schmancy-scroll>
-```
+## `overflowWithin()` — contained scroll region
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `hide` | boolean | `false` | Hide scrollbar in supported browsers |
-| `direction` | `'vertical' \| 'horizontal' \| 'both'` | `'both'` | Scroll axes |
-| `name` | string | — | Identifier for global scroll events |
-| `debounce` | number | — | Debounce time in ms for scroll events |
+Sets: `overflow: auto`, `overscroll-behavior: contain`, `scroll-behavior: smooth`, `min-h/w: 0`, `box-sizing: border-box`.
 
-Smooth scroll-behavior, overscroll containment, and support for flex-shrink sizing.
+## Canonical shell
 
-## sch-grid / sch-flex (v2)
+```typescript
+// app-shell.view.ts
+html`<schmancy-area ${fill()} name="root" .default=${...}>...</schmancy-area>`
+
+// app-home.view.ts
+html`
+  <my-shell class="grid grid-cols-[auto_1fr]" ${fill()}>
+    <app-rail></app-rail>
+    <div ${overflowWithin()} class="grid grid-rows-[auto_1fr] min-h-0">
+      <tree-picker></tree-picker>
+      <schmancy-area name="app" .default=${...}>...</schmancy-area>
+    </div>
+  </my-shell>
+`
+```
+
+```css
+/* styles.css */
+html, body { margin: 0; padding: 0; overflow: hidden; }
+```
 
-Reflected-attribute variants optimized for styling via CSS selectors. Same prop model as the classic components with a `sch-` prefix. Use when you need to target the layout from parent CSS without Tailwind.
+## Rules
 
-## Notes
-- All layout components extend the base `Layout` class which exposes pass-through CSS properties (padding, margin, width, position, border, etc.).
-- Prefer Tailwind (`class="flex items-center gap-2"`) for new code — these components remain for consistent theme-driven gaps and rapid prototyping.
+- One `fill()` per shell level. Inner levels get `min-h-0` grid cells.
+- `overflowWithin()` goes on the element that should scroll, not on `:host`.
+- Do not write `h-full`, `w-full`, or `:host { height: 100% }` anywhere. `schmancy-area`'s `::slotted` rule sizes mounted views.
+- `<schmancy-page>` is removed — `fill()` replaces it.

package/dist/skills/mixins.md

@@ -8,11 +8,10 @@ factory — composing `LitElement` + Tailwind injection + `BaseElement`
 ## Usage
 
 ```typescript
-import { SchmancyElement } from '@mhmo91/schmancy/mixins'
-import { customElement } from 'lit/decorators.js'
+import { SchmancyElement, schmancyElement } from '@mhmo91/schmancy/mixins'
 import { css, html } from 'lit'
 
-@customElement('my-component')
+@schmancyElement('my-component')
 class MyComponent extends SchmancyElement {
   static styles = [css`
     :host { display: block }
@@ -33,12 +32,34 @@ declare global {
 No styles? Just drop `static styles`:
 
 ```typescript
-@customElement('my-component')
+@schmancyElement('my-component')
 class MyComponent extends SchmancyElement {
   render() { return html`<slot></slot>` }
 }
 ```
 
+### Why `@schmancyElement` instead of Lit's `@customElement`
+
+`@schmancyElement` wraps the class's prototype methods with the active-host
+tracker BEFORE calling `customElements.define`. Lit's `@customElement` only
+calls `define` — the wrap then runs inside the `SchmancyElement` constructor,
+which is too late: per the HTML spec, the browser captures lifecycle callback
+references off the prototype at `define` time and invokes those cached
+references for every connect / disconnect.
+
+If you use plain `@customElement` and read state inside `connectedCallback`,
+the active-host stack is empty, the read falls through to `document.activeElement`,
+misses the enclosing `<schmancy-context>`, and silently resolves to the
+module-scoped global instead of the isolated copy. The constructor-time wrap
+still catches `render`, class methods, and inherited lifecycle methods on
+ancestor prototypes (the browser's cached reference for those is the
+ancestor's, which gets wrapped by an earlier sibling). But your subclass's
+own `connectedCallback` / `disconnectedCallback` overrides fall through.
+The symptom is silent: writes go to the wrong slot, reads return the wrong
+value, and the form looks broken for no obvious reason.
+
+`@schmancyElement` makes this impossible. Use it as the default.
+
 Tailwind is injected automatically — your `static styles` only declares
 component-local CSS.
 
@@ -99,7 +120,7 @@ Every SchmancyElement responds to `{its-tag}-where-are-you` events with
 ## Component skeleton
 
 ```typescript
-@customElement('my-component')
+@schmancyElement('my-component')
 export class MyComponent extends SchmancyElement {
   static styles = [css`:host { display: block }`]
 

package/dist/skills/schmancy/INDEX.md

@@ -11,6 +11,7 @@ The framework pieces — touch before components.
 - [Mixins](./mixins.md) — `SchmancyElement` base class.
 - [Theme](./theme.md) — `<schmancy-theme>`, color scheme, CSS variables.
 - [Directives](./directives.md) — Lit directives for physics, effects, text, visibility, interaction.
+- [Layout](./layout.md) — `fill()` + `overflowWithin()` directives for app-shell sizing (replaces `<schmancy-page>`).
 - [Animation](./animation.md) — Spring presets (`SPRING_SMOOTH`, etc.), `createAnimation`.
 
 ## Components by job
@@ -21,7 +22,7 @@ The framework pieces — touch before components.
 > Lab: [Map](../../lab/skills/map.md) · [Charts](../../lab/skills/charts.md) — install `@mhmo91/schmancy-lab`
 
 ### Surfaces & layout
-[Surface](./surface.md) · [Card](./card.md) · [Scroll / Grid / Flex](./layout.md) · [Page](./page.md) · [Content Drawer](./content-drawer.md) · [Window](./window.md) · [Boat](./boat.md) · [Float](./float.md) · [Splash Screen](./splash-screen.md)
+[Surface](./surface.md) · [Card](./card.md) · [Scroll / Grid / Flex](./layout.md) · [Content Drawer](./content-drawer.md) · [Window](./window.md) · [Boat](./boat.md) · [Float](./float.md) · [Splash Screen](./splash-screen.md)
 
 ### Forms
 [Form](./form.md) · [Input](./input.md) · [Textarea](./textarea.md) · [Select](./select.md) · [Autocomplete](./autocomplete.md) · [Option](./option.md) · [Checkbox](./checkbox.md) · [Switch](./switch.md) · [Radio Group](./radio-group.md) · [Chips](./chips.md) · [Date Range](./date-range.md) · [Date Range Inline](./date-range-inline.md) · [Range](./range.md)

package/dist/skills/schmancy/SKILL.md

@@ -25,6 +25,7 @@ All reference files live in this directory. Read by filename.
 | Base class (`SchmancyElement`) | `mixins.md` |
 | Theme (`<schmancy-theme>`, `theme` service) | `theme.md` |
 | Directives (`magnetic`, `cursorGlow`, `gravity`, `reveal`, `animateText`, …) | `directives.md` |
+| Layout (`fill()`, `overflowWithin()` — viewport-anchored shell sizing) | `layout.md` |
 | Spring physics presets | `animation.md` |
 
 ## Overlay services (prefer over tags)
@@ -78,6 +79,11 @@ State signals are the integration layer between co-located Schmancy view compone
 - Detection signals: a view component with `.property=${value}` inputs from a parent; a view component dispatching `CustomEvent`s that a sibling or parent handles; an orchestrator file co-located with a view where routing complexity does not exceed schmancy's `.guard`+`@redirect` capability (i.e., the flow is a linear sequence with no branching or cross-route hand-off).
 - Remediation: move shared state into schmancy state signals; have each component read/write signals directly in render() and connectedCallback(); delete the orchestrator if its only job was to pass data down and receive events up.
 
+**TYPOGRAPHY_NO_REDUNDANT_COLOR** (`TYPOGRAPHY_NO_REDUNDANT_COLOR`). `schmancy-typography` color classes override the component's default rendering color.
+
+- Detection signals: `class` attributes on `<schmancy-typography>` containing `text-on-surface`, `text-surface-on`, `text-surface-on-variant`, or any other color utility that matches the component's default — these restate what the component already renders and add no information.
+- Remediation: remove the redundant color class from the `class` attribute. Keep a color class only when it intentionally overrides the default (e.g. `text-primary-default`, `text-error`, a custom accent). The test: if removing the class produces no visual change, it is redundant.
+
 **EVENTS_UP_PROPS_DOWN** (cross-component communication when signals don't cover it)
 When two components genuinely cannot share a signal (e.g., a generic reusable component that must not import app state), user actions travel upward via `CustomEvent` dispatch and data travels downward via Lit property bindings — not via callable property bindings (`onXxx`, `handleXxx`) set on child elements.
 
@@ -125,31 +131,35 @@ Plus a live region: `<div id="live-status" role="status" aria-live="polite" clas
 ## Minimal app skeleton
 
 ```typescript
-<schmancy-theme root scheme="dark">
-  <schmancy-surface type="solid" fill="all">
-    <schmancy-scroll>
-      <schmancy-area
-        name="root"
-        .default=${lazy(() => import('./home.page'))}
-      >
-        <schmancy-route when="home-page"
-          .component=${lazy(() => import('./home.page'))}></schmancy-route>
-
-        <schmancy-route when="app-index"
-          .component=${lazy(() => import('./app.page'))}
-          .guard=${authState$.pipe(
-            map(u => !!u),
-            takeUntil(this.disconnecting),
-          )}
-          @redirect=${() => area.push({
-            component: 'home-page', area: 'root', historyStrategy: 'replace',
-          })}></schmancy-route>
-      </schmancy-area>
-    </schmancy-scroll>
-  </schmancy-surface>
-</schmancy-theme>
+// styles.css: html, body { margin: 0; padding: 0; overflow: hidden; }
+import { fill } from '@mhmo91/schmancy/directives'
+
+html`
+  <schmancy-theme root scheme="dark">
+    <schmancy-area
+      ${fill()}
+      name="root"
+      .default=${lazy(() => import('./home.page'))}
+    >
+      <schmancy-route when="home-page"
+        .component=${lazy(() => import('./home.page'))}></schmancy-route>
+
+      <schmancy-route when="app-index"
+        .component=${lazy(() => import('./app.page'))}
+        .guard=${authState$.pipe(
+          map(u => !!u),
+          takeUntil(this.disconnecting),
+        )}
+        @redirect=${() => area.push({
+          component: 'home-page', area: 'root', historyStrategy: 'replace',
+        })}></schmancy-route>
+    </schmancy-area>
+  </schmancy-theme>
+`
 ```
 
+See `layout.md` for the full shell pattern with rail + content area.
+
 ## Workflow
 
 1. User describes a UI task.

package/dist/skills/schmancy/area.md

@@ -14,9 +14,10 @@ Areas can be nested to compose shell-plus-sub-view layouts.
 
 `<schmancy-area>` is the routing leaf in the layout cascade. Its shadow CSS guarantees:
 
-1. **Stretch the mounted component.** The routed view fills the area (`min-height: 100%; width: 100%`). The area itself is `height: 100%; width: 100%` so it consumes whatever cell its parent gave it (typically a `<schmancy-page>` slot or a grid `1fr` row / column).
-2. **Scroll by default.** The host is `overflow: auto` — when the mounted component grows past the area's box, the area scrolls. Pages that need a custom scroll strategy (virtualized lists, multi-pane scroll) declare `<schmancy-area no-scroll>` and own their scroll.
-3. **Reset scroll on route change.** The area sets `scrollTop = 0` after every route swap so a new view starts at the top.
+1. **Stretch the mounted component.** `::slotted(:not(schmancy-route))` gives every mounted view `min-height: 100%; width: 100%; min-width: 0` so it fills the area cell.
+2. **Area sizing.** The host is `height: 100%; width: 100%; min-height: 0; min-width: 0` — it fills whatever grid cell or `fill()` box its parent gave it.
+3. **No built-in scroll.** Scroll is opt-in via `${overflowWithin()}` at the use site. Put `overflowWithin()` on the element that should scroll (the area itself, or a wrapper around it), not on the routed component.
+4. **Reset scroll on route change.** The area sets `scrollTop = 0` after every route swap so a new view starts at the top.
 
 Consumers do not write `h-full`, `w-full`, or `:host { height: 100% }` on routed components. The area's `::slotted` rule sizes them.
 
@@ -57,7 +58,7 @@ Consumers do not write `h-full`, `w-full`, or `:host { height: 100% }` on routed
 | `guard` | `Observable<boolean>` | When emits `false`, blocks and dispatches `redirect` event |
 | `exact` | boolean | Strict-equality matching |
 
-`<schmancy-area>` also accepts the `no-scroll` boolean attribute to opt out of default `overflow: auto` (for virtualized lists or custom scroll containers).
+Scroll is opt-in: apply `${overflowWithin()}` to the element (or a wrapper) that should scroll. The area has no `no-scroll` attribute — that concept is gone.
 
 ## `area` service
 

package/dist/skills/schmancy/connectivity.md

@@ -26,9 +26,7 @@ Place it once at the root — typically just inside your main `schmancy-theme` o
 ```html
 <schmancy-theme>
   <schmancy-connectivity-status></schmancy-connectivity-status>
-  <schmancy-page>
-    <!-- rest of app -->
-  </schmancy-page>
+  <schmancy-area ${fill()} name="root" .default=${...}>...</schmancy-area>
 </schmancy-theme>
 ```
 

package/dist/skills/schmancy/directives.md

@@ -5,11 +5,47 @@
 Lit directives that snap onto any element to add behavior. No components to wrap, no CSS to write — just `${directiveName()}` in your template.
 
 ```typescript
+import { fill, overflowWithin } from '@mhmo91/schmancy/directives'
 import { magnetic, cursorGlow, gravity, reveal } from '@mhmo91/schmancy/directives'
 ```
 
 ---
 
+## Layout (2 directives — use these for every app shell)
+
+> These replace the deleted `<schmancy-page>` primitive. See `layout.md` for the full paradigm.
+
+### `fill()` — Viewport-anchor a container
+
+Measures the element's position against `visualViewport` and applies an exact `height` (and `width`) in pixels — cascade-independent. Tracks `visualViewport` resize/scroll, orientation change, iOS soft-keyboard (via `focusout`), and `theme.bottomOffset$` for safe-area padding.
+
+```html
+<!-- Root area — anchored to the full viewport -->
+<schmancy-area ${fill()} name="root" .default=${...}>...</schmancy-area>
+
+<!-- Custom element shell — fill() bypasses display:inline collapse -->
+<my-shell class="grid grid-cols-[auto_1fr]" ${fill()}>...</my-shell>
+```
+
+**Sets:** `height: Npx`, `width: Npx`, `overflow: hidden`, `min-height/width: 0`, `box-sizing: border-box`, `padding-bottom` (safe area).
+**Does NOT set:** `display`, `grid-template-*` — put Tailwind layout classes on the same element.
+
+### `overflowWithin()` — Contained scroll region
+
+Turns a grid cell or flex child into a scroll container with `overscroll-behavior: contain`.
+
+```html
+<div ${overflowWithin()} class="grid grid-rows-[auto_1fr] min-h-0">
+  <header>...</header>
+  <schmancy-area name="app">...</schmancy-area>
+</div>
+```
+
+**Sets:** `overflow-y/x: auto`, `overscroll-behavior: contain`, `scroll-behavior: smooth`, `min-height/width: 0`, `box-sizing: border-box`.
+Dispatches debounced `schmancy:scroll` event; listens for `@schmancy:scrollTo` command.
+
+---
+
 ## Physics & Interaction (6 directives)
 
 ### `magnetic` — Elements lean toward the cursor