@tobiasoberpaul/mdk 0.1.0 → 0.1.1

package/README.md

@@ -1,95 +1,28 @@
 # MDK · UI Motion Library
 
-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.
+MDK is a framework-independent TypeScript library for reversible UI transitions. It uses the Web Animations API and CSS custom properties.
 
-## Run locally
+## Install
 
 ```sh
-npm install
-npm run dev
+npm install @tobiasoberpaul/mdk
 ```
 
-Open [the playground](http://127.0.0.1:4173/examples/).
+## Use
 
-## Publish the website
+```js
+import { createGrowTransition } from '@tobiasoberpaul/mdk';
+import '@tobiasoberpaul/mdk/motion.css';
 
-```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.
+const panel = document.querySelector('#panel');
+const toggle = document.querySelector('#toggle');
+const motion = createGrowTransition({ content: panel });
 
-```sh
-npm run build           # TypeScript library and CSS → dist/
-npm run build:examples  # Both component integrations and playground shell
+toggle.addEventListener('click', () => motion.toggle());
 ```
 
-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
+Your component manages layout, visibility, focus and accessibility. MDK handles the visual transition, including reversal and the system's reduced-motion preference.
 
-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).
+The library includes Grow, Extract, Morph, Slide and Content transitions. See the [library guide](https://github.com/TOberpaul/animations/blob/main/docs/LIBRARY.md) for the API, CSS tokens and integration patterns.
 
-See [publishing](docs/PUBLISHING.md) for npm package validation and release steps. The registry package is not published yet.
+Licensed under [MIT](LICENSE).

package/package.json

@@ -1,14 +1,10 @@
 {
   "name": "@tobiasoberpaul/mdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "files": [
     "dist",
-    "ai",
-    "docs/LIBRARY.md",
-    "docs/AI_INTEGRATION.md",
-    "docs/PUBLISHING.md",
-    "THIRD_PARTY_NOTICES.md"
+    "docs/LIBRARY.md"
   ],
   "exports": {
     ".": {
@@ -62,7 +58,6 @@
     "type": "git",
     "url": "git+https://github.com/TOberpaul/animations.git"
   },
-  "homepage": "https://toberpaul.github.io/animations/",
   "bugs": {
     "url": "https://github.com/TOberpaul/animations/issues"
   },
@@ -71,8 +66,7 @@
     "motion",
     "waapi",
     "typescript",
-    "design-system",
-    "mcp"
+    "design-system"
   ],
   "engines": {
     "node": ">=18"
@@ -80,9 +74,7 @@
   "sideEffects": [
     "**/*.css"
   ],
-  "bin": {
-    "motion-library-mcp": "ai/mcp-server.mjs"
-  },
+
   "publishConfig": {
     "access": "public"
   },

package/THIRD_PARTY_NOTICES.md

@@ -1,7 +0,0 @@
-# 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

@@ -1,14 +0,0 @@
-# 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

@@ -1,112 +0,0 @@
-#!/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/docs/AI_INTEGRATION.md

@@ -1,69 +0,0 @@
-# AI integration
-
-The library includes a local, read-only MCP server. Use it with an AI client that supports local stdio MCP servers. No model provider, API key, remote service, or runtime framework dependency is required. Each client controls its own approval and tool-use behavior.
-
-## Setup
-
-From the repository, run `npm ci` and `npm run build` once. Configure your client to launch:
-
-```text
-node /absolute/path/to/animations/ai/mcp-server.mjs
-```
-
-Use Node 18 or newer (Node 22 recommended). Paths are resolved relative to the server file, so the client's working directory does not matter. Restart the server after rebuilding the library.
-
-A common MCP configuration shape is:
-
-```json
-{
-  "mcpServers": {
-    "motion-library": {
-      "command": "node",
-      "args": ["/absolute/path/to/animations/ai/mcp-server.mjs"]
-    }
-  }
-}
-```
-
-On Windows use `C:/path/to/animations/ai/mcp-server.mjs`. For Kiro or other clients using `mcpServers`, place the entry in that client's MCP settings. Copilot in VS Code uses its own MCP configuration: put the server entry under `servers`, and add `"type": "stdio"`. Client locations and schemas vary; use the client's MCP settings UI or current documentation. This project does not silently modify any client configuration.
-
-VS Code-style entry:
-
-```json
-{
-  "servers": {
-    "motion-library": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["/absolute/path/to/animations/ai/mcp-server.mjs"]
-    }
-  }
-}
-```
-
-## What the AI receives
-
-| Capability | Purpose |
-| --- | --- |
-| `get_motion_reference` | Read guide, tokens, built TypeScript declarations, integration rules or canonical behavior definitions. |
-| `create_motion_example` | Generate a minimal disclosure integration for a selected behavior/activation, with optional placement. Returns code text without executing it. |
-| `motion://guide` | Public library guide. |
-| `motion://tokens` | Actual built motion.css. |
-| `motion://instructions` | Portable integration rules. |
-| `integrate_motion` prompt | A starting instruction for an AI-assisted component integration. |
-
-Guide, API, token and behavior responses are loaded from this checkout's documentation/build output. There is no separately maintained copy of the token values or API signatures. Rebuild after library API changes.
-
-Example request to your AI: “Use the Motion Library MCP to add an interruptible Grow transition to this existing popover. Preserve its accessibility and positioning.”
-
-## Compatibility and scope
-
-The adapter uses newline-delimited JSON-RPC over stdio. It supports initialization-based MCP versions 2025-03-26 / 2025-06-18 / 2025-11-25 and discovery-based version 2026-07-28. It offers read-only tools/resources/prompts, not remote HTTP hosting or resource subscriptions. Compatibility is conditional on the client's MCP implementation; it has not been certified in every AI product.
-
-For clients without MCP, provide `ai/INSTRUCTIONS.md` and `docs/LIBRARY.md` as repository context, or reference them from the client's own instruction file. A model-specific skill or power is not required.
-
-The GitHub Pages website cannot run a Node stdio process. The server runs locally alongside the AI client. The package has not been published to npm; use the local command above rather than an assumed npx package.
-
-## Installed package
-
-The package exposes the `motion-library-mcp` executable. After installing the package, clients can launch that command directly. Until the first registry release, use the local checkout or install its packed `.tgz` file. No registry name is assumed available.

package/docs/PUBLISHING.md

@@ -1,33 +0,0 @@
-# Publishing the package
-
-The package is prepared for npm and can also be installed with pnpm. Both use the same npm registry artifact.
-
-## Release prerequisites
-
-- License: MIT. Copyright is attributed to TOberpaul; verify attribution when accepting external contributions.
-- Sign in to npm with publish access to the `@tobiasoberpaul` scope. Check the account with `npm whoami`.
-- Confirm the version in package.json and package-lock.json, and record release changes.
-
-## Validate the artifact
-
-```sh
-npm ci
-npm run build
-npm run check:mcp
-npm pack --dry-run
-npm pack
-```
-
-The `prepack` hook builds the library. The package contains built ESM, TypeScript declarations, CSS, the MCP executable and public guides. React integrations, website assets, credentials and development dependencies are excluded. The core and MCP have no runtime dependencies.
-
-Install the resulting `.tgz` into a temporary consumer project and verify ESM imports and `motion-library-mcp`. CSS is available through `@tobiasoberpaul/mdk/motion.css`. Browser APIs are needed only when creating an animation; importing the module is safe without a browser.
-
-## Publish when ready
-
-After validation, publish `@tobiasoberpaul/mdk` to the public npm registry:
-
-```sh
-npm publish --access public
-```
-
-Use npm's required authentication/2FA flow. No token is stored in this repository. A GitHub Pages deployment publishes only the website; it does not publish an npm version. Registry releases are separate, intentional versioned actions.