@makaio/framework 1.0.0-dev-1781022866275 → 1.0.0-dev-1781023871421

package/dist/ui-kernel/index.mjs

@@ -0,0 +1 @@
+import{PageSubjects as e}from"./pages/namespace.mjs";import{z as t}from"zod";import{createBusNamespace as n}from"@makaio/framework/core";import{localSubject as r}from"@makaio/framework/bus";import{isRecord as i}from"@makaio/framework/utils";import{KernelSubjects as a}from"@makaio/framework/kernel";const o=new class{scopes=new Map([[`global`,{label:`Global`,description:`Available in global UI contexts`}],[`any`,{label:`Any`,description:`Available in every UI context`}]]);listeners=new Set;register(e,t){if(this.scopes.has(e)){console.warn(`Widget scope '${e}' already registered`);return}this.scopes.set(e,t),this.notify()}has(e){return this.scopes.has(e)}getAll(){return new Map(this.scopes)}subscribe(e){return this.listeners.add(e),()=>this.listeners.delete(e)}notify(){this.listeners.forEach(e=>e())}};function s(e,t,n=!0){let r=Array.isArray(e)?e:[e];return r.includes(t)||n&&r.includes(`any`)}const c=Object.freeze({level:`root`,values:Object.freeze({})});function l(e){return e}const u=new Set([`small`,`medium`,`large`,`full-width`]);function d(e){return typeof e==`number`&&Number.isFinite(e)}function f(e){return!i(e)||typeof e.instanceId!=`string`||typeof e.widgetId!=`string`||!d(e.col)||!d(e.row)||typeof e.size!=`string`||!u.has(e.size)||e.w!==void 0&&!d(e.w)||e.h!==void 0&&!d(e.h)||e.locked!==void 0&&typeof e.locked!=`boolean`?!1:e.config===void 0||i(e.config)}function p(e){return!i(e)||e.version!==1||!Array.isArray(e.placements)?!1:e.placements.every(e=>f(e))}var m=class{items=new Map;listeners=new Set;subscribe(e){return this.listeners.add(e),()=>this.listeners.delete(e)}notify(){let e,t=!1;if(this.listeners.forEach(n=>{try{n()}catch(n){t||=(e=n,!0)}}),t)throw e}has(e){return this.items.has(e)}size(){return this.items.size}},h=class extends m{cachedAll=null;register(e){return this.items.has(e.id)?!1:(this.items.set(e.id,l(e)),this.cachedAll=null,this.notify(),!0)}registerAll(e){e.forEach(e=>this.register(e))}get(e){return this.items.get(e)}getAll(){return this.cachedAll===null&&(this.cachedAll=Object.freeze(Array.from(this.items.values()))),this.cachedAll}getByScope(e,t=!0){return this.getAll().filter(n=>s(n.scope,e,t))}unregister(e){let t=this.items.delete(e);return t&&(this.cachedAll=null,this.notify()),t}clear(){this.items.size!==0&&(this.items.clear(),this.cachedAll=null,this.notify())}};const g=new h,_=t.string(),v=t.enum([`small`,`medium`,`large`,`full-width`]),ee=t.object({pageId:t.string().optional(),windowId:t.string().optional(),onActivate:t.unknown().refine(e=>typeof e==`function`,{message:`onActivate must be a function`}).optional()}),y=t.object({id:t.string(),name:t.string(),scope:t.union([_,t.array(_)]),description:t.string().optional(),supportedSizes:t.array(v),defaultSize:v,component:t.unknown().refine(e=>e!==void 0,{message:`component is required`}),defaultConfig:t.unknown().optional(),allowMultiple:t.boolean().optional(),activate:ee.optional()}),b=t.object({widgetId:t.string()}),x=t.object({widgetId:t.string(),instanceId:t.string()}),S=t.object({scope:_.optional()}),C=t.object({widgets:t.array(y)}),w={register:r(y),unregister:r(b),list:r({request:S,response:C}),activated:r(x)},te={register:y,unregister:b,list:{request:S,response:C},activated:x},T=n(`widget`,w),E=T.subjects,ne=480,re=500,ie=8,ae=2,oe=60,D=[8,8],se=464,O={small:1,medium:2,large:3,"full-width":4},ce=Object.freeze([]);function le(e,t=ce){let n=e.filter(e=>s(e.scope,`tray`,!1)),r=new Set(t),i=new Map(n.map(e=>[e.id,e])),a=1,o=[],c=new Set;for(let e of t){if(c.has(e))continue;c.add(e);let t=i.get(e);if(!t)continue;let n=t.trayDefaultSize??t.defaultSize,r=O[n];o.push({col:1,h:r,instanceId:`tray:locked:${e}`,locked:!0,row:a,size:n,w:2,widgetId:e}),a+=r}for(let e of n){if(r.has(e.id))continue;let t=e.trayDefaultSize??e.defaultSize,n=O[t];o.push({col:1,h:n,instanceId:`tray:item:${e.id}`,row:a,size:t,w:2,widgetId:e.id}),a+=n}return{placements:o,version:1}}function k(e,t){return g.register(t)?(e.emit(E.register,{id:t.id,name:t.name,scope:t.scope,description:t.description,supportedSizes:t.supportedSizes,defaultSize:t.defaultSize,component:t.component,defaultConfig:t.defaultConfig,allowMultiple:t.allowMultiple,activate:t.activate}).catch(e=>{console.error(`[widget-register] Failed to emit register for "${t.id}":`,e)}),!0):!1}function ue(e,t){return t.flatMap(t=>k(e,t)?[t.id]:[])}function A(e,t){return g.unregister(t)?(e.emit(E.unregister,{widgetId:t}).catch(e=>{console.error(`[widget-register] Failed to emit unregister for "${t}":`,e)}),!0):!1}const j=new WeakMap;function de(e){let t=j.get(e);if(t)return t.refCount+=1,()=>{--t.refCount,t.refCount===0&&(t.cleanup(),j.delete(e))};let n=[];n.push(e.on(E.register,e=>{let t=e.payload;g.has(t.id)||g.register(t)})),n.push(e.on(E.unregister,e=>{g.unregister(e.payload.widgetId)})),n.push(e.on(E.list,e=>{let{scope:t}=e.payload,n=t?g.getByScope(t):Array.from(g.getAll());e.setResult({widgets:n})}));let r=()=>n.forEach(e=>e()),i={cleanup:r,refCount:1};return j.set(e,i),()=>{--i.refCount,i.refCount===0&&(r(),j.delete(e))}}const M=new Map;function N(e){if(typeof e!=`string`)throw Error(`Extension name must be a non-empty string.`);let t=e.trim();if(t.length===0)throw Error(`Extension name must be a non-empty string.`);return t}function fe(e,t){let n=N(e);if(typeof t!=`function`)throw Error(`Browser factory must be a function.`);let r=M.get(n);if(r!==void 0&&r!==t)throw Error(`Browser factory already registered for extension "${n}".`);M.set(n,t)}function P(e){let t=N(e);M.delete(t)}function F(){M.clear()}function I(e){let t=N(e);return M.get(t)}function L(e,t){let n=R(e)?e:t;return n===void 0?{kind:`invalid`,reason:`expected function, got default export ${typeof e} and registry fallback ${t===void 0?`undefined`:typeof t}`}:{kind:`resolved`,factory:n}}function R(e){return typeof e==`function`}function z(e,t){for(let n of[...e].reverse())try{n()}catch(e){console.error(`${t} Cleanup failed:`,e)}}function B(e,t){return e===`any`||t===`any`?!0:e===t}function V(e,t){return e.surface?e.surface.surfaces?e.surface.surfaces.includes(t):!1:!0}function H(e,t={}){let{mode:n,level:r,group:i,surface:a,includeHidden:o=!1}=t;return e.filter(e=>{if(n&&e.mode!==n||r&&!B(e.level,r)||i&&e.group!==i||a&&!V(e,a))return!1;if(!o&&e.when)try{if(!e.when())return!1}catch(t){return console.warn(`[PageDefinitionRegistry] Page "when" callback threw, hiding page.`,{pageId:e.id,error:t}),!1}return!0})}function pe(e){if(e)return Object.freeze({...e,...e.surfaces?{surfaces:Object.freeze([...e.surfaces])}:{},...e.requiredCapabilities?{requiredCapabilities:Object.freeze([...e.requiredCapabilities])}:{}})}function me(e){if(!e.id||typeof e.id!=`string`)throw Error(`PageDefinition must have a non-empty string id`);if(!e.name||typeof e.name!=`string`)throw Error(`PageDefinition "${e.id}" must have a non-empty name`);if(e.mode!==`switch`&&e.mode!==`peek`&&e.mode!==`cover`&&e.mode!==`sheet`)throw Error(`PageDefinition "${e.id}" must have mode 'switch', 'peek', 'cover', or 'sheet'`);if(typeof e.level!=`string`||e.level.trim().length===0)throw Error(`PageDefinition "${e.id}" must have a non-empty level`);if(typeof e.component!=`function`)throw Error(`PageDefinition "${e.id}" must have a component loader function`);if(e.surface){let t=e.surface.surfaces,n=e.surface.requiredCapabilities;if(t!==void 0==(n!==void 0))throw Error(`PageDefinition "${e.id}" surface must specify exactly one of "surfaces" or "requiredCapabilities"`);if(t&&t.length===0)throw Error(`PageDefinition "${e.id}" surface.surfaces must be a non-empty array`);if(n&&n.length===0)throw Error(`PageDefinition "${e.id}" surface.requiredCapabilities must be a non-empty array`)}}var U=class extends m{cachedAll=null;register(e){if(this.items.has(e.id))throw Error(`PageDefinition "${e.id}" is already registered`);me(e);let t=Object.freeze({order:50,group:`navigate`,...e,surface:pe(e.surface)});return this.items.set(t.id,t),this.invalidateCache(),this.notify(),()=>{this.items.get(t.id)===t&&this.unregister(t.id)}}get(e){return this.items.get(e)}getAll(){return this.cachedAll||=Object.freeze(Array.from(this.items.values()).sort((e,t)=>(e.order??50)-(t.order??50))),this.cachedAll}query(e={}){return H(this.getAll(),e)}unregister(e){let t=this.items.delete(e);return t&&(this.invalidateCache(),this.notify()),t}clear(){this.items.clear(),this.invalidateCache(),this.notify()}invalidateCache(){this.cachedAll=null}};const W=new U;function he(e){o.has(e.scope)||console.warn(`[PageRegistry] Page "${e.id}" uses unregistered scope "${e.scope}". Consider registering it via widgetScopeRegistry.`);let t=new Set(e.slots.map(e=>e.id));for(let n of Object.keys(e.defaultContent))if(!t.has(n))throw Error(`Page "${e.id}" has defaultContent for slot "${n}" but slot is not declared in slots array`);if(t.size!==e.slots.length)throw Error(`Page "${e.id}" has duplicate slot IDs`);for(let t of e.slots){if(t.minColumnWidth<=0)throw Error(`Slot "${t.id}" in page "${e.id}" has invalid minColumnWidth (must be > 0)`);if(t.maxColumns<=0)throw Error(`Slot "${t.id}" in page "${e.id}" has invalid maxColumns (must be > 0)`);if(t.acceptsSizes.length===0)throw Error(`Slot "${t.id}" in page "${e.id}" has empty acceptsSizes array`)}for(let[t,n]of Object.entries(e.defaultContent))if(n)for(let r of n){if(!r.instanceId)throw Error(`Page "${e.id}" slot "${t}" has placement missing instanceId`);if(r.content.type===`widget`&&!r.content.widgetId)throw Error(`Page "${e.id}" slot "${t}" has widget placement with empty widgetId`);if(r.content.type===`view`&&!r.content.viewId)throw Error(`Page "${e.id}" slot "${t}" has view placement with empty viewId`)}}var G=class extends m{cachedAll=null;register(e){if(this.items.has(e.id))throw Error(`Page "${e.id}" is already registered`);if(e.route!==void 0){for(let t of this.items.values())if(t.route===e.route)throw Error(`Route "${e.route}" is already registered by page "${t.id}"`)}return he(e),this.items.set(e.id,e),this.invalidateCache(),this.notify(),()=>{this.items.get(e.id)===e&&this.unregister(e.id)}}get(e){return this.items.get(e)}getAll(){return this.cachedAll===null&&(this.cachedAll=Object.freeze(Array.from(this.items.values()))),this.cachedAll}getRoutablePages(){return this.getAll().filter(e=>e.route!==void 0)}getByScope(e,t=!0){return this.getAll().filter(n=>n.scope===e||t&&n.scope===`any`)}getByLevel(e,t=!0){return this.getAll().filter(n=>n.level===e||t&&(n.level===`any`||n.level===void 0))}unregister(e){let t=this.items.delete(e);return t&&(this.invalidateCache(),this.notify()),t}clear(){this.items.size!==0&&(this.items.clear(),this.invalidateCache(),this.notify())}invalidateCache(){this.cachedAll=null}};const K=new G;function ge(e,t,n){let r=[];try{if(n.pages)for(let e of n.pages)r.push(K.register(e));if(n.pageDefinitions)for(let e of n.pageDefinitions)r.push(W.register(e));return n.widgets&&n.widgets.forEach(n=>{k(e,n)?r.push(()=>A(e,n.id)):console.warn(`[registerExtensionUI] Widget "${n.id}" from extension "${t}" was already registered.`)}),()=>z(r,`[registerExtensionUI] ${t}`)}catch(e){throw z(r,`[registerExtensionUI] ${t}`),e}}const q=`#0d1117`,_e=`#e9eaed`,ve=`system-ui, sans-serif`;function ye(e,t=3e4){let n=!1,r,i,o=()=>{},s,c=new Promise((e,t)=>{r=e,i=e=>t(e)}),l=()=>{s!==void 0&&(clearTimeout(s),s=void 0)},u=()=>{n||(n=!0,l(),o(),r(`ready`))},d=()=>{n||(n=!0,l(),o(),r(`cancelled`))},f=()=>{n||(n=!0,l(),o(),r(`timeout`))},p=e=>{n||(n=!0,l(),o(),i(e instanceof Error?e:Error(String(e))))};return t>0&&(s=setTimeout(f,t)),o=e.on(a.ready,()=>{u()}),(async()=>{try{let t=await e.requestOptional(a.isReady,{});if(n)return;t.handled&&t.data.ready&&u()}catch(e){p(Error(`[waitForRuntimeReady] Readiness probe failed`,{cause:e}))}})(),{cleanup:d,ready:c}}function be(e){return e===`peek`||e===`cover`||e===`sheet`}var J=class extends m{cachedByParent=null;register(e){let t=this.makeKey(e.parentPageId,e.id);return this.items.has(t)?()=>void 0:(this.items.set(t,e),this.invalidateCache(),this.notify(),()=>{this.items.get(t)===e&&this.unregister(e.parentPageId,e.id)})}get(e,t){let n=this.makeKey(e,t);return this.items.get(n)}getByParent(e){this.cachedByParent||=new Map;let t=this.cachedByParent.get(e);return t||(t=Array.from(this.items.values()).filter(t=>t.parentPageId===e).sort((e,t)=>(e.order??100)-(t.order??100)),this.cachedByParent.set(e,t)),t}getByParentAndCategory(e,t){return this.getByParent(e).filter(e=>e.category===t)}unregister(e,t){let n=this.makeKey(e,t),r=this.items.delete(n);return r&&(this.invalidateCache(),this.notify()),r}clear(){this.items.clear(),this.invalidateCache(),this.notify()}makeKey(e,t){return`${e}:${t}`}invalidateCache(){this.cachedByParent=null}};const xe=new J;function Se(t){return t.on(e.list,e=>{let{surface:t}=e.payload,n=W.query(t?{surface:t}:{});e.setResult({pages:n.map(e=>({id:e.id,name:e.name,description:e.description,mode:e.mode,level:e.level,surfaces:e.surface===void 0?`all`:e.surface.surfaces?[...e.surface.surfaces]:void 0}))})})}function Ce(e,t){return`page-layout:${e}:${t.contextId!==null&&t.contextId!==void 0?`${t.scope}:${t.contextId}`:t.scope}`}const we={layout:`page-layout`,slotState:`page-slot-state`,editMode:`page-edit-mode`},Te=new Set([`focus`,`page`,`command`,`callback`,`external`]);function Ee(e){if(!e.id||typeof e.id!=`string`)throw Error(`NavigationTarget must have a non-empty string id`);if(!e.label||typeof e.label!=`string`)throw Error(`NavigationTarget "${e.id}" must have a non-empty label`);if(!e.action||typeof e.action.type!=`string`||!Te.has(e.action.type))throw Error(`NavigationTarget "${e.id}" must have a valid action`);if(typeof e.level!=`string`||e.level.trim().length===0)throw Error(`NavigationTarget "${e.id}" must have a non-empty level`)}function De(e,t){return e.level===`any`||t===`any`?!0:e.level===t}var Y=class extends m{cachedAll=null;register(e){if(this.items.has(e.id))throw Error(`NavigationTarget "${e.id}" is already registered`);Ee(e);let t=Object.freeze({...e,order:e.order??50,group:e.group??`navigate`,action:Object.freeze({...e.action})});return this.items.set(t.id,t),this.invalidateCache(),this.notify(),()=>{this.items.get(t.id)===t&&this.unregister(t.id)}}get(e){return this.items.get(e)}getAll(){return this.cachedAll||=Object.freeze(Array.from(this.items.values()).sort((e,t)=>(e.order??50)-(t.order??50))),this.cachedAll}query(e={}){let{level:t,group:n,includeHidden:r=!1}=e;return this.getAll().filter(e=>{if(t&&!De(e,t)||n&&e.group!==n)return!1;if(!r&&e.when)try{if(!e.when())return!1}catch(t){return console.warn(`[NavigationRegistry] Target "when" callback threw, hiding target.`,{targetId:e.id,error:t}),!1}return!0})}getByLevel(e){return this.query({level:e})}getByGroup(e){return this.query({group:e})}unregister(e){let t=this.items.delete(e);return t&&(this.invalidateCache(),this.notify()),t}clear(){this.items.clear(),this.invalidateCache(),this.notify()}invalidateCache(){this.cachedAll=null}};const Oe=new Y,ke=Object.freeze([Object.freeze({id:`navigate`,label:`Navigate`,order:0}),Object.freeze({id:`analytics`,label:`Analytics`,order:5}),Object.freeze({id:`quick-access`,label:`Quick Access`,order:10})]),Ae=new Set([`project-overview`,`control-center`,`agent-manager`]);function je(e){let t=(e.split(`#`)[0].split(`?`)[0].replace(/\/+$/,``)||`/`).split(`/`).filter(Boolean);return t.length===0?`_blank`:t[0]===`apps`&&t[1]?`apps-${t[1]}`:t[0]===`project`&&t[1]?`project-${t[1]}`:t[0]===`chat`?t[1]?`chat-${t[1]}`:`_blank`:t.length===1&&Ae.has(t[0])?t[0]:`_blank`}const Me=t.enum([`electron`,`electrobun`,`web`,`mobile`,`tray`]),X={ready:t.object({surface:Me,timestamp:t.number()}),navigate:{request:t.object({url:t.string().regex(/^\/(?!\/)/,`url must be an internal app path starting with a single /`)}),response:t.object({action:t.enum([`opened`,`focused`,`navigated`])})},"popover.show":{request:t.object({x:t.number().optional(),y:t.number().optional()}),response:t.object({shown:t.boolean()})},"shortcut.triggered":t.object({accelerator:t.string()})},Z=n(`ui`,X),Ne=Z.subjects;function Pe(e){return!!(typeof e==`function`||typeof e==`object`&&e&&`$$typeof`in e)}function Fe(e){if(!e.id||typeof e.id!=`string`)throw Error(`OnboardingStepDefinition must have a non-empty string id`);if(!e.title||typeof e.title!=`string`)throw Error(`OnboardingStepDefinition "${e.id}" must have a non-empty title`);if(typeof e.order!=`number`||!isFinite(e.order))throw Error(`OnboardingStepDefinition "${e.id}" must have a finite numeric order`);if(!Pe(e.component))throw Error(`OnboardingStepDefinition "${e.id}" must have a component`)}var Q=class extends m{cachedAll=null;register(e){return Fe(e),this.items.has(e.id)&&this.items.delete(e.id),this.items.set(e.id,e),this.invalidateCache(),this.notify(),()=>{this.items.get(e.id)===e&&this.unregister(e.id)}}get(e){return this.items.get(e)}getAll(){return this.cachedAll||=Object.freeze(Array.from(this.items.values()).sort((e,t)=>e.order-t.order)),this.cachedAll}unregister(e){let t=this.items.delete(e);return t&&(this.invalidateCache(),this.notify()),t}clear(){this.items.clear(),this.invalidateCache(),this.notify()}invalidateCache(){this.cachedAll=null}};const Ie=new Q,$=[{label:`Essential`,members:new Set([`hash-trigger`,`tool-tracking`,`artifacts`,`coordinator`]),defaultEnabled:!0,alwaysEnabled:!0},{label:`Recommended`,members:new Set([`context-advisor`,`terminal`,`conversation-timeline`,`skill-injector`,`code-annotations`,`agent-notes`,`pin-message`,`file-history`,`lock`]),defaultEnabled:!0,alwaysEnabled:!1},{label:`Developer Workflow`,members:new Set([`github`,`pr-review`,`worktree`,`drift-detector`]),defaultEnabled:!0,alwaysEnabled:!1},{label:`Advanced`,members:new Set([`routine`,`loop`,`summarize`,`vision`,`instruction-guard`,`question-extractor`]),defaultEnabled:!1,alwaysEnabled:!1},{label:`Integrations`,members:new Set([`pushover`,`linear-tasks`,`opencode`]),defaultEnabled:!1,alwaysEnabled:!1},{label:`Debug`,members:new Set([]),defaultEnabled:!1,alwaysEnabled:!1}];function Le(e){return e.alwaysEnabled||e.defaultEnabled}const Re={label:`Other`,members:new Set,defaultEnabled:!1,alwaysEnabled:!1};function ze(e){return $.find(t=>t.members.has(e))??Re}export{c as DEFAULT_WIDGET_UI_CONTEXT,Y as NavigationRegistry,Q as OnboardingStepRegistry,we as PAGE_PREFERENCE_CATEGORIES,$ as PLUGIN_CATEGORIES,U as PageDefinitionRegistry,G as PageRegistry,J as PageSectionRegistry,m as RegistryBase,q as SHELL_BG_COLOR,ve as SHELL_FONT_FAMILY,_e as SHELL_TEXT_COLOR,ie as TRAY_CANVAS_HORIZONTAL_PADDING_PX,D as TRAY_CELL_MARGIN,ae as TRAY_GRID_COLS,se as TRAY_GRID_WIDTH_PX,oe as TRAY_ROW_HEIGHT_PX,re as TRAY_WINDOW_HEIGHT_PX,ne as TRAY_WINDOW_WIDTH_PX,Z as UiNamespace,X as UiSchemas,Ne as UiSubjects,T as WidgetNamespace,te as WidgetRawSchemas,h as WidgetRegistry,w as WidgetSchemas,E as WidgetSubjects,Ce as buildPageLayoutKey,F as clearExtensionBrowserFactories,ye as createRuntimeReadyWaiter,ke as defaultNavigationGroups,je as deriveBrowserTarget,Le as deriveDefaultEnabled,le as deriveTrayLayout,l as eraseWidgetConfig,ze as findCategory,I as getRegisteredExtensionBrowserFactory,be as isOverlayMode,p as isWidgetLayout,f as isWidgetPlacement,Oe as navigationRegistry,Ie as onboardingStepRegistry,W as pageDefinitionRegistry,K as pageRegistry,xe as pageSectionRegistry,H as queryPageDefinitions,fe as registerExtensionBrowserFactory,ge as registerExtensionUI,Se as registerPageBusHandler,k as registerWidget,ue as registerWidgets,L as resolveExtensionBrowserFactory,z as runCleanupsInReverse,de as subscribeToWidgetEvents,P as unregisterExtensionBrowserFactory,A as unregisterWidget,s as widgetMatchesScope,g as widgetRegistry,o as widgetScopeRegistry};

package/dist/ui-kernel/pages/namespace.d.mts

@@ -0,0 +1,88 @@
+import * as _$zod from "zod";
+import * as _$_makaio_core0 from "@makaio/framework/core";
+import * as _$_makaio_contracts0 from "@makaio/framework/contracts";
+import * as _$zod_v4_core0 from "zod/v4/core";
+
+//#region ui/kernel/src/pages/namespace.d.ts
+/**
+ * Page namespace registration.
+ *
+ * Provides type-safe subjects for querying page metadata over the bus.
+ * Used by slash commands, navigation, and surface-aware page filtering.
+ */
+declare const PageNamespace: _$_makaio_core0.BusNamespaceDefinition<"pages", {
+  readonly list: {
+    readonly request: _$zod.ZodObject<{
+      surface: _$zod.ZodOptional<_$zod.ZodEnum<{
+        web: "web";
+        mobile: "mobile";
+        electron: "electron";
+        electrobun: "electrobun";
+        tray: "tray";
+      }>>;
+    }, _$zod_v4_core0.$strip>;
+    readonly response: _$zod.ZodObject<{
+      pages: _$zod.ZodArray<_$zod.ZodObject<{
+        id: _$zod.ZodString;
+        name: _$zod.ZodString;
+        description: _$zod.ZodOptional<_$zod.ZodString>;
+        mode: _$zod.ZodEnum<{
+          switch: "switch";
+          peek: "peek";
+          cover: "cover";
+          sheet: "sheet";
+        }>;
+        level: _$zod.ZodCustom<_$_makaio_contracts0.UiNavigationLevel, _$_makaio_contracts0.UiNavigationLevel>;
+        surfaces: _$zod.ZodOptional<_$zod.ZodUnion<readonly [_$zod.ZodLiteral<"all">, _$zod.ZodArray<_$zod.ZodEnum<{
+          web: "web";
+          mobile: "mobile";
+          electron: "electron";
+          electrobun: "electrobun";
+          tray: "tray";
+        }>>]>>;
+      }, _$zod_v4_core0.$strip>>;
+    }, _$zod_v4_core0.$strip>;
+  };
+}>;
+/**
+ * Page bus subjects for querying page metadata.
+ *
+ * Subjects available:
+ * - `PageSubjects.list` — Query available pages with optional surface filter (RPC)
+ */
+declare const PageSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSubjectDefinitions<"pages", {
+  readonly list: {
+    readonly request: _$zod.ZodObject<{
+      surface: _$zod.ZodOptional<_$zod.ZodEnum<{
+        web: "web";
+        mobile: "mobile";
+        electron: "electron";
+        electrobun: "electrobun";
+        tray: "tray";
+      }>>;
+    }, _$zod_v4_core0.$strip>;
+    readonly response: _$zod.ZodObject<{
+      pages: _$zod.ZodArray<_$zod.ZodObject<{
+        id: _$zod.ZodString;
+        name: _$zod.ZodString;
+        description: _$zod.ZodOptional<_$zod.ZodString>;
+        mode: _$zod.ZodEnum<{
+          switch: "switch";
+          peek: "peek";
+          cover: "cover";
+          sheet: "sheet";
+        }>;
+        level: _$zod.ZodCustom<_$_makaio_contracts0.UiNavigationLevel, _$_makaio_contracts0.UiNavigationLevel>;
+        surfaces: _$zod.ZodOptional<_$zod.ZodUnion<readonly [_$zod.ZodLiteral<"all">, _$zod.ZodArray<_$zod.ZodEnum<{
+          web: "web";
+          mobile: "mobile";
+          electron: "electron";
+          electrobun: "electrobun";
+          tray: "tray";
+        }>>]>>;
+      }, _$zod_v4_core0.$strip>>;
+    }, _$zod_v4_core0.$strip>;
+  };
+}>, "pages">;
+//#endregion
+export { PageNamespace, PageSubjects };

