@blukavantui/community 1.0.1 → 1.2.0

package/src/motion/value.ts

@@ -0,0 +1,61 @@
+import type { MotionController, MotionResult } from './controller.js';
+import { preserveStyles, type TransitionOptions } from './structure.js';
+
+export function finiteValue(value: number) { if (!Number.isFinite(value)) throw new Error('Provide a finite value.'); return value; }
+const percent = (value: number) => Math.max(0, Math.min(100, finiteValue(value)));
+
+/** Visual fill only. Owner supplies the real value and progress semantics. */
+export function createProgressTransition(fill: HTMLElement, motion: MotionController, initial = 0) {
+  const restore = preserveStyles(fill, ['transform', 'transform-origin']);
+  let value = percent(initial), revision = 0, destroyed = false;
+  fill.style.transformOrigin = 'left center'; fill.style.transform = `scaleX(${value / 100})`;
+  return {
+    async set(next: number, options: TransitionOptions = {}): Promise<MotionResult> {
+      next = percent(next); if (destroyed) return 'cancelled';
+      const own = ++revision, from = fill.ownerDocument.defaultView!.getComputedStyle(fill).transform;
+      motion.cancel(fill); value = next; fill.style.transform = `scaleX(${value / 100})`;
+      await motion.animate(fill, [{ transform: from }, { transform: fill.style.transform }], options);
+      return !destroyed && own === revision ? 'finished' : 'cancelled';
+    },
+    destroy() { destroyed = true; ++revision; motion.cancel(fill); restore(); },
+  };
+}
+
+/** SVG drawing or measured progress, normalized to 0–100 without guessing path length. */
+export function createStrokeTransition(path: SVGGeometryElement, motion: MotionController, initial = 0) {
+  const oldLength = path.getAttribute('pathLength'), restore = preserveStyles(path, ['stroke-dasharray', 'stroke-dashoffset']);
+  let revision = 0, destroyed = false;
+  const start = percent(initial);
+  path.setAttribute('pathLength', '1'); path.style.strokeDasharray = '1'; path.style.strokeDashoffset = String(1 - start / 100);
+  return {
+    async set(next: number, options: TransitionOptions = {}): Promise<MotionResult> {
+      next = percent(next); if (destroyed) return 'cancelled';
+      const own = ++revision, from = path.ownerDocument.defaultView!.getComputedStyle(path).strokeDashoffset;
+      motion.cancel(path); path.style.strokeDashoffset = String(1 - next / 100);
+      await motion.animate(path, [{ strokeDashoffset: from }, { strokeDashoffset: path.style.strokeDashoffset }], options);
+      return !destroyed && own === revision ? 'finished' : 'cancelled';
+    },
+    destroy() { destroyed = true; ++revision; motion.cancel(path); restore(); if (oldLength === null) path.removeAttribute('pathLength'); else path.setAttribute('pathLength', oldLength); },
+  };
+}
+
+/** One stable accessible value. Intermediate visual numbers are never live announcements. */
+export function createNumberTransition(element: HTMLElement, motion: MotionController, options: { value: number; format?: (value: number) => string }) {
+  let current = finiteValue(options.value), revision = 0, destroyed = false;
+  const original = Array.from(element.childNodes), doc = element.ownerDocument;
+  const visual = doc.createElement('span'), accessible = doc.createElement('span');
+  visual.setAttribute('aria-hidden', 'true'); accessible.className = 'blu-motion-sr-only';
+  const format = options.format || ((value: number) => Math.round(value).toLocaleString());
+  visual.textContent = accessible.textContent = format(current); element.replaceChildren(visual, accessible);
+  return {
+    async set(next: number, timing: TransitionOptions = {}): Promise<MotionResult> {
+      finiteValue(next); if (destroyed) return 'cancelled';
+      const text = format(next), own = ++revision;
+      accessible.textContent = text;
+      await motion.tween(element, current, next, value => { current = value; visual.textContent = format(value); }, timing);
+      if (destroyed || own !== revision) return 'cancelled';
+      current = next; visual.textContent = text; return 'finished';
+    },
+    destroy() { if (destroyed) return; destroyed = true; ++revision; motion.cancel(element); element.replaceChildren(...original); },
+  };
+}

package/src/motion/view-transition.ts

