@gjsify/example-gtk-adwaita-storybook 0.53.0 → 0.55.0

package/src/layout/separator.story.ts

@@ -0,0 +1,53 @@
+// Gtk.Separator — the rule between two groups, and the .spacer gap.
+// original implementation.
+
+import Gtk from 'gi://Gtk?version=4.0';
+import GObject from 'gi://GObject?version=2.0';
+import { type StoryArgs, type StoryMeta, type StoryModule, StoryWidget } from '@gjsify/storybook';
+import { separatorMeta } from './separator.meta.js';
+
+/** Story: a Gtk.Separator between two labels, in the box direction that makes it visible. */
+export class SeparatorStory extends StoryWidget {
+    private _box: Gtk.Box | null = null;
+    private _separator: Gtk.Separator | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookSeparator' }, SeparatorStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(SeparatorStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...separatorMeta, component: Gtk.Separator.$gtype };
+    }
+
+    initialize(): void {
+        this._separator = new Gtk.Separator();
+        this._box = new Gtk.Box({ spacing: 12, halign: Gtk.Align.CENTER });
+        this._box.append(new Gtk.Label({ label: 'Above' }));
+        this._box.append(this._separator);
+        this._box.append(new Gtk.Label({ label: 'Below' }));
+        this._apply();
+        this.addContent(this._box);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._box || !this._separator) return;
+        const vertical = this.args.orientation === 'vertical';
+        this._separator.orientation = vertical ? Gtk.Orientation.VERTICAL : Gtk.Orientation.HORIZONTAL;
+        // A rule runs ACROSS its box, so the box runs the other way.
+        this._box.orientation = vertical ? Gtk.Orientation.HORIZONTAL : Gtk.Orientation.VERTICAL;
+        if (this.args.spacer as boolean) this._separator.add_css_class('spacer');
+        else this._separator.remove_css_class('spacer');
+    }
+}
+
+GObject.type_ensure(SeparatorStory.$gtype);
+
+export const SeparatorStories: StoryModule = { stories: [SeparatorStory] };

package/src/layout/viewport.meta.ts

@@ -0,0 +1,19 @@
+// Shared, renderer-agnostic metadata for the Viewport story. Imported by the GTK renderer
+// (layout/viewport.story.ts) and the browser renderer (browser/layout/viewport.web.ts), so
+// both expose identical controls.
+
+// THE CONTROL NAME IS A CAMEL-CASE ARG NAME, not the GIR spelling: the control panel's
+// reader takes `name` as an identifier (`scripts/check-storybook-control-parity.mjs` reads
+// `\bname:\s*'([A-Za-z0-9_]+)'`), and each renderer writes it onto the property whose own
+// name it is — `scroll-to-focus` here.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const viewportMeta: StoryMeta = {
+    title: 'Layout/Viewport',
+    description:
+        'Gtk.Viewport — scrollability for a widget that has none of its own. It has one ' +
+        'property, scroll-to-focus: whether a widget that takes the focus is scrolled into ' +
+        'view. It is also what a Gtk.ScrolledWindow puts its child in.',
+    controls: [{ name: 'scrollToFocus', label: 'Scroll to focus', type: ControlType.BOOLEAN, defaultValue: true }],
+};

package/src/layout/viewport.story.ts

@@ -0,0 +1,53 @@
+// Gtk.Viewport — a column in a window that clips it, with the focus behaviour bound to args.
+// original implementation.
+
+import Gtk from 'gi://Gtk?version=4.0';
+import GObject from 'gi://GObject?version=2.0';
+import { type StoryArgs, type StoryMeta, type StoryModule, StoryWidget } from '@gjsify/storybook';
+import { viewportMeta } from './viewport.meta.js';
+
+/** Story: a Gtk.Viewport over a column of labels and a focusable button at its end. */
+export class ViewportStory extends StoryWidget {
+    private _viewport: Gtk.Viewport | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookViewport' }, ViewportStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(ViewportStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...viewportMeta, component: Gtk.Viewport.$gtype };
+    }
+
+    initialize(): void {
+        const box = new Gtk.Box({ orientation: Gtk.Orientation.VERTICAL, spacing: 8 });
+        for (let i = 1; i <= 16; i++) {
+            box.append(new Gtk.Label({ label: `Row ${i}` }));
+        }
+        // The one widget whose focus a viewport acts on, so the property has something to
+        // reveal: with it off, tabbing to the button leaves it below the edge.
+        box.append(new Gtk.Button({ label: 'Focus me', halign: Gtk.Align.START }));
+        this._viewport = new Gtk.Viewport({
+            child: box,
+            halign: Gtk.Align.CENTER,
+        });
+        this._apply();
+        this.addContent(this._viewport);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._viewport) return;
+        this._viewport.set_scroll_to_focus(this.args.scrollToFocus as boolean);
+    }
+}
+
+GObject.type_ensure(ViewportStory.$gtype);
+
+export const ViewportStories: StoryModule = { stories: [ViewportStory] };

package/src/layout/window.meta.ts

@@ -0,0 +1,13 @@
+// Shared, renderer-agnostic metadata for the Window story.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const windowMeta: StoryMeta = {
+    title: 'Layout/Window',
+    description:
+        'Adw.Window — a freeform window with no titlebar area. Use Adw.ToolbarView with Adw.HeaderBar for the top chrome.',
+    controls: [
+        { name: 'title', label: 'Title', type: ControlType.TEXT, defaultValue: 'Text Editor' },
+        { name: 'subtitle', label: 'Subtitle', type: ControlType.TEXT, defaultValue: 'notes.md' },
+    ],
+};

package/src/layout/window.story.ts

@@ -0,0 +1,66 @@
+// Adw.Window — a freeform window with a header bar and content.
+// original implementation.
+
+import Adw from 'gi://Adw?version=1';
+import Gtk from 'gi://Gtk?version=4.0';
+import GObject from 'gi://GObject?version=2.0';
+import { type StoryArgs, type StoryMeta, type StoryModule, StoryWidget } from '@gjsify/storybook';
+import { windowMeta } from './window.meta.js';
+
+/** Story: Adw.Window with a header bar and status page content. */
+export class WindowStory extends StoryWidget {
+    private _window: Adw.Window | null = null;
+    private _title: Adw.WindowTitle | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookWindow' }, WindowStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(WindowStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...windowMeta, component: Adw.Window.$gtype };
+    }
+
+    initialize(): void {
+        this._title = new Adw.WindowTitle({
+            title: this.args.title as string,
+            subtitle: this.args.subtitle as string,
+        });
+
+        const headerBar = new Adw.HeaderBar({ titleWidget: this._title, widthRequest: 460 });
+
+        const backButton = new Gtk.Button({ iconName: 'go-previous-symbolic' });
+        backButton.add_css_class('flat');
+        headerBar.pack_start(backButton);
+
+        const menuButton = new Gtk.MenuButton({ iconName: 'open-menu-symbolic' });
+        menuButton.add_css_class('flat');
+        headerBar.pack_end(menuButton);
+
+        const toolbarView = new Adw.ToolbarView();
+        toolbarView.add_top_bar(headerBar);
+
+        const statusPage = new Adw.StatusPage({
+            title: 'Your Library',
+            description: 'Content sits between the toolbars and scrolls independently of them.',
+        });
+        toolbarView.content = statusPage;
+
+        this._window = new Adw.Window({ content: toolbarView });
+
+        this.addContent(this._window);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        if (!this._title) return;
+        this._title.title = this.args.title as string;
+        this._title.subtitle = this.args.subtitle as string;
+    }
+}
+
+GObject.type_ensure(WindowStory.$gtype);
+
+export const WindowStories: StoryModule = { stories: [WindowStory] };

package/src/media/image.meta.ts

@@ -0,0 +1,24 @@
+// Shared, renderer-agnostic metadata for the Image story. Imported by the GTK
+// renderer (image.story.ts) and the browser renderer (browser/media/image.web.ts),
+// so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const imageMeta: StoryMeta = {
+    title: 'Media/Image',
+    description:
+        'Gtk.Image — a symbolic icon, drawn as a CSS-masked box in the surrounding text colour. It takes a ' +
+        'NAME, not a file: a name the icon theme cannot resolve draws the missing-image glyph, which is exactly ' +
+        'what GTK draws for it. That is why <gtk-picture> is a separate widget — an icon sized by the theme and ' +
+        'an image fitted to a box are two different jobs.',
+    controls: [
+        {
+            name: 'iconName',
+            label: 'Icon name',
+            type: ControlType.TEXT,
+            defaultValue: 'avatar-default-symbolic',
+        },
+        { name: 'size', label: 'Size (px)', type: ControlType.RANGE, min: 16, max: 96, step: 8, defaultValue: 48 },
+        { name: 'disabled', label: 'Disabled', type: ControlType.BOOLEAN, defaultValue: false },
+    ],
+};

package/src/media/image.story.ts

@@ -0,0 +1,48 @@
+// Gtk.Image — the symbolic icon node, sized by the reader.
+// original implementation.
+
+import Gtk from 'gi://Gtk?version=4.0';
+import GObject from 'gi://GObject?version=2.0';
+import { type StoryArgs, type StoryMeta, type StoryModule, StoryWidget } from '@gjsify/storybook';
+import { imageMeta } from './image.meta.js';
+
+/** Story: one Gtk.Image at the reader's size, with the name as the control. */
+export class ImageStory extends StoryWidget {
+    private _image: Gtk.Image | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookImage' }, ImageStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(ImageStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...imageMeta, component: Gtk.Image.$gtype };
+    }
+
+    initialize(): void {
+        this._image = new Gtk.Image({ halign: Gtk.Align.CENTER, valign: Gtk.Align.CENTER });
+        this._apply();
+        this.addContent(this._image);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._image) return;
+        // `icon_size` is GTK's own ICON_SIZE enum, and a widget's measurement is made from the
+        // minimum AND the natural size of that enum (gtkspinner.c:110-123 is the same shape),
+        // so the size request is what actually grows the box.
+        this._image.icon_size = this.args.size as number as Gtk.IconSize;
+        this._image.icon_name = this.args.iconName as string;
+        this._image.sensitive = !(this.args.disabled as boolean);
+    }
+}
+
+GObject.type_ensure(ImageStory.$gtype);
+
+export const ImageStories: StoryModule = { stories: [ImageStory] };

package/src/media/inscription.meta.ts

@@ -0,0 +1,45 @@
+// Shared, renderer-agnostic metadata for the Inscription story. Imported by the GTK
+// renderer (inscription.story.ts) and the browser renderer
+// (browser/media/inscription.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const inscriptionMeta: StoryMeta = {
+    title: 'Media/Inscription',
+    description:
+        'Gtk.Inscription — text laid out to a size in CHARACTERS and LINES rather than to a size in pixels. ' +
+        'It is the widget for text whose extent should be the same everywhere, so it never measures its own ' +
+        'content: min-chars/nat-chars and min-lines/nat-lines ARE its size request.',
+    controls: [
+        { name: 'text', label: 'Text', type: ControlType.TEXT, defaultValue: 'Inscription' },
+        { name: 'minChars', label: 'Min chars', type: ControlType.RANGE, min: 0, max: 40, step: 1, defaultValue: 3 },
+        { name: 'natChars', label: 'Nat chars', type: ControlType.RANGE, min: 0, max: 40, step: 1, defaultValue: 0 },
+        { name: 'minLines', label: 'Min lines', type: ControlType.RANGE, min: 0, max: 6, step: 1, defaultValue: 1 },
+        { name: 'natLines', label: 'Nat lines', type: ControlType.RANGE, min: 0, max: 6, step: 1, defaultValue: 0 },
+        {
+            name: 'wrapMode',
+            label: 'Wrap mode',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Word', value: 'word' },
+                { label: 'Char', value: 'char' },
+                { label: 'Word-char (default)', value: 'word-char' },
+            ],
+            defaultValue: 'word-char',
+        },
+        {
+            name: 'textOverflow',
+            label: 'Text overflow',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Clip (default)', value: 'clip' },
+                { label: 'Ellipsize start', value: 'ellipsize-start' },
+                { label: 'Ellipsize middle', value: 'ellipsize-middle' },
+                { label: 'Ellipsize end', value: 'ellipsize-end' },
+            ],
+            defaultValue: 'clip',
+        },
+        { name: 'xalign', label: 'X align', type: ControlType.RANGE, min: 0, max: 1, step: 0.05, defaultValue: 0 },
+        { name: 'yalign', label: 'Y align', type: ControlType.RANGE, min: 0, max: 1, step: 0.05, defaultValue: 0.5 },
+    ],
+};

package/src/media/inscription.story.ts

@@ -0,0 +1,64 @@
+// Gtk.Inscription — text held to a size in characters and lines.
+// original implementation.
+
+import Gtk from 'gi://Gtk?version=4.0';
+import GObject from 'gi://GObject?version=2.0';
+import Pango from 'gi://Pango?version=1.0';
+import { type StoryArgs, type StoryMeta, type StoryModule, StoryWidget } from '@gjsify/storybook';
+import { inscriptionMeta } from './inscription.meta.js';
+
+/** Story: a Gtk.Inscription inside a fixed frame, so its counts are the only thing that moves. */
+export class InscriptionStory extends StoryWidget {
+    private _inscription: Gtk.Inscription | null = null;
+    private _frame: Gtk.Frame | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookInscription' }, InscriptionStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(InscriptionStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...inscriptionMeta, component: Gtk.Inscription.$gtype };
+    }
+
+    initialize(): void {
+        // The widget's CSS name is `label` (gtkinscription.c:780), so a Gtk.Frame around it
+        // gives the fixed box the counts are supposed to show off — without a frame the
+        // inscription shrinks to its minimum every time and the nat counts do nothing.
+        this._inscription = new Gtk.Inscription();
+        this._frame = new Gtk.Frame({ child: this._inscription, halign: Gtk.Align.CENTER });
+        this._apply();
+        this.addContent(this._frame);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._inscription || !this._frame) return;
+        // The ORDER is the measure: `nat_chars` only ever WIDENS a widget, and the natural is
+        // `MAX (min_chars, nat_chars)` (gtkinscription.c:348) — so a `min_chars` written
+        // after a large `nat_chars` still leaves the natural at the larger of the two. Both
+        // counts go before the text for the same reason the level bar's endpoints go before
+        // its value.
+        this._inscription.min_chars = this.args.minChars as number;
+        this._inscription.nat_chars = this.args.natChars as number;
+        this._inscription.min_lines = this.args.minLines as number;
+        this._inscription.nat_lines = this.args.natLines as number;
+        this._inscription.text = this.args.text as string;
+        this._inscription.wrap_mode = this.args.wrapMode as Pango.WrapMode;
+        this._inscription.text_overflow = this.args.textOverflow as Gtk.InscriptionOverflow;
+        this._inscription.xalign = this.args.xalign as number;
+        this._inscription.yalign = this.args.yalign as number;
+        this._frame.width_request = 320;
+        this._frame.height_request = 160;
+    }
+}
+
+GObject.type_ensure(InscriptionStory.$gtype);
+
+export const InscriptionStories: StoryModule = { stories: [InscriptionStory] };

package/src/media/media-controls.meta.ts

@@ -0,0 +1,30 @@
+// Shared, renderer-agnostic metadata for the Media Controls story. Imported by the GTK
+// renderer (media-controls.story.ts) and the browser renderer
+// (browser/media/media-controls.web.ts), so both expose identical controls.
+//
+// The NAME is `media-controls` and not `controls`: the storybook keys every meta on its
+// file name, and `bareName('Gtk.MediaControls')` in
+// `scripts/check-website-adwaita-gallery.mjs` derives the same spelling — so the block on
+// /gjsify/gtk/media/ is found from this file without a TITLED_AFTER entry.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+// ONE control, and the omission is the decision. `sensitive` is the whole of the widget's
+// API beyond its one object property — `gtk_media_controls_set_sensitive` — and it is what
+// both renderings bind.
+//
+// `volume` used to sit here beside it and does not, because it would have moved on the
+// browser and done NOTHING on GTK: `volume_adjustment` is private to the template
+// (`ui/gtkmediacontrols.ui`) and `Gtk.MediaControls` exposes no volume setter at all. One
+// meta drives three panels, so a control one of them cannot honour is precisely the shape
+// `check-storybook-control-parity.mjs` exists to refuse. The browser element's `volume`
+// property is real and its own, and the doc says so.
+export const mediaControlsMeta: StoryMeta = {
+    title: 'Media/Media Controls',
+    description:
+        'Gtk.MediaControls — the transport bar: play, position, duration, volume. It owns no playback at all ' +
+        '(its one property is an object, `media-stream`), and the bar is INSENSITIVE until a stream is ' +
+        'attached. Note which label shows what: the position label shows the elapsed time and the one beside ' +
+        'it shows what REMAINS, negatively.',
+    controls: [{ name: 'sensitive', label: 'Sensitive', type: ControlType.BOOLEAN, defaultValue: true }],
+};

package/src/media/media-controls.story.ts

@@ -0,0 +1,58 @@
+// Gtk.MediaControls — the transport bar, shown with and without a stream.
+// original implementation.
+
+import Gtk from 'gi://Gtk?version=4.0';
+import GObject from 'gi://GObject?version=2.0';
+import { type StoryArgs, type StoryMeta, type StoryModule, StoryWidget } from '@gjsify/storybook';
+import { mediaControlsMeta } from './media-controls.meta.js';
+
+/** Story: a Gtk.MediaControls inside a `.osd .bottom` frame, as ui/gtkvideo.ui dresses it. */
+export class MediaControlsStory extends StoryWidget {
+    private _controls: Gtk.MediaControls | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookMediaControls' }, MediaControlsStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(MediaControlsStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...mediaControlsMeta, component: Gtk.MediaControls.$gtype };
+    }
+
+    initialize(): void {
+        this._controls = new Gtk.MediaControls();
+        // The `.osd` and `.bottom` classes are what `ui/gtkvideo.ui` puts on the controls
+        // revealer's child, and libadwaita has rules for exactly these (the `%osd` surface
+        // and the 12px standalone-OSD-toolbar padding). The story wears them so the bar is
+        // drawn as the video draws it rather than as a bare row of controls.
+        this._controls.add_css_class('osd');
+        this._controls.add_css_class('bottom');
+        this._apply();
+        this.addContent(this._controls);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._controls) return;
+        // `sensitive` is the bar's WHOLE state, and the template ships it at 0
+        // (ui/gtkmediacontrols.ui) — `gtk_media_controls_new()` gives a bar you cannot press.
+        // The control flips it so a reader can see both halves of the widget's life.
+        this._controls.sensitive = this.args.sensitive as boolean;
+        // There is no `volume` line here and there cannot be: `Gtk.MediaControls` exposes no
+        // volume setter, because `volume_adjustment` is private to the template
+        // (`ui/gtkmediacontrols.ui`) and the button reads it directly. That is why the shared
+        // meta declares no `volume` control either — one meta drives three panels, and a
+        // control the browser alone could honour is what
+        // `check-storybook-control-parity.mjs` refuses.
+    }
+}
+
+GObject.type_ensure(MediaControlsStory.$gtype);
+
+export const MediaControlsStories: StoryModule = { stories: [MediaControlsStory] };

package/src/media/picture.meta.ts

@@ -0,0 +1,42 @@
+// Shared, renderer-agnostic metadata for the Picture story. Imported by the GTK
+// renderer (picture.story.ts) and the browser renderer (browser/media/picture.web.ts),
+// so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const pictureMeta: StoryMeta = {
+    title: 'Media/Picture',
+    description:
+        'Gtk.Picture — an image fitted to the box it is given, not sized by itself. `content-fit` picks one ' +
+        'of the four fit modes (contain, cover, fill, scale-down), `can-shrink` decides whether it may be ' +
+        'smaller than its content, and `alternative-text` is what a screen reader hears.',
+    controls: [
+        {
+            name: 'contentFit',
+            label: 'Content fit',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Contain', value: 'contain' },
+                { label: 'Cover', value: 'cover' },
+                { label: 'Fill', value: 'fill' },
+                { label: 'Scale down', value: 'scale-down' },
+            ],
+            defaultValue: 'contain',
+        },
+        { name: 'canShrink', label: 'Can shrink', type: ControlType.BOOLEAN, defaultValue: true },
+        {
+            name: 'alternativeText',
+            label: 'Alternative text',
+            type: ControlType.TEXT,
+            defaultValue: 'A tangerine',
+        },
+        { name: 'isolateContents', label: 'Isolate contents', type: ControlType.BOOLEAN, defaultValue: true },
+        {
+            name: 'keepAspectRatio',
+            label: 'Keep aspect ratio (deprecated)',
+            type: ControlType.BOOLEAN,
+            defaultValue: true,
+        },
+        { name: 'width', label: 'Width (px)', type: ControlType.RANGE, min: 64, max: 320, step: 16, defaultValue: 240 },
+    ],
+};

package/src/media/picture.story.ts