package/dist/ui-kernel/pages/namespace.mjs

@@ -0,0 +1 @@
+import{PageSchemas as e}from"./schemas.mjs";import{createBusNamespace as t}from"@makaio/framework/core";const n=t(`pages`,e),r=n.subjects;export{n as PageNamespace,r as PageSubjects};

package/dist/ui-kernel/pages/schemas.d.mts

@@ -0,0 +1,2 @@
+import { a as SurfaceCapabilitySchema, c as SurfaceIdSchema, i as SurfaceCapability, l as isPageVisibleOnSurface, n as PageSchemas, o as SurfaceDeclaration, r as PageSurfaceConfig, s as SurfaceId, t as PageMetadata } from "../../schemas-DVF1A4DF.mjs";
+export { PageMetadata, PageSchemas, PageSurfaceConfig, SurfaceCapability, SurfaceCapabilitySchema, SurfaceDeclaration, SurfaceId, SurfaceIdSchema, isPageVisibleOnSurface };

package/dist/ui-kernel/pages/schemas.mjs

@@ -0,0 +1 @@
+import{z as e}from"zod";const t=e.enum([`web`,`mobile`,`electron`,`electrobun`,`tray`]),n=e.enum([`dom`,`native`,`filesystem`,`multi-window`,`touch`]);function r(e,t){return e.surfaces?e.surfaces.includes(t.id):e.requiredCapabilities?e.requiredCapabilities.every(e=>t.capabilities.includes(e)):!0}const i=e.custom(e=>typeof e==`string`&&e.length>0,`UI navigation level must be a non-empty string`),a=e.object({id:e.string(),name:e.string(),description:e.string().optional(),mode:e.enum([`switch`,`peek`,`cover`,`sheet`]),level:i,surfaces:e.union([e.literal(`all`),e.array(t)]).optional()}),o={list:{request:e.object({surface:t.optional()}),response:e.object({pages:e.array(a)})}};export{o as PageSchemas,n as SurfaceCapabilitySchema,t as SurfaceIdSchema,r as isPageVisibleOnSurface};

package/dist/ui-views/index.d.mts

@@ -0,0 +1,487 @@
+import { Component, ErrorInfo, FC, JSX, ReactNode, RefObject } from "react";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+import { ShellProps, WidgetDefinition, WidgetLayout, WidgetSize } from "@makaio/framework/ui-kernel";
+import { IMakaioBus } from "@makaio/framework/bus";
+import { UiContextSnapshot } from "@makaio/framework/contracts";
+import { Layout } from "react-grid-layout";
+
+//#region ui/views/src/widgets/WidgetContainer.d.ts
+interface WidgetContainerProps {
+  /**
+   * Widget instance ID
+   */
+  instanceId: string;
+  /**
+   * Widget title
+   */
+  title: string;
+  /**
+   * Current size
+   */
+  size: WidgetSize;
+  /**
+   * Widget content
+   */
+  children: ReactNode;
+  /**
+   * Called when remove button clicked
+   */
+  onRemove?: () => void;
+}
+/**
+ * WidgetContainer component
+ *
+ * Wraps widget content with chrome (title bar, remove button).
+ * Applies size-based styling.
+ * @param props - Component props
+ * @returns React component
+ */
+declare function WidgetContainer({
+  instanceId,
+  title,
+  size,
+  children,
+  onRemove
+}: WidgetContainerProps): _$react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region ui/views/src/widgets/built-in/StatusWidget.d.ts
+/**
+ * Framework-owned built-in widget definition that surfaces runtime and extension state.
+ *
+ * Register this definition by passing it as a `builtIn` to {@link useWidgets} so it
+ * is available in the dashboard palette and can be placed on any global-scope canvas.
+ */
+declare const frameworkStatusWidgetDefinition: WidgetDefinition;
+//#endregion
+//#region ui/views/src/widget-canvas/WidgetGrid.d.ts
+/**
+ * Configuration for the widget grid layout engine.
+ *
+ * A discriminated union on `responsive` ensures that the non-responsive branch
+ * always receives the mandatory `cols` and `width` values it requires, making
+ * silent misconfiguration a compile-time error.
+ * @example Responsive mode (default — omit `gridConfig` or pass this shape):
+ * ```tsx
+ * <WidgetCanvas gridConfig={{ responsive: true }} … />
+ * ```
+ * @example Fixed-column mode for constrained surfaces such as the tray popover:
+ * ```tsx
+ * <WidgetCanvas gridConfig={{ responsive: false, cols: 2, width: 480 }} … />
+ * ```
+ */
+type WidgetGridConfig = {
+  /**
+   * Enables react-grid-layout's `Responsive` component with automatic
+   * breakpoint detection. This is the default mode.
+   */
+  responsive: true;
+} | {
+  /**
+   * Disables breakpoint-responsive behaviour. A plain `GridLayout` is
+   * rendered with a fixed column count and an explicit pixel width.
+   * Use for constrained surfaces (e.g. tray popovers) where column
+   * changes on resize are undesirable.
+   */
+  responsive: false; /** Number of columns in the fixed grid. */
+  cols: number; /** Total grid width in pixels. Required to prevent silent misconfiguration. */
+  width: number; /** Row height in px. Falls back to the `WidgetGrid` `rowHeight` prop. */
+  rowHeight?: number; /** [horizontal, vertical] gap in px. Defaults to `[8, 8]`. */
+  margin?: [number, number];
+};
+interface WidgetGridProps {
+  /** Persisted widget layout. */
+  layout: WidgetLayout;
+  /** Widget definitions for rendering grid items. */
+  widgets: ReadonlyArray<WidgetDefinition>;
+  /** Whether the grid is in edit mode (draggable/removable). */
+  isEditing: boolean;
+  /**
+   * Called when the user changes the grid layout.
+   * @param layout - Updated widget layout.
+   */
+  onLayoutChange: (layout: WidgetLayout) => void;
+  /**
+   * Called when the user removes a widget from the grid.
+   * @param instanceId - Instance ID of the widget to remove.
+   */
+  onRemoveWidget: (instanceId: string) => void;
+  /** Height of a single grid row in pixels. */
+  rowHeight?: number;
+  /** Per-widget context values merged into each widget's config. */
+  widgetContext?: Record<string, Record<string, unknown>>;
+  /** Active host UI context for widgets rendered in this grid. */
+  uiContext?: UiContextSnapshot;
+  /** RGL dropping placeholder item. */
+  droppingItem?: {
+    i: string;
+    w: number;
+    h: number;
+  };
+  /**
+   * Called when a widget is dropped onto the grid from the palette.
+   * @param layout - Current RGL layout array.
+   * @param item - Drop target position.
+   * @param event - Native drag event carrying widget drag data.
+   */
+  onDrop?: (layout: Layout[], item: Layout, event: DragEvent) => void;
+  /** Optional layout engine configuration. When absent, defaults to responsive mode. */
+  gridConfig?: WidgetGridConfig;
+}
+/** Maps semantic widget sizes to their default grid dimensions. */
+declare const SIZE_MAPPING: Record<WidgetSize, {
+  w: number;
+  h: number;
+}>;
+/**
+ * Derive a semantic widget size from actual grid dimensions.
+ *
+ * Height is the primary signal because vertical space determines whether
+ * a widget can show detailed content (extension list) or must show a
+ * compact summary. Width is handled naturally by CSS within each tier.
+ * @param h - Current grid height in rows.
+ * @returns Semantic size for the widget's responsive rendering prop.
+ */
+declare function deriveWidgetSize(h: number): WidgetSize;
+/**
+ * Responsive grid that renders widget placements using react-grid-layout.
+ * @param props - Grid configuration including layout, widgets, and edit-mode callbacks.
+ * @returns Responsive grid with drag/resize support in edit mode.
+ */
+declare const WidgetGrid: FC<WidgetGridProps>;
+//#endregion
+//#region ui/views/src/widget-canvas/types.d.ts
+/**
+ * Props for the {@link WidgetCanvas} component.
+ */
+interface WidgetCanvasProps {
+  /** Height of a single grid row in pixels. */
+  rowHeight?: number;
+  /** Widget definitions available for placement on this canvas. */
+  widgets: ReadonlyArray<WidgetDefinition>;
+  /** Persisted layout loaded from preferences; `null` while loading. */
+  savedLayout?: WidgetLayout | null;
+  /** Whether the canvas is in a loading state. */
+  isLoading?: boolean;
+  /** Error from loading the layout, if any. */
+  error?: Error | null;
+  /**
+   * Persist the current layout.
+   * @param layout - Layout to persist.
+   */
+  onSaveLayout: (layout: WidgetLayout) => Promise<void>;
+  /**
+   * Called on every layout change (including unsaved in-progress edits).
+   * @param layout - Updated layout.
+   */
+  onLayoutChange?: (layout: WidgetLayout) => void;
+  /** Per-widget context values merged into each widget's config. */
+  widgetContext?: Record<string, Record<string, unknown>>;
+  /** Active host UI context for widgets rendered on this canvas. */
+  uiContext?: UiContextSnapshot;
+  /** Whether edit mode is externally controlled. */
+  isEditing?: boolean;
+  /** Toggle edit mode from the parent when `isEditing` is controlled. */
+  onToggleEdit?: () => void;
+  /**
+   * Optional fixed-grid configuration for non-responsive canvases (e.g. the
+   * tray surface). When `responsive: false` the canvas renders in a fixed
+   * pixel-width mode and delegates column layout to the host.
+   */
+  gridConfig?: WidgetGridConfig;
+}
+/**
+ * Internal editing state snapshot for the widget canvas.
+ */
+interface WidgetCanvasState {
+  /** Whether the canvas is in edit mode. */
+  isEditing: boolean;
+  /** In-flight layout awaiting persistence, if any. */
+  pendingLayout: WidgetLayout | null;
+  /** Widget ID currently being dragged from the palette, if any. */
+  draggingWidget: string | null;
+}
+/**
+ * Props for the floating {@link WidgetPalette} panel.
+ */
+interface WidgetPaletteProps {
+  /** Widget definitions shown in the palette. */
+  widgets: ReadonlyArray<WidgetDefinition>;
+  /** Current canvas layout (used to check which widgets are already placed). */
+  currentLayout: WidgetLayout;
+  /**
+   * Called when the user begins dragging a widget from the palette.
+   * @param widgetId - ID of the widget being dragged.
+   */
+  onDragStart: (widgetId: string) => void;
+  /** Called when a palette drag operation ends. */
+  onDragEnd: () => void;
+  /** Called when the user saves and exits edit mode via the palette close button. */
+  onClose: () => void;
+  /** Ref to the canvas container; used to clamp the floating palette position. */
+  containerRef?: RefObject<HTMLDivElement | null>;
+}
+//#endregion
+//#region ui/views/src/widget-canvas/WidgetCanvas.d.ts
+/**
+ * Editable widget dashboard that manages layout state and edit-mode lifecycle.
+ * @param props - Canvas configuration including widgets, saved layout, and save callback.
+ * @returns Widget canvas with grid, palette, and error/loading states.
+ */
+declare const WidgetCanvas: FC<WidgetCanvasProps>;
+//#endregion
+//#region ui/views/src/widget-canvas/WidgetPalette.d.ts
+/**
+ * Floating palette panel listing available widgets for drag-drop onto the canvas.
+ * @param props - Palette configuration including widget list and drag/close callbacks.
+ * @returns Draggable floating palette, or null until the container position is available.
+ */
+declare const WidgetPalette: FC<WidgetPaletteProps>;
+//#endregion
+//#region ui/views/src/widget-canvas/WidgetErrorBoundary.d.ts
+/**
+ * Props for {@link WidgetErrorBoundary}.
+ */
+interface WidgetErrorBoundaryProps {
+  /** The widget subtree to protect. */
+  children: ReactNode;
+  /**
+   * The widget ID, used to identify which widget crashed in log output.
+   */
+  widgetId: string;
+}
+/**
+ * Internal state for {@link WidgetErrorBoundary}.
+ */
+interface WidgetErrorBoundaryState {
+  /** Whether a render error has been caught. */
+  hasError: boolean;
+}
+/**
+ * A minimal React error boundary that catches render errors thrown by a
+ * single widget and displays an inline recovery UI.
+ *
+ * React error boundaries must be class components; this component exists
+ * solely at the framework layer and intentionally uses inline styles so it
+ * carries no dependency on CSS modules or host theme tokens.
+ * @example
+ * ```tsx
+ * <WidgetErrorBoundary widgetId={placement.widgetId}>
+ *   <Widget ... />
+ * </WidgetErrorBoundary>
+ * ```
+ */
+declare class WidgetErrorBoundary extends Component<WidgetErrorBoundaryProps, WidgetErrorBoundaryState> {
+  state: WidgetErrorBoundaryState;
+  /**
+   * Update state so the next render shows the fallback UI.
+   * @param _error - The error that was thrown.
+   * @returns The updated state slice.
+   */
+  static getDerivedStateFromError(_error: unknown): WidgetErrorBoundaryState;
+  /**
+   * Log the caught error to the console with contextual widget information.
+   * @param error - The error that was thrown during rendering.
+   * @param info - React-supplied component stack information.
+   */
+  componentDidCatch(error: unknown, info: ErrorInfo): void;
+  /**
+   * Reset the error state so the widget is allowed to re-render.
+   */
+  private readonly handleRetry;
+  render(): ReactNode;
+}
+//#endregion
+//#region ui/views/src/widget-canvas/drag-payload.d.ts
+interface WidgetDragPayload {
+  widgetId: string;
+}
+interface DataTransferLike {
+  getData(type: string): string;
+  setData(type: string, data: string): void;
+}
+declare const WIDGET_DRAG_DATA_TYPE = "application/vnd.makaio.widget+json";
+declare const setWidgetDragData: (dataTransfer: DataTransferLike, payload: WidgetDragPayload) => void;
+declare const getWidgetDragData: (dataTransfer: DataTransferLike | null | undefined) => WidgetDragPayload | null;
+//#endregion
+//#region ui/views/src/shell/FrameworkShell.d.ts
+/**
+ * Minimal framework-owned shell shown when no host shell is available.
+ * @param props - Shell props supplied by the extension loader.
+ * @returns Framework dashboard chrome with status widgets.
+ */
+declare function FrameworkShell(props: ShellProps): JSX.Element;
+//#endregion
+//#region ui/views/src/shell/BusStatusIndicator.d.ts
+/**
+ * Colored dot with text indicating bus connection state.
+ *
+ * Polls `KernelSubjects.isReady` every 5 seconds; shows green when the
+ * round-trip succeeds and red on failure. StrictMode-safe via run-ID pattern.
+ * @returns Inline status indicator element.
+ */
+declare function BusStatusIndicator(): JSX.Element;
+//#endregion
+//#region ui/views/src/shell/SheetOverlay.d.ts
+/**
+ * Framework-owned sheet overlay renderer.
+ *
+ * Subscribes to {@link usePageOverlayStore} and renders a fullscreen overlay
+ * when a sheet/cover page is active. Renders nothing when no page is active.
+ *
+ * Mount this once as a sibling of the main shell content so it floats above
+ * the widget canvas without disrupting the layout flow.
+ * @returns Overlay element (always mounted; empty when no page is active).
+ */
+declare function SheetOverlay(): JSX.Element;
+//#endregion
+//#region ui/views/src/shell/tray-view.d.ts
+/**
+ * Tray surface root.
+ *
+ * Registers framework built-ins on mount, derives the tray layout from the
+ * widget registry, and renders a fixed 2-column `WidgetCanvas`.
+ * @returns Tray canvas populated with tray-scoped widgets.
+ */
+declare function TrayView(): JSX.Element;
+//#endregion
+//#region ui/views/src/extensions/ExtensionBrowserLoader.d.ts
+/**
+ * Discovers, loads, and activates all extension browser entry points.
+ *
+ * On mount it waits for `kernel.isReady` (or the `kernel.ready` event if
+ * not yet ready), then delegates browser discovery/import/registration to
+ * {@link loadExtensionBrowserContributions}. This component owns the React
+ * state machine and cleanup wiring around that shared loader. If no
+ * contribution provides a `shell`, the framework-owned fallback shell is
+ * rendered as the root workspace chrome.
+ *
+ * Uses the run-ID pattern instead of a `mounted` flag to remain safe under
+ * React StrictMode double-invocation (see lessons-learned.md).
+ * @returns Resolved extension shell or a framework fallback.
+ */
+declare function ExtensionBrowserLoader(): JSX.Element;
+//#endregion
+//#region ui/views/src/extensions/EmptyStateUI.d.ts
+/**
+ * Props for {@link EmptyStateUI}.
+ */
+interface EmptyStateUIProps {
+  /** Optional heading override for error variants. */
+  title?: string;
+  /** Primary message shown below the heading. */
+  message?: string;
+  /** Optional supporting detail line. */
+  detail?: string;
+}
+/**
+ * Minimal shell-level status surface for loader error states.
+ *
+ * Displays a minimal branded splash with a short explanation.  Uses inline
+ * styles deliberately — this is a shell-level fallback that must not depend
+ * on the theme system or any CSS module pipeline.
+ * @param props - Optional copy overrides for loader error states.
+ * @returns Fallback shell-level status UI.
+ */
+declare function EmptyStateUI({
+  title,
+  message,
+  detail
+}?: EmptyStateUIProps): JSX.Element;
+//#endregion
+//#region ui/views/src/page/PageErrorBoundary.d.ts
+/**
+ * Props for {@link PageErrorBoundary}.
+ */
+interface PageErrorBoundaryProps {
+  /** Page ID for error reporting. */
+  pageId: string;
+  /** Child components. */
+  children: ReactNode;
+  /** Optional fallback UI rendered instead of the default error card. */
+  fallback?: ReactNode;
+}
+/**
+ * Internal state for {@link PageErrorBoundary}.
+ */
+interface PageErrorBoundaryState {
+  /** Whether a render error has been caught. */
+  hasError: boolean;
+  /** The caught error, if any. */
+  error: Error | null;
+}
+/**
+ * Error boundary for page rendering.
+ *
+ * Catches render errors thrown inside a page's component tree and shows a
+ * user-friendly fallback with a retry button.  If a `fallback` prop is
+ * supplied it is rendered instead of the default error card.
+ */
+declare class PageErrorBoundary extends Component<PageErrorBoundaryProps, PageErrorBoundaryState> {
+  constructor(props: PageErrorBoundaryProps);
+  /**
+   * Transition to error state so the next render shows the fallback UI.
+   * @param error - The error thrown during rendering.
+   * @returns Updated state slice.
+   */
+  static getDerivedStateFromError(error: Error): PageErrorBoundaryState;
+  /**
+   * Log the caught error with page context for debugging.
+   * @param error - The error that was thrown.
+   * @param errorInfo - React component stack information.
+   */
+  componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+  /**
+   * Reset the error state so the page is allowed to re-render.
+   */
+  private readonly handleRetry;
+  render(): ReactNode;
+}
+//#endregion
+//#region ui/views/src/nav/Sidebar.d.ts
+/**
+ * Sidebar navigation component.
+ *
+ * Reads page definitions from registry, groups by NavigationGroup,
+ * and delegates rendering to NavSidebar. Collapsed state is persisted
+ * per navigation level via useSidebarStore (localStorage).
+ * @returns Sidebar navigation UI, or null if no pages are available.
+ */
+declare function Sidebar(): ReactNode;
+//#endregion
+//#region ui/views/src/toast/ToastProvider.d.ts
+interface ToastProviderProps {
+  /**
+   * The bus instance to use for toast communication
+   */
+  bus: IMakaioBus;
+  /**
+   * Optional application content to render alongside the Toaster.
+   */
+  children?: ReactNode;
+}
+/**
+ * Toast notification provider.
+ *
+ * Renders the <Toaster /> component and listens for toast.show events on the bus.
+ * Emits toast.interacted and toast.dismissed events for action handling and cleanup.
+ * @param props - Component properties containing the bus instance
+ * @example
+ * ```tsx
+ * import { ToastProvider } from '@makaio/framework/ui-views';
+ * import { MakaioBus } from '@makaio/framework/bus';
+ *
+ * function App() {
+ *   return (
+ *     <ToastProvider bus={MakaioBus}>
+ *       <YourAppContent />
+ *     </ToastProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function ToastProvider({
+  bus,
+  children
+}: ToastProviderProps): React.ReactElement;
+//#endregion
+export { BusStatusIndicator, type DataTransferLike, EmptyStateUI, type EmptyStateUIProps, ExtensionBrowserLoader, FrameworkShell, PageErrorBoundary, SIZE_MAPPING, SheetOverlay, Sidebar, ToastProvider, type ToastProviderProps, TrayView, WIDGET_DRAG_DATA_TYPE, WidgetCanvas, type WidgetCanvasProps, type WidgetCanvasState, WidgetContainer, type WidgetContainerProps, type WidgetDragPayload, WidgetErrorBoundary, WidgetGrid, WidgetPalette, type WidgetPaletteProps, deriveWidgetSize, frameworkStatusWidgetDefinition, getWidgetDragData, setWidgetDragData };