@@ -0,0 +1,57 @@
+import type { MotionController, MotionEffect, MotionResult } from './controller.js';
+
+export interface ViewTransitionOptions {
+  effect?: MotionEffect | 'instant';
+  /** Container scroll only. Routing, browser history and document scroll stay app-owned. */
+  scroll?: 'preserve' | 'top';
+  /** Entrance duration; exit uses 280 ms. */
+  duration?: number;
+}
+
+/** Replace one workspace/page outlet. Latest request wins; no document/router interception. */
+export function createViewTransition(host: HTMLElement, motion: MotionController) {
+  let revision = 0, destroyed = false;
+  const originalBusy = host.getAttribute('aria-busy');
+  const restoreBusy = () => originalBusy === null ? host.removeAttribute('aria-busy') : host.setAttribute('aria-busy', originalBusy);
+  return {
+    async show(next: HTMLElement, options: ViewTransitionOptions = {}): Promise<MotionResult> {
+      if (destroyed) return 'cancelled';
+      if (next.contains(host) || next === host) throw new Error('A view cannot contain its outlet.');
+      const ownRevision = ++revision;
+      const opacity = host.ownerDocument.defaultView!.getComputedStyle(host).opacity;
+      motion.cancel(host);
+      host.setAttribute('aria-busy', 'true');
+      const current = () => !destroyed && ownRevision === revision;
+      try {
+        if (options.effect !== 'instant') await motion.animate(host, [{ opacity }, { opacity: 0 }], { phase: 'exit', duration: 280, easing: 'ease-in-out' }, 'fade');
+        if (!current()) return 'cancelled';
+        // Read focus immediately before replacement; do not steal focus if the user moved away.
+        const active = host.ownerDocument.activeElement as HTMLElement | null;
+        const hadFocus = !!active && host.contains(active);
+        const focusKey = active?.getAttribute('data-focus-key');
+        const scrollTop = host.scrollTop, scrollLeft = host.scrollLeft;
+        host.replaceChildren(next);
+        host.scrollTop = options.scroll === 'top' ? 0 : scrollTop;
+        host.scrollLeft = options.scroll === 'top' ? 0 : scrollLeft;
+        if (hadFocus) {
+          const keyed = focusKey ? Array.from(next.querySelectorAll<HTMLElement>('[data-focus-key]')).find(el => el.getAttribute('data-focus-key') === focusKey) : undefined;
+          const target = keyed || next.querySelector<HTMLElement>('[data-view-heading]') || next;
+          if (!target.hasAttribute('tabindex') && !target.matches('button,input,select,textarea,a[href]')) target.tabIndex = -1;
+          target.focus({ preventScroll: true });
+        }
+        if (options.effect !== 'instant') await motion.play(host, options.effect || 'fade', { duration: options.duration ?? 450, easing: 'ease-in-out' });
+        return current() ? 'finished' : 'cancelled';
+      } finally {
+        if (current()) restoreBusy();
+      }
+    },
+    cancel() { ++revision; motion.cancel(host); restoreBusy(); },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      ++revision;
+      motion.cancel(host);
+      restoreBusy();
+    },
+  };
+}

package/src/motion-enhancers.ts

@@ -0,0 +1,12 @@
+/** DOM-only adapters. Attach after the component mounts; dispose before its root. */
+export * from './web-motion/data-rows.js';
+export * from './web-motion/content.js';
+export * from './web-motion/statistic.js';
+export * from './web-motion/tree.js';
+export * from './web-motion/navigation.js';
+export * from './web-motion/notifications.js';
+export * from './web-motion/fields.js';
+export * from './web-motion/surfaces.js';
+export * from './web-motion/chip-ripple.js';
+export * from './web-motion/choice-ripple.js';
+export * from './web-motion/select-ripple.js';

package/src/motion-settings.ts

@@ -0,0 +1,3 @@
+/** Shared settings contract for optional component, data, chart and workflow adapters. */
+export * from './motion/component-settings.js';
+export * from './motion/settings-group.js';

package/src/motion.ts

@@ -0,0 +1,20 @@
+/** Experimental web-only 1.2 entry. Not exported by the published 1.1.0 package. */
+export * from './motion/controller.js';
+export * from './motion/view-transition.js';
+export * from './motion/button.js';
+export * from './motion/loading.js';
+export * from './motion/effects.js';
+export * from './motion/presence.js';
+export * from './motion/stagger.js';
+export * from './motion/scroll-reveal.js';
+export * from './motion/structure.js';
+export * from './motion/feedback.js';
+export * from './motion/value.js';
+export * from './motion/scene.js';
+export * from './motion/photo.js';
+export * from './motion/border-glow.js';
+export * from './motion/tabs.js';
+export * from './motion/action-feedback.js';
+export * from './motion/screen.js';
+export * from './motion/tokens.js';
+export * from './motion/optional.js';

package/src/native-components/form-layout.ts

