@tobiasoberpaul/mdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TOberpaul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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
+AUTHORS OR COPYRIGHT HOLDERS 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.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# MDK · UI Motion Library
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small, framework-independent TypeScript motion library using native Web
+Animations API (WAAPI), CSS tokens and reversible transitions. React is used only
+by the DB React and shadcn/ui playground integrations.
+
+## Run locally
+
+```sh
+npm install
+npm run dev
+```
+
+Open [the playground](http://127.0.0.1:4173/examples/).
+
+## Publish the website
+
+```sh
+npm ci
+npm run build:site
+```
+
+Upload the contents of `site/` to a static host, or configure its build command
+as `npm run build:site` and publish directory as `site`. The site includes
+Examples, Code playground and Documentation. Subdirectory hosting works without
+route rewrites. Preview the generated site locally at
+[the static build](http://127.0.0.1:4173/site/) while the dev server is running.
+
+GitHub Pages is deployed by `.github/workflows/pages.yml` on every push to
+`main`. Set **Settings → Pages → Source → GitHub Actions** in the repository.
+Website: https://toberpaul.github.io/animations/
+
+- **Examples:** switch between DB React and shadcn/ui, light/dark mode, reduced
+  motion, duration, progression gap and overshoot; scrub real animation frames.
+- **Code playground:** edit HTML with live preview. Define
+  motion in code through attributes/classes or direct factories. Drafts are
+  stored locally. Exported HTML references the running library server.
+
+```sh
+npm run build           # TypeScript library and CSS → dist/
+npm run build:examples  # Both component integrations and playground shell
+```
+
+The current package is private and has not been published to npm. Consume this
+checkout through a workspace/local package or import the built files. No runtime
+framework dependencies are required by the library.
+
+## Documentation
+
+See **[Library guide](docs/LIBRARY.md)** for the public API, declarative markup,
+tokens, content sequencing, viewport entry and component integration examples.
+
+| Playground animation | Example artifacts |
+| --- | --- |
+| Grow | Action menu, dialog, side panel, notification, three-column panels, split-button menu |
+| Extract | Action menu with a retained source button |
+| Morph | Replacing action menu, rename input |
+| Slide | Two-level submenu |
+| Content | Text block, image/caption and independently revealed page blocks |
+
+All component examples use the same core library. Components own positioning,
+content, accessibility, focus and lifecycle. The library owns visual transitions.
+Grow/Morph/Extract contents use fade and blur without an independent content
+slide. Content uses a fixed slide + blur + fade combination.
+
+## Defaults
+
+- Duration: **300ms**; Content uses this duration per item.
+- Easing: symmetric ease-in-out.
+- Overshoot: **15% of the shorter side, capped at .75rem**.
+- Playground progression: enabled, **24ms** start spacing.
+- Library progression: enabled by default; set `--motion-content-progressive: 0` to disable.
+- Reduced motion: respects the OS preference and the playground switch.
+
+The DB integration uses installed DB component/theme packages. Optional licensed
+DB Neo/icon assets require locally configured `ASSET_PASSWORD` and
+`ASSET_INIT_VECTOR`; they are not included in this repository. The examples use
+fallback icons where applicable. Keep credentials in ignored local environment
+files.
+
+Generated builds, dependencies and local visual-check output are ignored by Git.
+
+## AI coding clients
+
+A local read-only MCP server shares the guide, built API declarations, tokens and integration examples with compatible AI clients. See [AI integration setup](docs/AI_INTEGRATION.md). Start with `npm run build`, then configure `node /absolute/path/to/animations/ai/mcp-server.mjs` as a stdio MCP server. Portable integration rules are in `ai/INSTRUCTIONS.md`.
+
+## Local Codex analytics
+
+Run `npm run analytics` and open the printed address. It reads token counts and available five-hour account snapshots from local Codex history for recorded work-package turns. The optional project hook adds local request telemetry and can be trusted under **Settings → Hooks** or with `/hooks`. The [Context Starter](context-starter/README.md) describes the data format.
+
+## License and package releases
+
+Original library and MCP code is licensed under [MIT](LICENSE). Third-party example dependencies retain their own licenses; see [third-party notices](THIRD_PARTY_NOTICES.md).
+
+See [publishing](docs/PUBLISHING.md) for npm package validation and release steps. The registry package is not published yet.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,7 @@
+# Third-party notices
+
+The distributed library and local MCP server have no runtime dependencies. They use browser APIs and Node.js built-ins.
+
+The repository's website examples use third-party design systems, React, Radix primitives, Lucide icons and development tools. Those dependencies retain their own licenses; their example source and bundled website assets are not included in the npm package. See each dependency's installed LICENSE/NOTICE files and examples/shadcn/SHADCN-LICENSE when distributing the website.
+
+The package's LICENSE covers this project's original code, not third-party trademarks, fonts or proprietary design-system assets.

package/ai/INSTRUCTIONS.md

@@ -0,0 +1,14 @@
+# Motion Library integration rules
+
+Use the installed Motion Library instead of copying animation implementations into applications.
+
+1. Read `motion://guide` and `get_motion_reference` with topic `api` before choosing options. The built declarations and CSS tokens are authoritative.
+2. Choose Grow for anchored surfaces, Extract to retain the trigger, Morph to replace it, Slide for translation, and Fade for slide/blur/fade content reveals.
+3. Keep layout, positioning, semantics, visibility, focus, keyboard handling and lifecycle owned by the consuming component. Optional positioning is explicit; do not replace an existing positioning system.
+4. Include all visible elements in reveal groups: headings, controls, labels, icons, dividers and rows. Keep related elements together. Grow/Extract/Morph content does not slide.
+5. Use CSS custom properties for timing, easing and overshoot. Preserve progressive reveal and reduced-motion handling. Do not hardcode another animation recipe.
+6. Keep targets mounted through exit. Synchronize hidden/inert and aria-expanded. For modals, preserve the component's focus trap and focus restoration; generic examples are disclosures, not complete dialogs or menus.
+7. Destroy controllers and disconnect bindings/observers on unmount. Preserve interruption and reversal. Use seek or bindScrollMotion for scroll scrubbing rather than recreating controllers on each frame.
+8. Verify opening, closing, rapid reversal, keyboard operation, reduced motion and mobile geometry in the consuming application.
+
+The MCP tools provide reference text and source examples only. They do not execute generated code, edit the application, or call an AI model. Any implementation changes remain actions performed by the user's AI client under its normal permissions.

package/ai/mcp-server.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// Local, read-only MCP adapter. stdout is reserved for protocol messages.
+import {createInterface} from 'node:readline';
+import {readFile,readdir} from 'node:fs/promises';
+import {motionBehaviors} from '../dist/behaviors.js';
+const base=new URL('../',import.meta.url);
+const read=path=>readFile(new URL(path,base),'utf8');
+const versions=['2026-07-28','2025-11-25','2025-06-18','2025-03-26'];
+const capabilities={tools:{},resources:{},prompts:{}};
+const packageInfo=JSON.parse(await read('package.json'));
+const info={name:'motion-library',version:packageInfo.version};
+const instructions='Read motion_guide before integrating. Use the installed library API, not copied animation recipes. Component integrations own visibility, accessibility and focus. Tools read bundled reference files only; generated examples are not executed.';
+const resources=[
+ {uri:'motion://guide',name:'motion_guide',mimeType:'text/markdown',path:'docs/LIBRARY.md'},
+ {uri:'motion://tokens',name:'motion_tokens',mimeType:'text/css',path:'dist/styles/motion.css'},
+ {uri:'motion://instructions',name:'motion_integration_rules',mimeType:'text/markdown',path:'ai/INSTRUCTIONS.md'},
+];
+const tools=[
+ {name:'get_motion_reference',description:'Read the current library guide, design tokens, API declarations or canonical behavior definitions.',inputSchema:{type:'object',properties:{topic:{type:'string',enum:['guide','tokens','api','behaviors','instructions']}},required:['topic'],additionalProperties:false}},
+ {name:'create_motion_example',description:'Generate a minimal integration using the real Motion Library API. Returns source text; never executes or writes it.',inputSchema:{type:'object',properties:{behavior:{type:'string',enum:Object.keys(motionBehaviors)},activation:{type:'string',enum:['click','hover','focus','observer','scroll','manual']},placement:{type:'string',enum:['center','top','bottom','left','right','bottom-end','top-end']},relativeTo:{type:'string',enum:['trigger','viewport']},space:{type:'number',minimum:0,maximum:128}},required:['behavior'],additionalProperties:false}},
+].map(tool=>({...tool,annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:false}}));
+function invalid(message){throw Object.assign(new Error(message),{code:-32602});}
+async function reference(topic){
+ if(topic==='behaviors')return JSON.stringify(motionBehaviors,null,2);
+ if(topic==='api'){
+  const files=[];
+  async function walk(path){for(const entry of await readdir(new URL(path,base),{withFileTypes:true})){const file=path+'/'+entry.name;if(entry.isDirectory())await walk(file);else if(entry.name.endsWith('.d.ts'))files.push(file);}}
+  await walk('dist');files.sort();return (await Promise.all(files.map(async file=>'// '+file+'\n'+await read(file)))).join('\n\n');
+ }
+ const resource=resources.find(value=>value.uri==='motion://'+topic);
+ if(!resource)invalid('Unknown reference topic.');return read(resource.path);
+}
+function example(args){
+ const behavior=args.behavior,activation=args.activation??'click';
+ if(!Object.hasOwn(motionBehaviors,behavior))invalid('Unknown behavior.');
+ if(!tools[1].inputSchema.properties.activation.enum.includes(activation))invalid('Invalid activation.');
+ const placement=args.placement;
+ if(placement&&!tools[1].inputSchema.properties.placement.enum.includes(placement))invalid('Invalid placement.');
+ const relativeTo=args.relativeTo??'trigger';
+ if(!['trigger','viewport'].includes(relativeTo))invalid('Invalid relativeTo.');
+ const space=args.space??12;if(typeof space!=='number'||!Number.isFinite(space)||space<0||space>128)invalid('space must be between 0 and 128 pixels.');
+ const position=placement?`\n  position: { relativeTo: '${relativeTo}', placement: '${placement}', space: ${space} },`:'';
+ const scroll=activation==='scroll'?`\n  scroll: { mode: 'scrub', start: 200, end: 600 },`:'';
+ const observer=activation==='observer'?`\n  observeElement: document.querySelector('#motion-slot'),`:'';
+ return `<!-- Reserve this slot so entry/exit cannot shift the surrounding page. -->
+<div id="motion-slot">
+  <button id="trigger" aria-controls="target" aria-expanded="false">Open</button>
+  <section id="target" data-motion="${behavior}" data-motion-anchor="center" hidden inert>
+    <h2>Your next idea</h2>
+    <p>Content keeps its layout and follows the library reveal recipe.</p>
+    <button id="close">Close</button>
+  </section>
+</div>
+
+// Load the library's motion.css in your application.
+import {createInteractiveMotion} from '@tobiasoberpaul/mdk';
+const target = document.querySelector('#target');
+const trigger = document.querySelector('#trigger');
+const motion = createInteractiveMotion({
+  content: target, trigger, on: '${activation}',${position}${scroll}${observer}
+  close: target.querySelector('#close'),
+  reveal: [...target.children],
+  onStateChange(state) {
+    if (state === 'destroyed') return;
+    target.hidden = state === 'closed';
+    target.inert = state === 'closed' || state === 'closing';
+    trigger.setAttribute('aria-expanded', String(state === 'open' || state === 'opening'));
+${behavior==='morph'?"    trigger.style.visibility = state === 'closed' ? '' : 'hidden';\n    trigger.inert = state !== 'closed';\n":''}  },
+});
+// Existing component positioning is used unless position is explicitly supplied.
+// This is a generic disclosure, not a complete modal dialog or ARIA menu integration.
+// Add component-owned focus restoration and semantics where appropriate.
+// On unmount: motion.destroy();`;
+}
+async function dispatch(method,params={}){
+ if(method==='initialize')return {protocolVersion:versions.slice(1).includes(params.protocolVersion)?params.protocolVersion:'2025-06-18',capabilities,serverInfo:info,instructions};
+ if(method==='server/discover')return {supportedVersions:[versions[0]],capabilities,instructions,cacheScope:'public',ttlMs:0,resultType:'complete'};
+ if(method==='ping')return {};
+ if(method==='resources/list')return {resources:resources.map(({path,...resource})=>resource)};
+ if(method==='resources/templates/list')return {resourceTemplates:[]};
+ if(method==='resources/read'){
+  const resource=resources.find(value=>value.uri===params.uri);if(!resource)invalid('Unknown resource URI.');
+  return {contents:[{uri:resource.uri,mimeType:resource.mimeType,text:await read(resource.path)}]};
+ }
+ if(method==='tools/list')return {tools};
+ if(method==='tools/call'){
+  const args=params.arguments??{};if(!args||typeof args!=='object'||Array.isArray(args))invalid('Arguments must be an object.');
+  const tool=tools.find(value=>value.name===params.name);if(!tool)invalid('Unknown tool.');
+  if(Object.keys(args).some(key=>!Object.hasOwn(tool.inputSchema.properties,key)))invalid('Unknown argument.');
+  try{return {content:[{type:'text',text:params.name==='get_motion_reference'?await reference(args.topic):example(args)}]};}
+  catch(error){return {isError:true,content:[{type:'text',text:error.message}]};}
+ }
+ if(method==='prompts/list')return {prompts:[{name:'integrate_motion',description:'Plan an integration using the library reference and existing component lifecycle.'}]};
+ if(method==='prompts/get'){
+  if(params.name!=='integrate_motion')invalid('Unknown prompt.');
+  return {messages:[{role:'user',content:{type:'text',text:(await read('ai/INSTRUCTIONS.md'))+'\nRead the guide and API through get_motion_reference. Inspect the existing component and implement its motion with the library. Include cleanup and reduced-motion behavior.'}}]};
+ }
+ throw Object.assign(new Error('Method not found'),{code:-32601});
+}
+const send=value=>process.stdout.write(JSON.stringify(value)+'\n');
+const lines=createInterface({input:process.stdin,crlfDelay:Infinity});
+let queue=Promise.resolve();
+lines.on('line',line=>{queue=queue.then(async()=>{
+ let request;try{request=JSON.parse(line);}catch{send({jsonrpc:'2.0',id:null,error:{code:-32700,message:'Parse error'}});return;}
+ if(!request||Array.isArray(request)||request.jsonrpc!=='2.0'||typeof request.method!=='string'){
+  send({jsonrpc:'2.0',id:request?.id??null,error:{code:-32600,message:'Invalid request'}});return;
+ }
+ if(request.params!==undefined&&(!request.params||typeof request.params!=='object'||Array.isArray(request.params))){send({jsonrpc:'2.0',id:request.id??null,error:{code:-32602,message:'Params must be an object'}});return;}
+ if(!Object.hasOwn(request,'id'))return; // Notifications never receive responses.
+ try{const modern=request.params?._meta?.['io.modelcontextprotocol/protocolVersion'];if(modern&&modern!==versions[0])invalid('Unsupported modern protocol version.');const result=await dispatch(request.method,request.params);send({jsonrpc:'2.0',id:request.id,result:modern?{...result,resultType:'complete'}:result});}
+ catch(error){send({jsonrpc:'2.0',id:request.id,error:{code:error.code??-32603,message:error.code?error.message:'Unable to read the bundled library reference. Run npm run build first.'}});}
+ }).catch(error=>process.stderr.write(error.message+'\n'));});

package/dist/behaviors.d.ts

@@ -0,0 +1,25 @@
+export declare const motionBehaviors: {
+    readonly grow: {
+        readonly replacesTrigger: false;
+        readonly contentEffect: "fade-blur";
+    };
+    readonly extract: {
+        readonly replacesTrigger: false;
+        readonly contentEffect: "fade-blur";
+    };
+    readonly morph: {
+        readonly replacesTrigger: true;
+        readonly contentEffect: "fade-blur";
+    };
+    readonly slide: {
+        readonly replacesTrigger: false;
+        readonly contentEffect: "fade-blur";
+    };
+    readonly fade: {
+        readonly replacesTrigger: false;
+        readonly contentEffect: "slide-blur-fade";
+    };
+};
+export type MotionKind = keyof typeof motionBehaviors;
+/** Canonical naming shared by declarative integration and consuming components. */
+export declare function getMotionKind(content: HTMLElement): MotionKind;

package/dist/behaviors.js

@@ -0,0 +1,20 @@
+export const motionBehaviors = {
+    grow: { replacesTrigger: false, contentEffect: 'fade-blur' },
+    extract: { replacesTrigger: false, contentEffect: 'fade-blur' },
+    morph: { replacesTrigger: true, contentEffect: 'fade-blur' },
+    slide: { replacesTrigger: false, contentEffect: 'fade-blur' },
+    fade: { replacesTrigger: false, contentEffect: 'slide-blur-fade' },
+};
+/** Canonical naming shared by declarative integration and consuming components. */
+export function getMotionKind(content) {
+    const names = [...Object.keys(motionBehaviors), 'liquid', 'content'];
+    const classes = names.filter(name => content.classList.contains(`motion-${name}`));
+    const raw = content.dataset.motion ?? (classes.length === 1 ? classes[0] : undefined);
+    if (raw === 'content')
+        return 'fade';
+    if (raw === 'liquid')
+        return content.hasAttribute('data-motion-replace-trigger') ? 'morph' : 'extract';
+    if (!raw || !Object.prototype.hasOwnProperty.call(motionBehaviors, raw))
+        throw new Error('Set data-motion to grow, extract, morph, slide or fade, or use one matching motion-* class.');
+    return raw;
+}

package/dist/core/animation.d.ts

@@ -0,0 +1,16 @@
+import type { Options, Transition } from './lifecycle.js';
+export interface Track {
+    element: Element;
+    frames: Keyframe[];
+    easing?: string;
+    pseudoElement?: string;
+    composite?: CompositeOperation;
+}
+export declare function createTransition(options: Options, pattern: string, tracks: () => Track[], behavior?: {
+    keepVisibleWhenClosed?: boolean;
+    durationScale?: () => number;
+    revealTiming?: (count: number, index: number) => {
+        start: number;
+        end: number;
+    };
+}): Transition;

package/dist/core/animation.js

@@ -0,0 +1,150 @@
+import { motionBehaviors } from '../behaviors.js';
+import { contentTimeline } from './content-timing.js';
+import { contentTracks } from './content-frames.js';
+import { revealGroups, hasSurfaceSequence, sequenceTiming } from './content-groups.js';
+import { duration, numberToken, token } from './tokens.js';
+export function createTransition(options, pattern, tracks, behavior = {}) {
+    const { content } = options;
+    const reduced = matchMedia('(prefers-reduced-motion: reduce)');
+    let target = options.initiallyOpen ?? false;
+    let state = target ? 'open' : 'closed';
+    let animations = [];
+    let generation = 0;
+    const opacity = content.style.getPropertyValue('opacity');
+    const priority = content.style.getPropertyPriority('opacity');
+    function restore() {
+        if (opacity)
+            content.style.setProperty('opacity', opacity, priority);
+        else
+            content.style.removeProperty('opacity');
+    }
+    function endpoint() { restore(); if (!target && !behavior.keepVisibleWhenClosed)
+        content.style.opacity = '0'; }
+    function notify(next) { state = next; options.onStateChange?.(next); }
+    function cancel() { generation++; animations.forEach(a => a.cancel()); animations = []; }
+    function settle() {
+        cancel();
+        endpoint();
+        notify(target ? 'open' : 'closed');
+    }
+    endpoint();
+    function set(next) {
+        if (state === 'destroyed' || next === target)
+            return;
+        target = next;
+        // Let adapters settle native effects before the visual-state snapshot.
+        if (!animations.length)
+            restore();
+        // Notify before measurement so the component can unhide and position itself.
+        notify(target ? 'opening' : 'closing');
+        if (state === 'destroyed')
+            return;
+        if (reduced.matches || typeof content.animate !== 'function') {
+            settle();
+            return;
+        }
+        if (!animations.length) {
+            try {
+                let time = duration(content, pattern);
+                if (!time) {
+                    settle();
+                    return;
+                }
+                const requestedEasing = token(content, `easing-${pattern}`);
+                const easing = CSS.supports('animation-timing-function', requestedEasing) ? requestedEasing : token(content, 'easing-standard');
+                const recipe = motionBehaviors[(pattern === 'scale' ? 'grow' : pattern === 'liquid' ? 'extract' : pattern === 'content' ? 'fade' : pattern)];
+                const descriptions = tracks();
+                time *= behavior.durationScale?.() ?? 1;
+                const reveal = options.reveal ? (Array.isArray(options.reveal) ? options.reveal : [options.reveal]) : [];
+                const progressive = numberToken(content, 'content-progressive') > 0;
+                const surfaceSequence = progressive && hasSurfaceSequence(content);
+                const { targets: revealTargets, orders } = revealGroups(content, reveal, options.revealPseudoElements ?? [], progressive);
+                if (revealTargets.length) {
+                    const start = numberToken(content, progressive ? 'component-content-offset' : `${pattern}-reveal-offset`);
+                    const end = numberToken(content, progressive ? 'component-content-end' : `${pattern}-reveal-end`);
+                    const blur = token(content, `${pattern}-reveal-blur`);
+                    const plan = contentTimeline(content, orders.length, { start, end, stepToken: 'component-content-stagger', capToken: 'component-content-stagger-span' });
+                    for (const { element, pseudoElement, order } of revealTargets) {
+                        const index = orders.indexOf(order);
+                        const sequence = surfaceSequence ? (behavior.revealTiming ?? ((count, index) => sequenceTiming(content, count, index)))(orders.length + 1, index + 1) : undefined;
+                        const range = sequence ?? plan.at(index);
+                        if (!pseudoElement && (element === content || !content.contains(element)))
+                            throw new Error('Reveal targets must be inner elements, separate from the surface.');
+                        descriptions.push(...contentTracks({ element, pseudoElement, ...range, blur, easing: token(content, 'easing-reveal'),
+                            distance: recipe?.contentEffect === 'slide-blur-fade' ? token(content, 'reveal-distance') : undefined }));
+                    }
+                }
+                for (const track of descriptions) {
+                    const timing = { duration: time, easing: track.easing ?? easing, fill: 'both', composite: track.composite ?? 'replace' };
+                    const a = track.pseudoElement
+                        ? new Animation(new KeyframeEffect(track.element, track.frames, { ...timing, pseudoElement: track.pseudoElement }), document.timeline)
+                        : track.element.animate(track.frames, timing);
+                    a.pause();
+                    a.currentTime = target ? 0 : time;
+                    animations.push(a);
+                }
+            }
+            catch (error) {
+                settle();
+                throw error;
+            }
+        }
+        // Reversing at an exact endpoint must settle, rather than letting play()
+        // auto-rewind the effect to the opposite end of the timeline.
+        if (animations.every(a => target ? Number(a.currentTime) >= Number(a.effect.getTiming().duration) : Number(a.currentTime) <= 0)) {
+            settle();
+            return;
+        }
+        const version = ++generation;
+        animations.forEach(a => { a.playbackRate = target ? 1 : -1; a.play(); });
+        Promise.all(animations.map(a => a.finished)).then(() => {
+            if (version === generation && state !== 'destroyed')
+                settle();
+        }).catch(() => { });
+    }
+    function seek(progress) {
+        if (!Number.isFinite(progress))
+            throw new Error('Motion progress must be finite.');
+        if (state === 'destroyed')
+            return;
+        const p = Math.max(0, Math.min(1, progress));
+        if (reduced.matches) {
+            const next = p >= .5;
+            if (next !== target)
+                set(next);
+            else if (animations.length)
+                settle();
+            return;
+        }
+        if (!animations.length) {
+            if ((p === 0 && state === 'closed') || (p === 1 && state === 'open'))
+                return;
+            set(state !== 'open');
+        }
+        if (!animations.length)
+            return;
+        generation++;
+        target = p > 0;
+        animations.forEach(a => { a.pause(); a.currentTime = p * Number(a.effect.getTiming().duration); });
+        if (p === 0 || p === 1)
+            settle();
+        else if (state !== 'opening')
+            notify('opening');
+    }
+    function preferenceChanged() { if (reduced.matches && animations.length)
+        settle(); }
+    reduced.addEventListener('change', preferenceChanged);
+    return {
+        get state() { return state; }, get isOpen() { return target; },
+        seek,
+        open: () => set(true), close: () => set(false), toggle: () => set(!target),
+        destroy() {
+            if (state === 'destroyed')
+                return;
+            cancel();
+            restore();
+            reduced.removeEventListener('change', preferenceChanged);
+            notify('destroyed');
+        }
+    };
+}

package/dist/core/content-frames.d.ts

@@ -0,0 +1,13 @@
+import type { Track } from './animation.js';
+export interface ContentTrackOptions {
+    element: HTMLElement;
+    pseudoElement?: string;
+    start: number;
+    end: number;
+    blur: string;
+    easing: string;
+    distance?: string;
+    blurEnd?: number;
+}
+/** The single fade/blur recipe; Content adds an additive vertical translation. */
+export declare function contentTracks(options: ContentTrackOptions): Track[];

package/dist/core/content-frames.js

@@ -0,0 +1,27 @@
+/** The single fade/blur recipe; Content adds an additive vertical translation. */
+export function contentTracks(options) {
+    const { element, pseudoElement, start, end, blur, easing, distance, blurEnd } = options;
+    if (!CSS.supports('filter', `blur(${blur})`))
+        throw new Error('Content blur must be a CSS length.');
+    const style = getComputedStyle(element, pseudoElement), filter = style.filter, opacity = style.opacity;
+    const blurred = `${filter === 'none' ? '' : `${filter} `}blur(${blur})`;
+    const display = style.display === 'inline' ? { display: 'inline-block' } : {};
+    const from = { ...display, opacity: 0, ...(blurEnd === undefined ? { filter: blurred } : {}) };
+    const to = { ...display, opacity, ...(blurEnd === undefined ? { filter } : {}) };
+    const tracks = [{ element, pseudoElement, easing: 'linear', frames: [
+                { ...from, offset: 0 }, { ...from, offset: start, easing }, { ...to, offset: end }, { ...to, offset: 1 }
+            ] }];
+    if (distance) {
+        if (!CSS.supports('translate', `0 ${distance}`))
+            throw new Error('Content distance must be a CSS length.');
+        tracks.push({ element, pseudoElement, easing: 'linear', composite: 'add', frames: [
+                { translate: `0 ${distance}`, offset: 0 }, { translate: `0 ${distance}`, offset: start, easing },
+                { translate: '0 0', offset: end }, { translate: '0 0', offset: 1 }
+            ] });
+    }
+    if (blurEnd !== undefined)
+        tracks.push({ element, pseudoElement, easing: 'linear', frames: [
+                { filter: blurred, offset: 0, easing }, { filter, offset: blurEnd }, { filter, offset: 1 }
+            ] });
+    return tracks;
+}

package/dist/core/content-groups.d.ts

@@ -0,0 +1,18 @@
+/** Keep icon/label pairs and semantic sections together; never reveal nested groups twice. */
+export declare function contentGroups(roots: HTMLElement[]): HTMLElement[];
+/** Bound the stagger so any number of groups still finishes inside the same timeline. */
+export declare function contentStagger(content: HTMLElement, count: number, span?: number): number;
+/** Opt in to a shared overlapping sequence: surface first, then its groups. */
+export declare function hasSurfaceSequence(content: HTMLElement): boolean;
+export declare function sequenceTiming(content: HTMLElement, count: number, index: number): {
+    start: number;
+    end: number;
+};
+export declare function revealGroups(content: HTMLElement, roots: HTMLElement[], pseudos: string[], progressive: boolean): {
+    targets: {
+        element: HTMLElement;
+        pseudoElement: string | undefined;
+        order: number;
+    }[];
+    orders: number[];
+};

package/dist/core/content-groups.js

@@ -0,0 +1,34 @@
+import { contentTimeline } from './content-timing.js';
+/** Keep icon/label pairs and semantic sections together; never reveal nested groups twice. */
+export function contentGroups(roots) {
+    const selector = '[data-motion-order],[data-motion-content-group],header,footer,[role="menuitem"],button,h1,h2,h3,h4,h5,h6,p,small,figure,figcaption,label,input,textarea,select';
+    const groups = roots.flatMap(root => {
+        if (root.matches(selector))
+            return [root];
+        const candidates = Array.from(root.querySelectorAll(selector));
+        return candidates.length ? candidates.filter(item => !candidates.some(other => other !== item && other.contains(item))) : [root];
+    });
+    return Array.from(new Set(groups)).filter(item => !groups.some(other => other !== item && other.contains(item))).map((element, index) => ({ element, index, order: Number(element.dataset.motionOrder ?? index) })).sort((a, b) => a.order - b.order || a.index - b.index).map(item => item.element);
+}
+/** Bound the stagger so any number of groups still finishes inside the same timeline. */
+export function contentStagger(content, count, span = 1) {
+    return contentTimeline(content, count, { end: span }).step;
+}
+/** Opt in to a shared overlapping sequence: surface first, then its groups. */
+export function hasSurfaceSequence(content) {
+    return content.matches('[data-motion-sequence="surface-first"],.motion-sequence');
+}
+export function sequenceTiming(content, count, index) {
+    return contentTimeline(content, count).at(index);
+}
+export function revealGroups(content, roots, pseudos, progressive) {
+    const grouped = progressive ? contentGroups(roots) : roots;
+    const generated = Array.from(new Set(pseudos));
+    const targets = [
+        ...Array.from(new Set(grouped)).map((element, index) => ({ element, pseudoElement: undefined, order: Number(element.dataset.motionOrder ?? (index + generated.length)) })),
+        ...generated.map((pseudoElement, index) => ({ element: content, pseudoElement, order: Number(content.getAttribute(pseudoElement === '::before' ? 'data-motion-before-order' : 'data-motion-after-order') ?? index) })),
+    ].sort((a, b) => a.order - b.order);
+    if (targets.some(target => !Number.isFinite(target.order)))
+        throw new Error('Motion content order must be numeric.');
+    return { targets, orders: Array.from(new Set(targets.map(target => target.order))) };
+}

package/dist/core/content-layout.d.ts

@@ -0,0 +1,4 @@
+import type { Track } from './animation.js';
+/** Hold the existing inner layout in its final position while the surface
+ * resizes around it. Measurements happen once; reversal reuses native tracks. */
+export declare function fixedContentTracks(content: HTMLElement, frames: Keyframe[], pseudoElements?: ReadonlyArray<'::before' | '::after'>): Track[];