@gjsify/storybook 0.10.0 → 0.12.0

package/README.md

@@ -82,6 +82,17 @@ await runStorybook({
 });
 ```
 
+## Debug it over MCP
+
+Run the storybook with `GJSIFY_DEVTOOLS=1` and it exposes the [`@gjsify/devtools`](../devtools) control plane, so an AI agent can drive it:
+
+```bash
+GJSIFY_DEVTOOLS=1 gjsify storybook        # exposes org.gjsify.Devtools
+gjsify debug --profile storybook          # MCP bridge: list_stories / get_current_story / open_story / set_story_arg (+ generic screenshot)
+```
+
+See the [Debugging & remote control guide](https://gjsify.github.io/gjsify/guides/devtools/).
+
 ## Exports
 
 - `StoryWidget` — Adw.Bin base class; `fromMeta()`, `addContent()`, `initialize()`/`updateArgs()`/`teardown()` hooks

package/lib/esm/application.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{StoryRegistryService as e}from"./registry.js";import{STORYBOOK_CSS as t}from"./styles.js";import{StorybookWindow as n}from"./window.js";import r from"@girs/adw-1";import i from"@girs/gdk-4.0";import a from"@girs/gio-2.0";import o from"@girs/gobject-2.0";import s from"@girs/gtk-4.0";var c=class StorybookApplication extends r.Application{static{o.registerClass({GTypeName:`StorybookApplication`},StorybookApplication)}constructor(t){super({application_id:t.applicationId,flags:a.ApplicationFlags.DEFAULT_FLAGS}),this._window=null,this._registry=new e,this._options=t,this.connect(`startup`,()=>this._initStyles()),this.connect(`activate`,()=>this._onActivate())}_initStyles(){let e=new s.CssProvider;e.load_from_string(`${t}\n${this._options.css??``}`);let n=i.Display.get_default();if(!n){console.error(`No display found`);return}s.StyleContext.add_provider_for_display(n,e,s.STYLE_PROVIDER_PRIORITY_APPLICATION)}_onActivate(){if(!this._window){this._window=new n({application:this}),this._options.title&&this._window.set_title(this._options.title),this._registry.registerStories(this._options.stories);try{let e=this._registry.createStoryInstances();this._window.populateSidebar(e)}catch(e){console.error(`Failed to create story instances:`,e)}}this._window.present()}};o.type_ensure(c.$gtype);export{c as StorybookApplication};
+import"./_virtual/_rolldown/runtime.js";import{storybookDevtoolsExtension as e}from"./devtools-extension.js";import{STORYBOOK_CSS as t}from"./styles.js";import{StorybookWindow as n}from"./window.js";import r from"@girs/adw-1";import i from"@girs/gdk-4.0";import a from"@girs/gio-2.0";import o from"@girs/gobject-2.0";import s from"@girs/gtk-4.0";import{installDevtools as c}from"@gjsify/devtools";var l=class StorybookApplication extends r.Application{static{o.registerClass({GTypeName:`StorybookApplication`},StorybookApplication)}constructor(e){super({application_id:e.applicationId,flags:a.ApplicationFlags.DEFAULT_FLAGS}),this._window=null,this._options=e,this.connect(`startup`,()=>this._initStyles()),this.connect(`activate`,()=>this._onActivate())}_initStyles(){let e=new s.CssProvider;e.load_from_string(`${t}\n${this._options.css??``}`);let n=i.Display.get_default();if(!n){console.error(`No display found`);return}s.StyleContext.add_provider_for_display(n,e,s.STYLE_PROVIDER_PRIORITY_APPLICATION)}_onActivate(){if(!this._window){this._window=new n({application:this}),this._options.title&&this._window.set_title(this._options.title);try{this._window.populateSidebar(this._options.stories)}catch(e){console.error(`Failed to create story instances:`,e)}c(this,{enabled:this._options.devtools||void 0,extend:[e(this._window)]})}this._window.present()}};o.type_ensure(l.$gtype);export{l as StorybookApplication};

package/lib/esm/devtools-extension.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{buildStorybookDevtoolsExtension as e}from"@gjsify/storybook-core";const t={ListStories:`<method name="ListStories"><arg type="s" direction="out" name="stories_json"/></method>`,GetCurrentStory:`<method name="GetCurrentStory"><arg type="s" direction="out" name="story_json"/></method>`,OpenStory:`<method name="OpenStory"><arg type="s" direction="in" name="title"/><arg type="b" direction="out" name="opened"/></method>`,SetStoryArg:`<method name="SetStoryArg"><arg type="s" direction="in" name="name"/><arg type="s" direction="in" name="value_json"/><arg type="b" direction="out" name="applied"/></method>`,GetStoryArgs:`<method name="GetStoryArgs"><arg type="s" direction="out" name="args_json"/></method>`};function storybookDevtoolsExtension(n){let r=e(n.controller),i=[],a={},o={};for(let e of r.methods){let n=t[e.name];n&&i.push(n),a[e.name]=e.handler,o[e.name]=e.kind}return{methodsXml:i,handlers:a,methodKinds:o,contributeStatus:r.contributeStatus}}export{storybookDevtoolsExtension};

package/lib/esm/discover.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{isStoryModule as e}from"@gjsify/stories";function collectStoryModules(t){let n=[];for(let r of t)if(!(!r||typeof r!=`object`))for(let t of Object.values(r))e(t)&&n.push(t);return n}export{collectStoryModules};
+import"./_virtual/_rolldown/runtime.js";import{collectStoryModules as e}from"@gjsify/storybook-core";function collectStoryModules(t){return e(t)}export{collectStoryModules};

package/lib/esm/index.js

@@ -1 +1 @@
-import{StoryRegistryService as e}from"./registry.js";import{StorybookWindow as t}from"./window.js";import{StorybookApplication as n}from"./application.js";import{installActionGroup as r,withActionGroup as i}from"./decorators.js";import{collectStoryModules as a}from"./discover.js";import{StoryWidget as o}from"./story-widget.js";import{runStorybook as s}from"./run.js";import{ControlType as c,argsFromControls as l,isStoryModule as u}from"@gjsify/stories";export{c as ControlType,e as StoryRegistryService,o as StoryWidget,n as StorybookApplication,t as StorybookWindow,l as argsFromControls,a as collectStoryModules,r as installActionGroup,u as isStoryModule,s as runStorybook,i as withActionGroup};
+import{storybookDevtoolsExtension as e}from"./devtools-extension.js";import{StorybookWindow as t}from"./window.js";import{StorybookApplication as n}from"./application.js";import{installActionGroup as r,withActionGroup as i}from"./decorators.js";import{collectStoryModules as a}from"./discover.js";import{StoryWidget as o}from"./story-widget.js";import{StoryRegistryService as s}from"./registry.js";import{runStorybook as c}from"./run.js";import{ControlType as l,argsFromControls as u,isStoryModule as d}from"@gjsify/stories";export{l as ControlType,s as StoryRegistryService,o as StoryWidget,n as StorybookApplication,t as StorybookWindow,u as argsFromControls,a as collectStoryModules,r as installActionGroup,d as isStoryModule,c as runStorybook,e as storybookDevtoolsExtension,i as withActionGroup};

package/lib/esm/registry.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";var StoryRegistryService=class{constructor(){this.modules=[]}registerStory(e){if(!e||!Array.isArray(e.stories)){console.warn(`Invalid story module provided to registerStory`);return}this.modules.push(e)}registerStories(e){if(!Array.isArray(e)){console.warn(`Invalid story modules array provided to registerStories`);return}let t=e.filter(e=>e&&Array.isArray(e.stories));this.modules.push(...t)}getStories(){return[...this.modules]}createStoryInstances(){for(let e of this.modules)this.instantiateStoriesForModule(e);return[...this.modules]}instantiateStoriesForModule(e){e.instances||=[];let t=e.decorators??[];for(let n of e.stories)try{let r=new n,build=()=>{typeof r.initialize==`function`&&r.initialize()};t.reduceRight((e,t)=>()=>t(e,r),build)(),e.instances.push(r)}catch(e){console.error(`Failed to instantiate story widget: ${n.name||`Unknown`}`,e)}}};export{StoryRegistryService};
+import"./_virtual/_rolldown/runtime.js";import{StoryRegistry as e,StoryRegistry as t}from"@gjsify/storybook-core";var StoryRegistryService=class extends t{};export{e as StoryRegistry,StoryRegistryService};

package/lib/esm/story-widget.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import e from"@girs/adw-1";import t from"@girs/gobject-2.0";import n from"@girs/gtk-4.0";import{argsFromControls as r}from"@gjsify/stories";var i=class StoryWidget extends e.Bin{static{t.registerClass({GTypeName:`StoryWidget`,Properties:{meta:t.ParamSpec.object(`meta`,`Meta`,`Story metadata`,t.ParamFlags.READWRITE,t.Object),story:t.ParamSpec.string(`story`,`Story Name`,`Story name`,t.ParamFlags.READWRITE,``),args:t.ParamSpec.object(`args`,`Args`,`Story arguments`,t.ParamFlags.READWRITE,t.Object)}},StoryWidget)}constructor(e,t={}){super(t),this._story=``,this._storyContent=null,this._group=null,this._meta=e.meta,this._story=e.story,this._args=e.args,this.get_child()??this._installDefaultChrome()}static fromMeta(e,t){return{meta:e,story:t,args:r(e.controls)}}get meta(){return this._meta}set meta(e){this._meta!==e&&(this._meta=e,this.notify(`meta`),this._refreshChromeText())}get story(){return this._story}set story(e){this._story!==e&&(this._story=e,this.notify(`story`),this._refreshChromeText())}get args(){return this._args}set args(e){this._args!==e&&(this._args=e,this.notify(`args`),this.updateArgs(e))}initialize(){}updateArgs(e){}teardown(){}addContent(e){if(!this._storyContent)return;let t=this._storyContent.get_first_child();for(;t;)t.unparent(),t=this._storyContent.get_first_child();this._storyContent.append(e)}_installDefaultChrome(){let t=new e.PreferencesPage,r=new e.PreferencesGroup,i=new n.Box({orientation:n.Orientation.VERTICAL,halign:n.Align.CENTER,valign:n.Align.CENTER,margin_top:12,margin_bottom:12,spacing:12,hexpand:!0});r.add(i),t.add(r),this.set_child(t),this._group=r,this._storyContent=i,this._refreshChromeText()}_refreshChromeText(){if(!this._group)return;let e=this._meta?this._story?`${this._meta.title} — ${this._story}`:this._meta.title:this._story,t=this._meta?.description??``;this._group.set_title(e),this._group.set_description(t)}};t.type_ensure(i.$gtype);export{i as StoryWidget};
+import"./_virtual/_rolldown/runtime.js";import e from"@girs/adw-1";import t from"@girs/gobject-2.0";import n from"@girs/gtk-4.0";import{StoryViewBase as r}from"@gjsify/storybook-core";import{argsFromControls as i}from"@gjsify/stories";function buildGtkChrome(t){let r=new e.PreferencesPage,i=new e.PreferencesGroup,a=new n.Box({orientation:n.Orientation.VERTICAL,halign:n.Align.CENTER,valign:n.Align.CENTER,margin_top:12,margin_bottom:12,spacing:12,hexpand:!0});return a.add_css_class(`story-stage`),i.add(a),r.add(i),t.set_child(r),{root:t,hasStage:!0,setStageContent(e){let t=a.get_first_child();for(;t;)t.unparent(),t=a.get_first_child();a.append(e)},setChromeText(e,t){i.set_title(e),i.set_description(t)}}}var StoryCore=class extends r{constructor(e,t,n){super(),this._widget=e,this.initBase(t,n)}createChrome(e){return buildGtkChrome(this._widget)}initialize(){this._widget.initialize()}updateArgs(e){this._widget.updateArgs(e)}teardown(){this._widget.teardown()}emitArgs(e){super.emitArgs(e),this._widget.notify(`args`)}},a=class StoryWidget extends e.Bin{static{t.registerClass({GTypeName:`StoryWidget`,Properties:{meta:t.ParamSpec.object(`meta`,`Meta`,`Story metadata`,t.ParamFlags.READWRITE,t.Object),story:t.ParamSpec.string(`story`,`Story Name`,`Story name`,t.ParamFlags.READWRITE,``),args:t.ParamSpec.object(`args`,`Args`,`Story arguments`,t.ParamFlags.READWRITE,t.Object)}},StoryWidget)}constructor(e,t={}){super(t),this._core=new StoryCore(this,e.meta,e.story)}static fromMeta(e,t){return{meta:e,story:t,args:i(e.controls)}}get meta(){return this._core.meta}get story(){return this._core.story}get args(){return this._core.args}set args(e){this._core.args=e}onArgsChanged(e){return this._core.onArgsChanged(e)}setArg(e,t){this._core.setArg(e,t)}initialize(){}updateArgs(e){}teardown(){}addContent(e){this._core.addContent(e)}};t.type_ensure(a.$gtype);export{a as StoryWidget};

package/lib/esm/styles.js

@@ -7,4 +7,22 @@ const e=`
 .story-range-row > box {
     border-radius: 12px;
 }