@@ -0,0 +1,21 @@
+import {createCheckbox} from '../checkbox.js';
+import {createTextInput} from '../text-input.js';
+import {createTextArea} from '../text-area.js';
+import {createRadioButton} from '../radio-button.js';
+import {createRadioGroup} from '../radio-group.js';
+import {createSwitch} from '../switch.js';
+import {createSelect} from '../select.js';
+import {createTable} from '../table.js';
+import {install} from '../native-base.js';
+const wrap = (factory:any) => (host:HTMLElement,p:any,events:any) => { const instance=factory(host,json(p),events); return {...instance,update:(patch:any)=>instance.update(json(patch))}; };
+const json = (p:Record<string,unknown>) => { const result={...p}; for(const key of ['Options','Rows','Columns','Actions','Leading','Trailing']) if(key+'Json' in result) { result[key]=JSON.parse(String(result[key+'Json'] || (['Leading','Trailing'].includes(key)?'null':'[]'))); delete result[key+'Json']; } return result; };
+install({
+ Checkbox:wrap(createCheckbox),
+ TextInput:wrap(createTextInput),
+ TextArea:wrap(createTextArea),
+ RadioButton:wrap(createRadioButton),
+ RadioGroup:wrap(createRadioGroup),
+ Switch:wrap(createSwitch),
+ Select:wrap(createSelect),
+ Table:wrap(createTable)
+});

package/src/native-motion-components.ts

@@ -0,0 +1,76 @@
+/** Native DOM enhancement only. Existing Blocks own all content and application events. */
+import {nativeLayoutAdapter} from './native-motion-layout.js';
+import type {MotionController} from './motion/controller.js';
+import type {Adapter,NativeMotionOptions} from './native-motion.js';
+import {observeSurface} from './web-motion/surfaces.js';
+import {enhanceField} from './web-motion/fields.js';
+import {enhanceChoiceRipple} from './web-motion/choice-ripple.js';
+import {enhanceChipRipple} from './web-motion/chip-ripple.js';
+import {enhanceSelectRipple} from './web-motion/select-ripple.js';
+import {enhanceContentMotion,type ContentMotionKind} from './web-motion/content.js';
+import {enhanceTree} from './web-motion/tree.js';
+import {enhanceNavigation} from './web-motion/navigation.js';
+import {enhanceNotifications} from './web-motion/notifications.js';
+import {enhanceDataRows,type MotionRow} from './web-motion/data-rows.js';
+import {enhanceStatistic} from './web-motion/statistic.js';
+import {tableRows} from './form-layout/table.js';
+import {createShimmer} from './motion/optional.js';
+
+const content=new Set(['profile-card','video-lightbox','video-player','collection-layout','cascader','transfer','chip','tree-select','timeline','skeleton','media-image','tour','notification-center']);
+export function nativeComponentAdapter(kind:string,root:HTMLElement,motion:MotionController):Adapter|undefined {
+  const layout=nativeLayoutAdapter(kind,root,motion);if(layout)return layout;
+  if(['drawer','palette','picker'].includes(kind)) {
+    const x=observeSurface(root,motion,kind as 'drawer'|'palette'|'picker');return {update(){x.sync();},capture:x.capture,destroy:x.destroy};
+  }
+  if(['choice','select','form-field'].includes(kind)) {
+    let target:HTMLElement|null=null,field:ReturnType<typeof enhanceField>|undefined,ripple:{destroy():void}|undefined;
+    const menu=kind==='select'?observeSurface(root,motion,'select'):undefined;
+    return {update(p){
+      const next=root.matches('.blu-field')?root:root.querySelector<HTMLElement>('.blu-field');
+      if(next!==target){field?.destroy();target=next;field=next?enhanceField(next,motion):undefined;}
+      field?.sync();menu?.sync();
+      if(p.Ripple&&!ripple)ripple=kind==='select'?enhanceSelectRipple(root,motion):enhanceChoiceRipple(root,motion);
+      else if(!p.Ripple&&ripple){ripple.destroy();ripple=undefined;}
+    },capture:()=>menu?.capture(),destroy(){field?.destroy();menu?.destroy();ripple?.destroy();}};
+  }
+  if(kind==='state-feedback'){
+    let signature=root.textContent+'|'+root.className;
+    const changed=()=>{const next=root.textContent+'|'+root.className;if(next===signature)return;signature=next;void motion.play(root,'fade',{duration:450});};
+    const observer=new MutationObserver(changed);observer.observe(root,{childList:true,subtree:true,characterData:true,attributes:true,attributeFilter:['class','aria-pressed','aria-selected']});
+    return {update:changed,destroy(){observer.disconnect();motion.cancel(root);}};
+  }
+  if(content.has(kind)) {
+    const x=enhanceContentMotion(root,motion,kind as ContentMotionKind);
+    let selected=root.classList.contains('blu-chip--selected');
+    const watch=kind==='chip'&&root.matches('.blu-chip')?new MutationObserver(()=>{const next=root.classList.contains('blu-chip--selected');if(next!==selected){selected=next;void motion.play(root,'fade',{duration:450});}}):undefined;watch?.observe(root,{attributes:true,attributeFilter:['class']});
+    let ripple:ReturnType<typeof enhanceChipRipple>|undefined;
+    return {capture:x.capture,update(p){
+      if(kind==='chip'&&p.Ripple&&!ripple)ripple=enhanceChipRipple(root,motion);
+      else if(!p.Ripple&&ripple){ripple.destroy();ripple=undefined;}
+    },destroy(){watch?.disconnect();motion.cancel(root);ripple?.destroy();x.destroy();}};
+  }
+  if(kind==='tree'){const x=enhanceTree(root,motion);return {update(){},destroy:x.destroy};}
+  if(kind==='notifications'){const x=enhanceNotifications(root,motion);return {update(){},destroy:x.destroy};}
+  if(['sidebar','pagination','tabs'].includes(kind)){const x=enhanceNavigation(root,motion,kind as 'sidebar'|'pagination'|'tabs');return {update(){},destroy:x.destroy};}
+  if(kind==='statistic'){
+    let p:NativeMotionOptions={},x:ReturnType<typeof enhanceStatistic>|undefined;
+    return {update(next){p=next;x??=enhanceStatistic(root,motion,()=>p);},capture:()=>x?.capture(),destroy:()=>x?.destroy()};
+  }
+  if(kind==='loading-skeleton'){
+    let x:ReturnType<typeof createShimmer>|undefined;
+    return {update(p){x??=createShimmer(root,{paused:p.Paused});x.update({paused:p.Paused});},destroy:()=>x?.destroy()};
+  }
+  if(kind==='grid'||kind==='table') {
+    let p:NativeMotionOptions={};
+    const read=():MotionRow[]=>{
+      if(kind==='grid')return [...root.querySelectorAll<HTMLElement>('.ag-center-cols-container > .ag-row[row-id], .ag-grid-scrolling-container > .ag-row[row-id]')].map(element=>{const cells=[...element.querySelectorAll<HTMLElement>('.ag-cell')];return {key:element.getAttribute('row-id')!,element,cells,cellKeys:cells.map(c=>c.getAttribute('col-id')||'')};});
+      // Stable native keys are supplied from the actual rendered data, never row position/text.
+      let keys:string[]=[];try{if(p.RowKeysJson) keys=JSON.parse(p.RowKeysJson).map(String); else if(p.RowKey&&!p.Loading){ const options={Caption:"",Rows:JSON.parse(p.RowsJson||'[]'),Columns:JSON.parse(p.ColumnsJson||'[]'),Page:p.Page,PageSize:p.PageSize,SortKey:p.SortKey,SortDirection:p.SortDirection as 'Ascending'|'Descending'}; keys=tableRows<Record<string,unknown>>(options).rows.map(row=>String(row[p.RowKey!])); }}catch{return [];}
+      const rows=[...root.querySelectorAll<HTMLTableRowElement>('.blu-table tbody > tr')];
+      if(rows.length!==keys.length||keys.some(k=>!k)||new Set(keys).size!==keys.length)return [];
+      return rows.map((element,i)=>({key:keys[i],element,cells:[...element.cells],cellKeys:[...element.cells].map((c,j)=>c.dataset.key||String(j))}));
+    };
+    const x=enhanceDataRows(root,motion,read);
+    return {capture:x.capture,update(next){p=next;},destroy:x.destroy};
+  }
+}

package/src/native-motion-content.ts

@@ -0,0 +1,10 @@
+/** Content producers install their current adapters regardless of which
+ * producer initialized the shared native motion registry first. */
+import { createNativeMotionRuntime } from './native-motion.js';
+import { nativeComponentAdapter } from './native-motion-components.js';
+if (typeof window !== 'undefined') {
+  window.BluUIMotion12 ??= createNativeMotionRuntime();
+  for (const kind of ['profile-card', 'collection-layout', 'video-lightbox', 'media-image']) {
+    window.BluUIMotion12.register(kind, (root, motion) => nativeComponentAdapter(kind, root, motion)!);
+  }
+}

package/src/native-motion-foundations.ts

@@ -0,0 +1,56 @@
+import type {MotionController} from './motion/controller.js';
+import type {Adapter} from './native-motion.js';
+import {createMotionPresence} from './motion/presence.js';
+import {createScrollReveal} from './motion/scroll-reveal.js';
+import {playStagger,type StaggerOrder} from './motion/stagger.js';
+import {createBorderGlow} from './motion/border-glow.js';
+import {createRipple,createShimmer,createIconTransition,createEmphasis,type MotionIcon} from './motion/optional.js';
+import {createPhotoZoom} from './motion/photo.js';
+import {createSizeTransition} from './motion/structure.js';
+import {playFeedback} from './motion/feedback.js';
+import {createLoadingIndicator} from './motion/loading.js';
+
+export function nativeFoundationAdapter(kind:string,root:HTMLElement,motion:MotionController):Adapter|undefined {
+  if(kind==='feedback'){let key:string|undefined;return {update(p){if(key===p.ReplayKey)return;key=p.ReplayKey;void playFeedback(root,motion,p.Decoration==='nudge'?'nudge':'highlight',{duration:p.Decoration==='nudge'?650:1400});},destroy(){motion.cancel(root);}};}
+  if(kind==='size'){let x:ReturnType<typeof createSizeTransition>|undefined,axis='';let value:boolean|undefined;return {update(p){const nextAxis=p.Variant==='width'?'width':'height';if(nextAxis!==axis){x?.destroy();axis=nextAxis;x=createSizeTransition(root,motion,nextAxis);value=undefined;}const next=p.IsVisible!==false;if(next===value)return;const fallback=p.FocusFallbackId?document.getElementById(p.FocusFallbackId)||undefined:undefined;if(!next&&root.contains(document.activeElement)&&(!fallback?.isConnected||root.contains(fallback)))throw Error('A focusable FocusFallbackId is required before collapsing focused content.');if(!next&&root.contains(document.activeElement)){fallback?.focus({preventScroll:true});if(root.contains(document.activeElement))throw Error('FocusFallbackId cannot receive focus.');}value=next;void x!.setOpen(next,{focusFallback:fallback,duration:650});},destroy:()=>x?.destroy()};}
+  if(kind==='visibility'){
+    const presence=createMotionPresence(root,motion);let value:boolean|undefined;
+    return {update(p){const next=p.IsVisible!==false;if(next===value)return;const fallback=p.FocusFallbackId?document.getElementById(p.FocusFallbackId)||undefined:undefined;
+      if(!next&&root.contains(document.activeElement)&&(!fallback?.isConnected||root.contains(fallback)))throw Error('A focusable FocusFallbackId outside MotionVisibility is required before hiding focused content.');
+      if(!next&&root.contains(document.activeElement)){fallback?.focus({preventScroll:true});if(root.contains(document.activeElement))throw Error('FocusFallbackId cannot receive focus.');}value=next; if(next)void presence.show({effect:p.Effect||'fade'});else void presence.hide({effect:p.Effect||'fade',focusFallback:fallback});
+    },destroy:presence.destroy};
+  }
+  if(kind==='reveal'){
+    let x:ReturnType<typeof createScrollReveal>|undefined,signature='';
+    return {update(p){const s=JSON.stringify([p.Effect,p.Once]);if(s===signature)return;signature=s;x?.destroy();x=createScrollReveal([root],motion,{effect:p.Effect||'fade',once:p.Once!==false,duration:750});},destroy:()=>x?.destroy()};
+  }
+  if(kind==='stagger'){
+    let key:string|undefined;const targets=new Set<HTMLElement>();
+    return {update(p){if(key===p.ReplayKey)return;key=p.ReplayKey;for(const el of targets)motion.cancel(el);targets.clear();
+      const items=[...root.querySelectorAll<HTMLElement>('[data-blu-stagger-item],.blu-motion-stagger-item')].slice(0,60);for(const el of items)targets.add(el);
+      void playStagger(motion,items,p.Effect||'fade',{duration:750,gap:p.GapMs??45,columns:p.Columns??1,order:(p.Order||'forward') as StaggerOrder});
+    },destroy(){for(const el of targets)motion.cancel(el);targets.clear();}};
+  }
+  if(kind==='decoration'){
+    let signature='',x:{destroy():void;update?:(p:any)=>void;setActive?:(on:boolean)=>unknown}|undefined;
+    return {update(p){const type=p.Decoration||'ripple',s=JSON.stringify([type,p.LoopDurationMs]);if(s!==signature){x?.destroy();x=undefined;signature=s;
+      if(type==='ripple')x=createRipple(root,motion);
+      else if(type==='shimmer')x=createShimmer(root,{duration:p.LoopDurationMs||1800,paused:p.Paused});
+      else if(type==='border-glow')x=createBorderGlow(root,{duration:p.LoopDurationMs||12000,paused:p.Paused});
+      else if(type==='underline'||type==='border')x=createEmphasis(root,motion,type);
+      else throw Error('Unsupported decoration.');
+    }x?.update?.({paused:p.Paused});void x?.setActive?.(p.IsActive===true);},destroy:()=>x?.destroy()};
+  }
+  if(kind==='icon'){
+    let x:ReturnType<typeof createIconTransition>|undefined,kind='';
+    return {update(p){if(kind!==(p.Decoration||'chevron')){x?.destroy();kind=p.Decoration||'chevron';x=createIconTransition(root,motion,kind as MotionIcon);}void x?.setActive(p.IsActive===true);},destroy:()=>x?.destroy()};
+  }
+  if(kind==='photo'){
+    let target:HTMLImageElement|null=null,x:ReturnType<typeof createPhotoZoom>|undefined;
+    return {update(p){const next=root.querySelector('img');if(next!==target){x?.destroy();target=next;x=next?createPhotoZoom(next,motion):undefined;}void x?.setZoomed(p.IsActive===true);},destroy:()=>x?.destroy()};
+  }
+  if(kind==='loading'){
+    let x:ReturnType<typeof createLoadingIndicator>|undefined;
+    return {update(p){const options={Label:p.Label||'Loading',Variant:(p.Variant||'Spinner') as 'Spinner'|'Dots'|'Bar',Progress:p.Progress};if(x)x.update(options);else x=createLoadingIndicator(root,options);},destroy:()=>x?.destroy()};
+  }
+}

package/src/native-motion-layout.ts

@@ -0,0 +1,35 @@
+import type {MotionController} from './motion/controller.js';
+import type {Adapter} from './native-motion.js';
+import {preserveStyles} from './motion/structure.js';
+import {createStrokeTransition} from './motion/value.js';
+export function nativeLayoutAdapter(kind:string,root:HTMLElement,motion:MotionController):Adapter|undefined {
+  if(kind==='sidebar'){
+    let open=!root.classList.contains('blu-sidebar--closed'),dead=false,revision=0,release=()=>{};
+    const sync=()=>{const next=!root.classList.contains('blu-sidebar--closed');if(next===open)return;open=next;const own=++revision;motion.cancel(root);release();release=()=>{};
+      if(next){void motion.play(root,'fade',{duration:450});return;}
+      if(motion.mode==='off'||root.contains(document.activeElement))return;
+      const style=preserveStyles(root,['display','pointer-events']),inert=root.inert,aria=root.getAttribute('aria-hidden');
+      release=()=>{style();root.inert=inert;if(aria===null)root.removeAttribute('aria-hidden');else root.setAttribute('aria-hidden',aria);};
+      root.style.setProperty('display','block','important');root.style.pointerEvents='none';root.inert=true;root.setAttribute('aria-hidden','true');
+      void motion.animate(root,[{opacity:1},{opacity:0}],{duration:450},'fade').finally(()=>{if(!dead&&own===revision){release();release=()=>{};}});
+    };const observer=new MutationObserver(sync);observer.observe(root,{attributes:true,attributeFilter:['class']});
+    return {update:sync,destroy(){dead=true;++revision;observer.disconnect();motion.cancel(root);release();}};
+  }
+  if(kind==='splitter'){
+    let columns=getComputedStyle(root).gridTemplateColumns,rows=getComputedStyle(root).gridTemplateRows,dragging=false;
+    const capture=()=>{const css=getComputedStyle(root);columns=css.gridTemplateColumns;rows=css.gridTemplateRows;};
+    const down=()=>{dragging=true;motion.cancel(root);capture();},up=()=>{dragging=false;capture();};
+    const refresh=()=>{const css=getComputedStyle(root),nextColumns=css.gridTemplateColumns,nextRows=css.gridTemplateRows;
+      if(!dragging&&(columns!==nextColumns||rows!==nextRows))void motion.animate(root,[{gridTemplateColumns:columns,gridTemplateRows:rows},{gridTemplateColumns:nextColumns,gridTemplateRows:nextRows}],{duration:650,easing:'ease-in-out'});
+      columns=nextColumns;rows=nextRows;
+    };const observer=new MutationObserver(refresh);observer.observe(root,{attributes:true,attributeFilter:['style','class']});
+    root.addEventListener('pointerdown',down,true);root.ownerDocument.addEventListener('pointerup',up,true);root.ownerDocument.addEventListener('pointercancel',up,true);
+    return {capture,update:refresh,destroy(){observer.disconnect();motion.cancel(root);root.removeEventListener('pointerdown',down,true);root.ownerDocument.removeEventListener('pointerup',up,true);root.ownerDocument.removeEventListener('pointercancel',up,true);}};
+  }
+  if(kind==='sparkline'){
+    let path:SVGGeometryElement|null=null,stroke:ReturnType<typeof createStrokeTransition>|undefined;
+    const sync=()=>{const next=root.querySelector<SVGGeometryElement>('.blu-sparkline__line');if(next===path)return;stroke?.destroy();path=next;stroke=next?createStrokeTransition(next,motion,0):undefined;void stroke?.set(100,{duration:750});};
+    const observer=new MutationObserver(sync);observer.observe(root,{childList:true,subtree:true});sync();
+    return {update:sync,destroy(){observer.disconnect();stroke?.destroy();}};
+  }
+}