@@ -0,0 +1,81 @@
+// Gtk.Picture — an image fitted to the box, with the fit mode as the control.
+// original implementation.
+
+import Gtk from 'gi://Gtk?version=4.0';
+import Gdk from 'gi://Gdk?version=4.0';
+import GLib from 'gi://GLib?version=2.0';
+import GObject from 'gi://GObject?version=2.0';
+import { type StoryArgs, type StoryMeta, type StoryModule, StoryWidget } from '@gjsify/storybook';
+import { pictureMeta } from './picture.meta.js';
+
+/** The story's paintable: a `Gdk.MemoryTexture` of two bands, so `contain` and `cover` differ. */
+function makePaintable(): Gdk.Paintable {
+    const width = 320;
+    const height = 180;
+    const stride = width * 4;
+    const bytes = new Uint8Array(stride * height);
+    for (let y = 0; y < height; y++) {
+        // A horizontal split, so an axis-preserving fit and an axis-breaking one are
+        // distinguishable at a glance — which is the whole point of a `content-fit` demo.
+        const band = y < height / 2 ? 0x30 : 0x90;
+        for (let x = 0; x < width; x++) {
+            const offset = y * stride + x * 4;
+            bytes[offset] = band;
+            bytes[offset + 1] = x < width / 2 ? 0x40 : 0xc0;
+            bytes[offset + 2] = 0xa0;
+            bytes[offset + 3] = 0xff;
+        }
+    }
+    return Gdk.MemoryTexture.new(width, height, Gdk.MemoryFormat.R8G8B8A8, GLib.Bytes.new(bytes), stride);
+}
+
+/** Story: a Gtk.Picture in a deliberately non-square box, so every fit mode is visible. */
+export class PictureStory extends StoryWidget {
+    private _picture: Gtk.Picture | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookPicture' }, PictureStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(PictureStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...pictureMeta, component: Gtk.Picture.$gtype };
+    }
+
+    initialize(): void {
+        this._picture = new Gtk.Picture({
+            paintable: makePaintable(),
+            halign: Gtk.Align.CENTER,
+            valign: Gtk.Align.CENTER,
+        });
+        this._apply();
+        this.addContent(this._picture);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._picture) return;
+        const width = this.args.width as number;
+        // A 16:9 box round a 16:9 paintable, so `contain` fills it and `cover` does too —
+        // which would hide the difference. The box is 3:2 so `cover` crops top and bottom.
+        this._picture.set_size_request(width, Math.round((width * 2) / 3));
+        // The ORDER is the C's: `keep_aspect_ratio` is a MAPPING onto `content_fit`
+        // (gtkpicture.c:1017-1021), so writing it after `content_fit` would overwrite the
+        // control the reader just moved. It goes FIRST, and only when it is on.
+        if (this.args.keepAspectRatio as boolean) this._picture.keep_aspect_ratio = true;
+        this._picture.content_fit = this.args.contentFit as Gtk.ContentFit;
+        this._picture.can_shrink = this.args.canShrink as boolean;
+        this._picture.alternative_text = this.args.alternativeText as string;
+        this._picture.isolate_contents = this.args.isolateContents as boolean;
+    }
+}
+
+GObject.type_ensure(PictureStory.$gtype);
+
+export const PictureStories: StoryModule = { stories: [PictureStory] };

package/src/media/video.meta.ts

@@ -0,0 +1,32 @@
+// Shared, renderer-agnostic metadata for the Video story. Imported by the GTK
+// renderer (video.story.ts) and the browser renderer (browser/media/video.web.ts),
+// so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const videoMeta: StoryMeta = {
+    title: 'Media/Video',
+    description:
+        'Gtk.Video — a play surface with an overlay icon and a controls bar that hides itself three seconds ' +
+        'after you stop moving the pointer. The overlay icon is a four-way choice — no stream, error, ended, ' +
+        'or ready — and it is only VISIBLE while the video is stopped; there is no pause glyph over the frames.',
+    controls: [
+        { name: 'autoplay', label: 'Autoplay', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'loop', label: 'Loop', type: ControlType.BOOLEAN, defaultValue: true },
+        {
+            name: 'graphicsOffload',
+            label: 'Graphics offload',
+            type: ControlType.BOOLEAN,
+            defaultValue: false,
+        },
+        {
+            name: 'width',
+            label: 'Width (px)',
+            type: ControlType.RANGE,
+            min: 160,
+            max: 480,
+            step: 40,
+            defaultValue: 320,
+        },
+    ],
+};