+
+/* Controls panel shares the window (story) background; only the left
+   navigation sidebar keeps a distinct shade. The overlay-split-view sidebar is
+   otherwise drawn on the sidebar shade — flatten it onto the window colour. */
+.storybook-controls > .sidebar,
+.storybook-controls > .sidebar > * {
+    background-color: @window_bg_color;
+}
+
+/* Subtle dashed frame around the live preview so the widget's bounds stay
+   locatable even when it is transparent or in an empty state (e.g. a collapsed
+   bottom sheet, a status page, a bare button). @window_fg_color flips with the
+   theme (alpha(currentColor, …) does not resolve in a Gtk.CssProvider). */
+.story-stage {
+    border: 1px dashed alpha(@window_fg_color, 0.28);
+    border-radius: 12px;
+    padding: 18px;
+}
 `;export{e as STORYBOOK_CSS};

package/lib/esm/window.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import e from"@girs/adw-1";import t from"@girs/gdk-4.0";import n from"@girs/gobject-2.0";import r from"@girs/gtk-4.0";import{ControlType as i}from"@gjsify/stories";var a=class StorybookWindow extends e.ApplicationWindow{static{n.registerClass({GTypeName:`StorybookWindow`},StorybookWindow)}constructor(e){super(e),this._controlRows=[],this._controlRefreshers=[],this._activeStoryHandlerId=0,this._activeStory=null,this.set_default_size(1200,800),this.set_size_request(360,320),this.set_title(`Storybook`),this._buildUI(),this._sidebar_list.connect(`row-selected`,this._onStorySelected.bind(this)),this._show_controls_button.connect(`toggled`,this._onToggleControls.bind(this)),this._controls_split_view.set_show_sidebar(!0)}_buildUI(){this._sidebar_list=new r.ListBox({selection_mode:r.SelectionMode.SINGLE}),this._sidebar_list.add_css_class(`navigation-sidebar`);let t=new r.ScrolledWindow({hexpand:!0,vexpand:!0,child:this._sidebar_list}),n=new e.HeaderBar({title_widget:new e.WindowTitle({title:`Stories`}),show_end_title_buttons:!1}),i=new e.ToolbarView({content:t});i.add_top_bar(n);let a=new e.NavigationPage({title:`Stories`,tag:`stories`,child:i});this._content_area=new e.Bin({hexpand:!0,vexpand:!0});let o=new r.ScrolledWindow({hexpand:!0,vexpand:!0,child:this._content_area});this._control_panel=new e.PreferencesGroup({title:`Controls`});let s=new e.PreferencesPage;s.add(this._control_panel);let c=new r.ScrolledWindow({vexpand:!0,child:s});this._controls_split_view=new e.OverlaySplitView({show_sidebar:!0,sidebar_position:r.PackType.END,min_sidebar_width:280,max_sidebar_width:360,content:o,sidebar:c}),this._preview_title=new e.WindowTitle({title:`Preview`}),this._show_controls_button=new r.ToggleButton({icon_name:`sidebar-show-right-symbolic`,tooltip_text:`Toggle Controls`,active:!0});let l=new e.HeaderBar({title_widget:this._preview_title});l.pack_end(this._show_controls_button);let u=new e.ToolbarView({content:this._controls_split_view});u.add_top_bar(l);let d=new e.NavigationPage({title:`Preview`,tag:`preview`,child:u});this._main_split_view=new e.NavigationSplitView({min_sidebar_width:220,max_sidebar_width:320,sidebar:a,content:d}),this.set_content(this._main_split_view);let f=e.BreakpointCondition.parse(`max-width: 720sp`);if(f){let t=new e.Breakpoint({condition:f});t.connect(`apply`,()=>{this._main_split_view.collapsed=!0,this._controls_split_view.collapsed=!0}),t.connect(`unapply`,()=>{this._main_split_view.collapsed=!1,this._controls_split_view.collapsed=!1}),this.add_breakpoint(t)}}_onToggleControls(e){this._controls_split_view.set_show_sidebar(e.get_active())}populateSidebar(e){if(this._clearSidebar(),!e.some(e=>e.instances?.length)){console.error(`Story modules do not have instances. Call createStoryInstances first.`);return}this._groupStoriesByCategory(e).forEach((e,t)=>{this._addCategoryToSidebar(t),e.forEach(e=>{this._addStoryToSidebar(e)})})}_clearSidebar(){let e=this._sidebar_list.get_first_child();for(;e;){let t=e.get_next_sibling();e.unparent(),e=t}}_groupStoriesByCategory(e){let t=new Map;return e.forEach(e=>{e.instances?.length&&e.instances.forEach(e=>{let[n]=e.meta.title.split(`/`);t.has(n)||t.set(n,[]),t.get(n).push(e)})}),t}_addCategoryToSidebar(e){let t=new r.ListBoxRow({selectable:!1}),n=new r.Label({label:e,halign:r.Align.START,margin_top:10,margin_bottom:4,margin_start:12,margin_end:12});n.add_css_class(`heading`),n.add_css_class(`dim-label`),t.set_child(n),this._sidebar_list.append(t)}_addStoryToSidebar(e){let t=e.meta.title.split(`/`),n=t.length>1?t[1]:e.meta.title,i=new r.ListBoxRow,a=new r.Label({label:n||`Unnamed Story`,halign:r.Align.START,margin_start:20,margin_top:6,margin_bottom:6});i.set_child(a),this._sidebar_list.append(i),i.storyWidget=e}_onStorySelected(e,t){if(!t)return;let n=t;n.storyWidget&&(this._showStory(n.storyWidget),this._main_split_view.get_collapsed()&&this._main_split_view.set_show_content(!0))}_showStory(e){this._preview_title.set_title(`${e.meta.title} - ${e.story}`),this._content_area.set_child(e),this._updateControlPanel(e)}_updateControlPanel(e){this._clearControlPanel();let t=e.meta.controls;Array.isArray(t)&&(t.forEach(t=>{if(!t?.name||!t?.type){console.warn(`Invalid control configuration:`,t);return}let n=this._createControlRow(e,t);n&&(this._control_panel.add(n),this._controlRows.push(n))}),this._activeStory&&this._activeStoryHandlerId&&this._activeStory.disconnect(this._activeStoryHandlerId),this._activeStory=e,this._activeStoryHandlerId=e.connect(`notify::args`,()=>{for(let t of this._controlRefreshers)t(e.args)}),this._show_controls_button.set_active(!0))}_clearControlPanel(){for(let e of this._controlRows)this._control_panel.remove(e);this._controlRows=[],this._controlRefreshers=[]}_createControlRow(e,t){let n=e.args[t.name];switch(t.type){case i.TEXT:return this._createTextRow(e,t,typeof n==`string`?n:``);case i.NUMBER:return this._createNumberRow(e,t,typeof n==`number`?n:t.min??0);case i.BOOLEAN:return this._createBooleanRow(e,t,typeof n==`boolean`?n:!1);case i.RANGE:return this._createRangeRow(e,t,typeof n==`number`?n:t.min??0);case i.SELECT:return this._createSelectRow(e,t,n??null);case i.COLOR:return this._createColorRow(e,t,typeof n==`string`?n:`#000000`);default:return console.warn(`Unsupported control type: ${t.type}`),null}}_writeArg(e,t,n){e.args={...e.args,[t]:n}}_createTextRow(t,n,r){let i=new e.EntryRow({title:n.label||n.name});return i.set_text(r),n.description&&i.set_tooltip_text(n.description),i.connect(`changed`,()=>this._writeArg(t,n.name,i.get_text())),this._controlRefreshers.push(e=>{let t=typeof e[n.name]==`string`?e[n.name]:``;i.get_text()!==t&&i.set_text(t)}),i}_createNumberRow(t,n,r){let i=e.SpinRow.new_with_range(n.min??0,n.max??100,n.step??1);return i.set_title(n.label||n.name),n.description&&i.set_subtitle(n.description),i.set_value(r),i.connect(`changed`,()=>this._writeArg(t,n.name,i.get_value())),this._controlRefreshers.push(e=>{let t=typeof e[n.name]==`number`?e[n.name]:0;i.get_value()!==t&&i.set_value(t)}),i}_createBooleanRow(t,n,r){let i=new e.SwitchRow({title:n.label||n.name,subtitle:n.description??``,active:r});return i.connect(`notify::active`,()=>this._writeArg(t,n.name,i.get_active())),this._controlRefreshers.push(e=>{let t=!!e[n.name];i.get_active()!==t&&i.set_active(t)}),i}_createRangeRow(e,t,n){let i=t.min??0,a=t.max??100,o=t.step??1,s=Number.isInteger(o)&&Number.isInteger(n),c=new r.Adjustment({lower:i,upper:a,step_increment:o,value:n});c.step_increment=o;let l=new r.ListBoxRow({selectable:!1,activatable:!1});l.add_css_class(`story-range-row`);let u=new r.Box({orientation:r.Orientation.VERTICAL,spacing:6,margin_top:12,margin_bottom:12,margin_start:12,margin_end:12}),d=new r.Box({orientation:r.Orientation.HORIZONTAL,spacing:12}),f=new r.Label({label:t.label||t.name,halign:r.Align.START,hexpand:!0,ellipsize:3});f.add_css_class(`heading`);let p=new r.Label({label:this._formatRangeValue(n,s),halign:r.Align.END});if(p.add_css_class(`numeric`),p.add_css_class(`dim-label`),d.append(f),d.append(p),u.append(d),t.description){let e=new r.Label({label:t.description,halign:r.Align.START,xalign:0,wrap:!0,max_width_chars:32});e.add_css_class(`caption`),e.add_css_class(`dim-label`),u.append(e)}let m=new r.Scale({orientation:r.Orientation.HORIZONTAL,adjustment:c,draw_value:!1,hexpand:!0});return m.connect(`value-changed`,()=>{let n=m.get_value();if(s){let e=Math.round(n);if(e!==n){m.set_value(e);return}n=e}p.set_label(this._formatRangeValue(n,s)),this._writeArg(e,t.name,n)}),u.append(m),l.set_child(u),this._controlRefreshers.push(e=>{let r=typeof e[t.name]==`number`?e[t.name]:n;m.get_value()!==r&&(m.set_value(r),p.set_label(this._formatRangeValue(r,s)))}),l}_formatRangeValue(e,t){return t?String(Math.round(e)):e.toFixed(2)}_createSelectRow(t,n,i){let a=n.options;if(!a?.length)return console.warn(`SELECT control "${n.name}" has no options`),null;let o=r.StringList.new(a.map(e=>e.label)),s=new e.ComboRow({title:n.label||n.name,subtitle:n.description??``,model:o}),c=a.findIndex(e=>e.value===i);return c>=0&&s.set_selected(c),s.connect(`notify::selected`,()=>{let e=s.get_selected();e>=0&&e<a.length&&this._writeArg(t,n.name,a[e].value)}),this._controlRefreshers.push(e=>{let t=e[n.name],r=a.findIndex(e=>e.value===t);r>=0&&s.get_selected()!==r&&s.set_selected(r)}),s}_createColorRow(n,i,a){let o=new e.ActionRow({title:i.label||i.name,subtitle:i.description??``}),s=new r.ColorDialogButton({dialog:new r.ColorDialog({title:i.label||i.name}),valign:r.Align.CENTER}),c=new t.RGBA;return c.parse(a)&&s.set_rgba(c),s.connect(`notify::rgba`,()=>{this._writeArg(n,i.name,this._rgbaToHex(s.get_rgba()))}),o.add_suffix(s),o.set_activatable_widget(s),o}_rgbaToHex(e){let channel=e=>Math.round(Math.max(0,Math.min(1,e))*255).toString(16).padStart(2,`0`);return`#${channel(e.red)}${channel(e.green)}${channel(e.blue)}`}};n.type_ensure(a.$gtype);export{a as StorybookWindow};
+import"./_virtual/_rolldown/runtime.js";import e from"@girs/adw-1";import t from"@girs/gdk-4.0";import n from"@girs/gobject-2.0";import r from"@girs/gtk-4.0";import{StorybookController as i,bindControl as a}from"@gjsify/storybook-core";function adwControlWidgetFactory(){return{text(t,n){let r=new e.EntryRow({title:t});n&&r.set_tooltip_text(n);let i=null;return r.connect(`changed`,()=>i?.(r.get_text())),{node:r,get:()=>r.get_text(),set:e=>r.set_text(e),onChange:e=>{i=e}}},boolean(t,n){let r=new e.SwitchRow({title:t,subtitle:n??``}),i=null;return r.connect(`notify::active`,()=>i?.(r.get_active())),{node:r,get:()=>r.get_active(),set:e=>r.set_active(e),onChange:e=>{i=e}}},number(t){let n=e.SpinRow.new_with_range(t.min??0,t.max??100,t.step??1);n.set_title(t.label||t.name),t.description&&n.set_subtitle(t.description);let r=null;return n.connect(`changed`,()=>r?.(n.get_value())),{node:n,get:()=>n.get_value(),set:e=>n.set_value(e),onChange:e=>{r=e}}},range(e){return buildRangeWidget(e)},select(e){return buildSelectWidget(e)},color(e,t){return buildColorWidget(e,t)}}}function buildRangeWidget(e){let t=e.min??0,n=e.max??100,i=e.step??1,a=typeof e.min==`number`?e.min:0,o=Number.isInteger(i)&&Number.isInteger(a),s=new r.Adjustment({lower:t,upper:n,step_increment:i,value:a});s.step_increment=i;let c=new r.ListBoxRow({selectable:!1,activatable:!1});c.add_css_class(`story-range-row`);let l=new r.Box({orientation:r.Orientation.VERTICAL,spacing:6,margin_top:12,margin_bottom:12,margin_start:12,margin_end:12}),u=new r.Box({orientation:r.Orientation.HORIZONTAL,spacing:12}),d=new r.Label({label:e.label||e.name,halign:r.Align.START,hexpand:!0,ellipsize:3});d.add_css_class(`heading`);let formatValue=e=>o?String(Math.round(e)):e.toFixed(2),f=new r.Label({label:formatValue(a),halign:r.Align.END});if(f.add_css_class(`numeric`),f.add_css_class(`dim-label`),u.append(d),u.append(f),l.append(u),e.description){let t=new r.Label({label:e.description,halign:r.Align.START,xalign:0,wrap:!0,max_width_chars:32});t.add_css_class(`caption`),t.add_css_class(`dim-label`),l.append(t)}let p=new r.Scale({orientation:r.Orientation.HORIZONTAL,adjustment:s,draw_value:!1,hexpand:!0}),m=null,h=!1;return p.connect(`value-changed`,()=>{if(h)return;let e=p.get_value();if(o){let t=Math.round(e);if(t!==e){p.set_value(t);return}e=t}f.set_label(formatValue(e)),m?.(e)}),l.append(p),c.set_child(l),{node:c,get:()=>p.get_value(),set:e=>{h=!0,p.set_value(e),h=!1,f.set_label(formatValue(e))},onChange:e=>{m=e}}}function buildSelectWidget(t){let n=t.options??[],i=r.StringList.new(n.map(e=>e.label)),a=new e.ComboRow({title:t.label||t.name,subtitle:t.description??``,model:i}),o=null;return a.connect(`notify::selected`,()=>o?.(a.get_selected())),{node:a,get:()=>a.get_selected(),set:e=>a.set_selected(e),onChange:e=>{o=e}}}function buildColorWidget(n,i){let a=new e.ActionRow({title:n,subtitle:i??``}),o=new r.ColorDialogButton({dialog:new r.ColorDialog({title:n}),valign:r.Align.CENTER});a.add_suffix(o),a.set_activatable_widget(o);let channel=e=>Math.round(Math.max(0,Math.min(1,e))*255).toString(16).padStart(2,`0`),rgbaToHex=e=>`#${channel(e.red)}${channel(e.green)}${channel(e.blue)}`,s=null,c=!1;return o.connect(`notify::rgba`,()=>{c||s?.(rgbaToHex(o.get_rgba()))}),{node:a,get:()=>rgbaToHex(o.get_rgba()),set:e=>{let n=new t.RGBA;n.parse(e)&&(c=!0,o.set_rgba(n),c=!1)},onChange:e=>{s=e}}}var o=class StorybookWindow extends e.ApplicationWindow{static{n.registerClass({GTypeName:`StorybookWindow`},StorybookWindow)}constructor(e){super(e),this._controlRows=[],this._rowByTitle=new Map,this._onSelect=null,this._suppressSelect=!1,this.set_default_size(1200,800),this.set_size_request(360,320),this.set_title(`Storybook`),this._buildUI(),this._controller=new i(this,e=>this._buildControls(e)),this._sidebar_list.connect(`row-selected`,this._onRowSelected.bind(this)),this._show_controls_button.connect(`toggled`,this._onToggleControls.bind(this)),this._controls_split_view.set_show_sidebar(!0)}_onRowSelected(e,t){if(this._suppressSelect||!t)return;let n=t;n.storyWidget&&this._onSelect?.(n.storyWidget)}get controller(){return this._controller}_buildControls(e){let t=e.meta.controls;if(!Array.isArray(t))return[];let n=adwControlWidgetFactory(),r=[];for(let i of t){if(!i?.name||!i?.type){console.warn(`Invalid control configuration:`,i);continue}let t=a(e,i,n);t&&r.push(t)}return r}_buildUI(){this._sidebar_list=new r.ListBox({selection_mode:r.SelectionMode.SINGLE}),this._sidebar_list.add_css_class(`navigation-sidebar`);let t=new r.ScrolledWindow({hexpand:!0,vexpand:!0,child:this._sidebar_list}),n=new e.HeaderBar({title_widget:new e.WindowTitle({title:`Stories`}),show_end_title_buttons:!1}),i=new e.ToolbarView({content:t,top_bar_style:e.ToolbarStyle.FLAT});i.add_top_bar(n);let a=new e.NavigationPage({title:`Stories`,tag:`stories`,child:i});this._content_area=new e.Bin({hexpand:!0,vexpand:!0});let o=new r.ScrolledWindow({hexpand:!0,vexpand:!0,child:this._content_area});this._control_panel=new e.PreferencesGroup({title:`Controls`});let s=new e.PreferencesPage;s.add(this._control_panel);let c=new r.ScrolledWindow({vexpand:!0,child:s});this._controls_split_view=new e.OverlaySplitView({show_sidebar:!0,sidebar_position:r.PackType.END,min_sidebar_width:280,max_sidebar_width:360,content:o,sidebar:c,css_classes:[`storybook-controls`]}),this._preview_title=new e.WindowTitle({title:`Preview`}),this._show_controls_button=new r.ToggleButton({icon_name:`sidebar-show-right-symbolic`,tooltip_text:`Toggle Controls`,active:!0});let l=new e.HeaderBar({title_widget:this._preview_title});l.pack_end(this._show_controls_button);let u=new e.ToolbarView({content:this._controls_split_view,top_bar_style:e.ToolbarStyle.FLAT});u.add_top_bar(l);let d=new e.NavigationPage({title:`Preview`,tag:`preview`,child:u});this._main_split_view=new e.NavigationSplitView({min_sidebar_width:220,max_sidebar_width:320,sidebar:a,content:d}),this.set_content(this._main_split_view);let f=e.BreakpointCondition.parse(`max-width: 720sp`);if(f){let t=new e.Breakpoint({condition:f});t.connect(`apply`,()=>{this._main_split_view.collapsed=!0,this._controls_split_view.collapsed=!0}),t.connect(`unapply`,()=>{this._main_split_view.collapsed=!1,this._controls_split_view.collapsed=!1}),this.add_breakpoint(t)}}_onToggleControls(e){this._controls_split_view.set_show_sidebar(e.get_active())}populateSidebar(e){this._controller.mount(e,!0)}renderSidebar(e,t){this._onSelect=t,this._suppressSelect=!0,this._clearSidebar(),this._rowByTitle.clear();for(let t of e){this._addCategoryToSidebar(t.category);for(let{instance:e,name:n}of t.stories)this._addStoryToSidebar(e,n)}this._suppressSelect=!1}markSelected(e){let t=this._rowByTitle.get(e);t&&this._sidebar_list.get_selected_row()!==t&&(this._suppressSelect=!0,this._sidebar_list.select_row(t),this._suppressSelect=!1)}setPreviewTitle(e){this._preview_title.set_title(e)}showPreview(e){this._content_area.set_child(e),this._main_split_view.get_collapsed()&&this._main_split_view.set_show_content(!0)}renderControls(e){this._clearControlPanel();for(let t of e){let e=t.view;this._control_panel.add(e),this._controlRows.push(e)}this._show_controls_button.set_active(!0)}_clearSidebar(){let e=this._sidebar_list.get_first_child();for(;e;){let t=e.get_next_sibling();e.unparent(),e=t}}_addCategoryToSidebar(e){let t=new r.ListBoxRow({selectable:!1}),n=new r.Label({label:e,halign:r.Align.START,margin_top:10,margin_bottom:4,margin_start:12,margin_end:12});n.add_css_class(`heading`),n.add_css_class(`dim-label`),t.set_child(n),this._sidebar_list.append(t)}_addStoryToSidebar(e,t){let n=new r.ListBoxRow,i=new r.Label({label:t||`Unnamed Story`,halign:r.Align.START,margin_start:20,margin_top:6,margin_bottom:6});n.set_child(i),this._sidebar_list.append(n),n.storyWidget=e,this._rowByTitle.set(e.meta.title,n)}_clearControlPanel(){for(let e of this._controlRows)this._control_panel.remove(e);this._controlRows=[]}get activeStory(){return this._controller.activeStory}openStoryByTitle(e){return this._controller.openStoryByTitle(e)}setActiveArg(e,t){return this._controller.setActiveArg(e,t)}};n.type_ensure(o.$gtype);export{o as StorybookWindow};