package/src/native-motion-pilot.ts

@@ -0,0 +1,151 @@
+/** Private O11 pilot. Enhances stable native wrappers; never owns their children. */
+import { createMotionController, type MotionController, type MotionEffect } from './motion/controller.js';
+import { createComponentMotionScope, validateComponentMotion, type ComponentMotionSettings } from './motion/component-settings.js';
+import { motionEffects } from './motion/effects.js';
+import { createPressFeedback } from './motion/feedback.js';
+import { createMotionPresence } from './motion/presence.js';
+import { enhanceField } from './web-motion/fields.js';
+import { observeSurface } from './web-motion/surfaces.js';
+
+export interface NativeMotionOptions {
+  EnableMotion?: boolean;
+  Preference?: 'System' | 'Reduced' | 'Off';
+  UseDefaultDuration?: boolean;
+  DurationMs?: number;
+  Easing?: ComponentMotionSettings['easing'];
+  Effect?: MotionEffect;
+  ReplayKey?: string;
+  ActivePanel?: string;
+  FocusFallbackId?: string;
+}
+type Kind = 'provider' | 'container' | 'button' | 'field' | 'modal' | 'workspace';
+type Adapter = { update(p: NativeMotionOptions): void; capture?(): void; destroy(): void };
+type Owner = { root: HTMLElement; kind: Kind; parent?: Owner; controller?: MotionController; scope?: ReturnType<typeof createComponentMotionScope>; adapter: Adapter; signature: string; priorKind: string | null; options: NativeMotionOptions };
+
+export function nativeMotionSettings(p: NativeMotionOptions): ComponentMotionSettings {
+  const preference = p.Preference ?? 'System';
+  if (!['System', 'Reduced', 'Off'].includes(preference)) throw Error('Preference must be System, Reduced or Off.');
+  if (p.Effect !== undefined && !(motionEffects as readonly string[]).includes(p.Effect) && p.Effect !== 'scale') throw Error('Unknown motion effect.');
+  if (p.UseDefaultDuration === false && p.DurationMs === undefined) throw Error('DurationMs is required when UseDefaultDuration is False.');
+  return validateComponentMotion({ mode: preference === 'System' ? 'inherit' : preference.toLowerCase() as 'reduced' | 'off',
+    duration: p.UseDefaultDuration === false ? p.DurationMs : undefined, easing: p.Easing });
+}
+
+/** Multiple producer scripts share this registry, never overlapping body controllers. */
+export function createNativeMotionRuntime() {
+  const owners = new Map<string, Owner>();
+  const hosts = new WeakMap<HTMLElement, string>();
+  function parentOf(root: HTMLElement): Owner | undefined {
+    for (let el = root.parentElement; el; el = el.parentElement) {
+      const owner = owners.get(hosts.get(el) || '');
+      if (owner?.kind === 'provider') return owner;
+    }
+  }
+  function destroy(id: string) {
+    const owner = owners.get(id); if (!owner) return;
+    // Children release their adapters before a screen provider disappears.
+    for (const [childId, child] of owners) if (child.parent === owner) destroy(childId);
+    owner.adapter.destroy(); owner.scope?.destroy(); owner.controller?.destroy();
+    if (owner.priorKind === null) owner.root.removeAttribute('data-blu-native-motion');
+    else owner.root.setAttribute('data-blu-native-motion', owner.priorKind);
+    owners.delete(id); if (hosts.get(owner.root) === id) hosts.delete(owner.root);
+  }
+  function makeAdapter(kind: Kind, root: HTMLElement, motion: MotionController): Adapter {
+    if (kind === 'modal') {
+      // The original modal owns focus, events and slots. Only its JS-created
+      // surface is enhanced; closing copies are inert, unnamed visual decoration.
+      const surface = observeSurface(root, motion, 'modal');
+      return { update() { surface.sync(); }, capture: surface.capture, destroy: surface.destroy };
+    }
+    if (kind === 'button') {
+      const press = createPressFeedback(root, motion);
+      let busy = root.getAttribute('aria-busy'), face: HTMLElement | null = null;
+      const refresh = () => {
+        const next = root.getAttribute('aria-busy');
+        if (next === busy) return;
+        busy = next; if (face) motion.cancel(face);
+        face = root.querySelector<HTMLElement>('.blu-button-content');
+        // Native If widgets still own the label/spinner. Fade the stable face only.
+        if (face) void motion.play(face, 'fade', { duration: 350 });
+      };
+      const observer = new MutationObserver(refresh);
+      observer.observe(root, { attributes: true, attributeFilter: ['aria-busy'], childList: true, subtree: true });
+      return { update: refresh, destroy() { observer.disconnect(); if (face) motion.cancel(face); press.destroy(); } };
+    }
+    if (kind === 'field') {
+      let target: HTMLElement | null = null, field: ReturnType<typeof enhanceField> | undefined;
+      return { update() {
+        const next = root.matches('.blu-field') ? root : root.querySelector<HTMLElement>('.blu-field');
+        if (next !== target) { field?.destroy(); target = next; field = target ? enhanceField(target, motion) : undefined; }
+        field?.sync();
+      }, destroy() { field?.destroy(); } };
+    }
+    if (kind === 'workspace') {
+      const panels = Array.from(root.children).filter((el): el is HTMLElement => el instanceof HTMLElement && el.classList.contains('blu-native-workspace-panel'));
+      if (panels.length !== 2) throw Error('WorkspaceTransition requires two stable native panel wrappers.');
+      const presence = panels.map(el => createMotionPresence(el, motion));
+      let active = -1, dead = false, revision = 0;
+      return { update(p) {
+        const next = p.ActivePanel === 'Second' ? 1 : 0;
+        if (next === active) return;
+        const old = active; active = next; const own = ++revision;
+        const fallback = (p.FocusFallbackId ? root.ownerDocument.getElementById(p.FocusFallbackId) : root) || root;
+        if (old < 0) { panels.forEach((panel, i) => { panel.hidden = i !== next; panel.inert = i !== next; }); return; }
+        // Existing values and nodes stay in place; application state already changed.
+        if (panels[old].contains(root.ownerDocument.activeElement)) fallback.focus({ preventScroll: true });
+        if (panels[old].contains(root.ownerDocument.activeElement)) root.focus({ preventScroll: true });
+        const options = { effect: p.Effect || 'fade' as MotionEffect, duration: 650, focusFallback: root };
+        void presence[old].hide(options).then(() => { if (!dead && own === revision) panels[old].inert = true; });
+        void presence[next].show(options);
+      }, destroy() { dead = true; ++revision; presence.forEach(p => p.destroy()); } };
+    }
+    let replay: string | undefined;
+    return { update(p) {
+      if (kind !== 'container' || p.ReplayKey === replay) return;
+      replay = p.ReplayKey;
+      void motion.play(root, p.Effect || 'fade', { duration: 750 });
+    }, destroy() { motion.cancel(root); } };
+  }
+  function sync(kind: Kind, hostId: string, p: NativeMotionOptions, ownerId = hostId): string {
+    try {
+      if (!ownerId) throw Error('A stable native motion owner is required.');
+      if (p.EnableMotion !== true) { destroy(ownerId); return ''; }
+      const settings = nativeMotionSettings(p); // Reject invalid changes before touching the old adapter.
+      const root = document.getElementById(hostId); if (!root) { destroy(ownerId); return 'Native motion host is not rendered yet.'; }
+      const parent = parentOf(root), previous = owners.get(ownerId), occupant = hosts.get(root);
+      if (occupant && occupant !== ownerId) throw Error('Native motion host already has an owner.');
+      if (previous && (previous.root !== root || previous.kind !== kind || previous.parent !== parent)) destroy(ownerId);
+      let owner = owners.get(ownerId);
+      const signature = JSON.stringify(settings);
+      if (!owner) {
+        const controller = parent ? undefined : createMotionController(root, 'system');
+        const base = parent?.scope?.motion || parent?.controller || controller!;
+        // A private controller owns the root attribute; its component scope is destroyed first.
+        const scope = createComponentMotionScope(root, base, settings);
+        const priorKind = root.getAttribute('data-blu-native-motion');
+        root.setAttribute('data-blu-native-motion', kind);
+        try {
+          owner = { root, kind, parent, controller, scope, adapter: makeAdapter(kind, root, scope.motion), signature, priorKind, options: { ...p } };
+          owners.set(ownerId, owner); hosts.set(root, ownerId);
+        } catch (error) { scope.destroy(); controller?.destroy(); if (priorKind === null) root.removeAttribute('data-blu-native-motion'); else root.setAttribute('data-blu-native-motion', priorKind); throw error; }
+      } else if (owner.signature !== signature) { owner.scope!.update(settings); owner.signature = signature; }
+      const preference = settings.mode === 'inherit' ? 'system' : settings.mode || 'system';
+      if (owner.controller && owner.controller.preference !== preference) owner.controller.setPreference(preference);
+      owner.options = { ...p };
+      owner.adapter.update({ ...p, ReplayKey: p.ReplayKey ?? '' });
+      // O11 can ready inner Blocks before their enclosing provider.
+      if (kind === 'provider') for (const [childId, child] of Array.from(owners)) {
+        if (child !== owner && root.contains(child.root) && child.parent !== parentOf(child.root)) sync(child.kind, child.root.id, child.options, childId);
+      }
+      return '';
+    } catch (error) { return error instanceof Error ? error.message : String(error); }
+  }
+  return { version: '1.2.0-local-pilot', sync, destroy,
+    capture: (id: string) => owners.get(id)?.adapter.capture?.(),
+    /** Read-only counts for lifecycle checks; does not expose application data. */
+    inspect: () => ({ owners: owners.size, kinds: Array.from(owners.values(), o => o.kind) }),
+  };
+}
+
+declare global { interface Window { BluUIMotionPilot?: ReturnType<typeof createNativeMotionRuntime> } }
+if (typeof window !== 'undefined' && !window.BluUIMotionPilot) window.BluUIMotionPilot = createNativeMotionRuntime();