package/lib/types/application.d.ts

@@ -10,6 +10,8 @@ export interface StorybookOptions {
     stories: StoryModule[];
     /** Consumer's own widget stylesheet, layered on top of the built-in chrome CSS. */
     css?: string;
+    /** Force-enable the devtools control plane (otherwise gated on `GJSIFY_DEVTOOLS`). */
+    devtools?: boolean;
 }
 /**
  * Hosts the storybook: loads styles on startup, builds the window and populates
@@ -18,7 +20,6 @@ export interface StorybookOptions {
  */
 export declare class StorybookApplication extends Adw.Application {
     private _window;
-    private _registry;
     private _options;
     constructor(options: StorybookOptions);
     private _initStyles;

package/lib/types/devtools-extension.d.ts

@@ -0,0 +1,11 @@
+import type { DevtoolsExtension } from '@gjsify/devtools';
+import type { StorybookWindow } from './window.js';
+/**
+ * Build a {@link DevtoolsExtension} that exposes the storybook's story surface
+ * — list/open stories, read/set the active story's args — so an agent (via the
+ * MCP bridge) can drive and debug widgets in isolation. Wired by
+ * {@link StorybookApplication} when `GJSIFY_DEVTOOLS` is set.
+ *
+ * Delegates the method set to the window's {@link StorybookController}.
+ */
+export declare function storybookDevtoolsExtension(window: StorybookWindow): DevtoolsExtension;

package/lib/types/discover.d.ts

@@ -1,8 +1,8 @@
-import type { StoryModule as GtkStoryModule } from './story-widget.js';
+import type { StoryModule } from './story-widget.js';
 /**
  * Flatten a list of module namespaces (the `import * as m from './x.story.js'`
- * objects the `gjsify storybook` command generates) into the story modules
+ * objects the `gjsify storybook` command generates) into the GTK story modules
  * they export — regardless of the export name. Any exported value shaped like a
- * {@link StoryModule} (an object with a `stories` array) is collected.
+ * story module (an object with a `stories` array) is collected.
  */
-export declare function collectStoryModules(namespaces: Array<Record<string, unknown>>): GtkStoryModule[];
+export declare function collectStoryModules(namespaces: Array<Record<string, unknown>>): StoryModule[];

package/lib/types/index.d.ts

@@ -4,6 +4,7 @@ export type { StoryDecorator, StoryModule, StoryWidgetConstructor } from './stor
 export { StoryRegistryService } from './registry.js';
 export { installActionGroup, withActionGroup, type StoryAction } from './decorators.js';
 export { StorybookWindow } from './window.js';
+export { storybookDevtoolsExtension } from './devtools-extension.js';
 export { StorybookApplication, type StorybookOptions } from './application.js';
 export { runStorybook } from './run.js';
 export { collectStoryModules } from './discover.js';

package/lib/types/registry.d.ts

@@ -1,22 +1,11 @@
-import type { StoryModule } from './story-widget.js';
+import { StoryRegistry } from '@gjsify/storybook-core';
+import type { StoryWidget } from './story-widget.js';
+export { StoryRegistry } from '@gjsify/storybook-core';
 /**
- * Manages story-module registration and instantiation. Unlike the original
- * PixelRPG implementation there is no exported singleton — each
- * {@link runStorybook} run owns exactly one registry, which removes the
- * double-registration footgun.
+ * Manages story-module registration and instantiation for the GTK renderer.
+ * One registry per {@link runStorybook} run (no shared singleton). All behaviour
+ * — validation, defensive copies, decorator `reduceRight` composition — is the
+ * core {@link StoryRegistry}.
  */
-export declare class StoryRegistryService {
-    private modules;
-    /** Register a single story module. */
-    registerStory(storyModule: StoryModule): void;
-    /** Register multiple story modules (invalid ones are filtered out). */
-    registerStories(storyModules: StoryModule[]): void;
-    /** All registered story modules (a shallow copy). */
-    getStories(): StoryModule[];
-    /**
-     * Instantiate every registered story widget and prepare it for display.
-     * Call once GTK is ready.
-     */
-    createStoryInstances(): StoryModule[];
-    private instantiateStoriesForModule;
+export declare class StoryRegistryService extends StoryRegistry<StoryWidget> {
 }

package/lib/types/story-widget.d.ts

@@ -1,7 +1,7 @@
 import Adw from '@girs/adw-1';
 import GObject from '@girs/gobject-2.0';
 import Gtk from '@girs/gtk-4.0';
-import { type StoryArgs, type StoryMeta } from '@gjsify/stories';
+import { type StoryArgs, type StoryArgValue, type StoryMeta } from '@gjsify/stories';
 export declare namespace StoryWidget {
     interface ConstructorProps {
         meta: StoryMeta;
@@ -10,7 +10,8 @@ export declare namespace StoryWidget {
     }
 }
 /**
- * Base class for GJS story widgets.
+ * Base class for GJS story widgets — a thin GTK adapter over
+ * {@link StoryViewBase}.
  *
  * Provides default chrome — a centered `Adw.PreferencesPage` /
  * `Adw.PreferencesGroup` with title + description above a content slot — built
@@ -19,11 +20,7 @@ export declare namespace StoryWidget {
  * providing their own composite template (then {@link addContent} is a no-op).
  */
 export declare class StoryWidget extends Adw.Bin {
-    private _meta;
-    private _story;
-    private _args;
-    private _storyContent;
-    private _group;
+    private _core;
     constructor(params: StoryWidget.ConstructorProps, adwParams?: Partial<Adw.Bin.ConstructorProps>);
     /**
      * Build the constructor params from a story's metadata, deriving the initial
@@ -31,11 +28,13 @@ export declare class StoryWidget extends Adw.Bin {
      */
     static fromMeta(meta: StoryMeta, story: string): StoryWidget.ConstructorProps;
     get meta(): StoryMeta;
-    set meta(value: StoryMeta);
     get story(): string;
-    set story(value: string);
     get args(): StoryArgs;
     set args(value: StoryArgs);
+    /** Subscribe to args changes; returns an unsubscribe function. */
+    onArgsChanged(listener: (args: StoryArgs) => void): () => void;
+    /** Set a single arg — drives {@link updateArgs} and notifies listeners. */
+    setArg(name: string, value: StoryArgValue): void;
     /** Override in subclasses — build the preview. Runs in the registry init path. */
     initialize(): void;
     /** Override in subclasses — react to a control change. */
@@ -47,8 +46,6 @@ export declare class StoryWidget extends Adw.Bin {
      * installed its own composite template.
      */
     addContent(widget: Gtk.Widget): void;
-    private _installDefaultChrome;
-    private _refreshChromeText;
 }
 /** Wraps a story's content-build step (e.g. to install a shared action group). */
 export type StoryDecorator = (build: () => void, widget: StoryWidget) => void;

package/lib/types/story-widget.gjs.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/styles.d.ts

@@ -1 +1 @@
-export declare const STORYBOOK_CSS = "\n/* Range-control card in the controls sidebar \u2014 keeps the label + description\n   from being squashed into a single column when the sidebar is narrow. */\n.story-range-row {\n    padding: 0;\n}\n.story-range-row > box {\n    border-radius: 12px;\n}\n";
+export declare const STORYBOOK_CSS = "\n/* Range-control card in the controls sidebar \u2014 keeps the label + description\n   from being squashed into a single column when the sidebar is narrow. */\n.story-range-row {\n    padding: 0;\n}\n.story-range-row > box {\n    border-radius: 12px;\n}\n\n/* Controls panel shares the window (story) background; only the left\n   navigation sidebar keeps a distinct shade. The overlay-split-view sidebar is\n   otherwise drawn on the sidebar shade \u2014 flatten it onto the window colour. */\n.storybook-controls > .sidebar,\n.storybook-controls > .sidebar > * {\n    background-color: @window_bg_color;\n}\n\n/* Subtle dashed frame around the live preview so the widget's bounds stay\n   locatable even when it is transparent or in an empty state (e.g. a collapsed\n   bottom sheet, a status page, a bare button). @window_fg_color flips with the\n   theme (alpha(currentColor, \u2026) does not resolve in a Gtk.CssProvider). */\n.story-stage {\n    border: 1px dashed alpha(@window_fg_color, 0.28);\n    border-radius: 12px;\n    padding: 18px;\n}\n";

package/lib/types/window.d.ts

@@ -1,12 +1,15 @@
 import Adw from '@girs/adw-1';
-import type { StoryModule } from './story-widget.js';
+import type { StoryArgValue } from '@gjsify/stories';
+import { type CategoryGroup, type ControlRow, StorybookController, type StorybookView } from '@gjsify/storybook-core';
+import type { StoryModule, StoryWidget } from './story-widget.js';
 /**
  * Main window for the storybook. The sidebar lists story instances grouped by
  * the `Category/Name` title prefix; the preview pane holds the active
  * {@link StoryWidget} and an `Adw.PreferencesGroup` of controls drives its
- * `args` with two-way binding.
+ * `args` with two-way binding. Implements {@link StorybookView} so the shared
+ * {@link StorybookController} drives it.
  */
-export declare class StorybookWindow extends Adw.ApplicationWindow {
+export declare class StorybookWindow extends Adw.ApplicationWindow implements StorybookView<StoryWidget> {
     private _sidebar_list;
     private _content_area;
     private _control_panel;
@@ -15,30 +18,44 @@ export declare class StorybookWindow extends Adw.ApplicationWindow {
     private _controls_split_view;
     private _main_split_view;
     private _controlRows;
-    private _controlRefreshers;
-    private _activeStoryHandlerId;
-    private _activeStory;
+    private _rowByTitle;
+    private _controller;
+    private _onSelect;
+    private _suppressSelect;
     constructor(params: Partial<Adw.ApplicationWindow.ConstructorProps>);
+    private _onRowSelected;
+    /** The controller driving this window (exposed for the devtools extension). */
+    get controller(): StorybookController<StoryWidget>;
+    private _buildControls;
     private _buildUI;
     private _onToggleControls;
-    /** Populate the sidebar with story instances grouped by category. */
+    /**
+     * Populate the sidebar with story modules. Registers + instantiates them via
+     * the controller (which renders the sidebar through this view's
+     * {@link renderSidebar} seam) and opens the first story.
+     */
     populateSidebar(storyModules: StoryModule[]): void;
+    renderSidebar(groups: Array<CategoryGroup<StoryWidget>>, onSelect: (instance: StoryWidget) => void): void;
+    markSelected(title: string): void;
+    setPreviewTitle(title: string): void;
+    showPreview(instance: StoryWidget): void;
+    renderControls(rows: Array<ControlRow<unknown>>): void;
     private _clearSidebar;
-    private _groupStoriesByCategory;
     private _addCategoryToSidebar;
     private _addStoryToSidebar;
-    private _onStorySelected;
-    private _showStory;
-    private _updateControlPanel;
     private _clearControlPanel;
-    private _createControlRow;
-    private _writeArg;
-    private _createTextRow;
-    private _createNumberRow;
-    private _createBooleanRow;
-    private _createRangeRow;
-    private _formatRangeValue;
-    private _createSelectRow;
-    private _createColorRow;
-    private _rgbaToHex;
+    /** The currently-displayed story, or null. */
+    get activeStory(): StoryWidget | null;
+    /**
+     * Select + show a story by its full `Category/Name` title; the sidebar
+     * selection updates too, so the UI stays in sync. Returns false when no
+     * story with that title exists.
+     */
+    openStoryByTitle(title: string): boolean;
+    /**
+     * Set one arg on the active story — drives the same `args` path as the
+     * control panel, so the visible control rows refresh via the controller's
+     * args subscription. Returns false when no story is active.
+     */
+    setActiveArg(name: string, value: StoryArgValue): boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/storybook",
-    "version": "0.10.0",
+    "version": "0.12.0",
     "description": "Reusable GTK/Adwaita storybook for GJS — author *.story.ts and browse them in a generic component explorer",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -41,11 +41,13 @@
         "@girs/glib-2.0": "2.88.0-4.0.4",
         "@girs/gobject-2.0": "2.88.0-4.0.4",
         "@girs/gtk-4.0": "4.23.0-4.0.4",
-        "@gjsify/stories": "^0.10.0"
+        "@gjsify/devtools": "^0.12.0",
+        "@gjsify/stories": "^0.12.0",
+        "@gjsify/storybook-core": "^0.12.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.10.0",
-        "@gjsify/unit": "^0.10.0",
+        "@gjsify/cli": "^0.12.0",
+        "@gjsify/unit": "^0.12.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },