@iyulab/modern-app 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.3.4 (2026-04-01)
+
+### Features
+- Progress bar now fades in/out with CSS transition on route begin/done
+- Progress bar shows error state (red) on `route-error` and auto-dismisses
+
+### Documentation
+- Added `docs/` topic guides and `skills/modern-app/` agent skill package
+- Rewrote `README.md` with accurate API and links to docs/skills
+
+## 0.3.3 (2026-04-01)
+
+### Fixes
+- Fixed missing `u-` prefix in `customElement` registration for `SidebarButton`, `SidebarGroup`, `SidebarLink`, and `SidebarSection` — components were referenced as `u-sidebar-*` in the template but registered as `sidebar-*`, causing them not to render
+
 ## 0.3.2 (2026-04-01)
 
 ### Breaking Changes

package/README.md

@@ -1,8 +1,6 @@
-# Modern App
+# @iyulab/modern-app
 
-A modern web application framework by iyulab, built on React and Lit Element.
-
-For complete examples and documentation, visit our demo site: [https://modern-app.iyulab.com](https://modern-app.iyulab.com)
+A client-side SPA framework built on [Lit Element](https://lit.dev/) by iyulab. It bundles routing, a responsive sidebar layout, theme management, toast notifications, and i18n into a single `app` singleton.
 
 ## Installation
 
@@ -10,167 +8,119 @@ For complete examples and documentation, visit our demo site: [https://modern-ap
 npm install @iyulab/modern-app
 ```
 
-## Architecture
-
-`@iyulab/modern-app` is a **client-side SPA framework** built on Lit Element. It is designed for:
-
-✅ **Suitable for:**
-- Single Page Applications (SPA)
-- Admin dashboards and internal tools
-- Progressive Web Apps (PWA)
-- Projects where SEO is not a primary concern
-
-❌ **Not suitable for:**
-- Server-Side Rendering (SSR) frameworks (Next.js, Nuxt, SvelteKit, etc.)
-- Static Site Generation (SSG)
-- SEO-critical public-facing pages
-- Projects requiring initial HTML content for search engines
+## When to use it
 
-This is by design — Lit components render on the client side. If you need SSR capabilities, consider using Lit's experimental SSR support separately or choose a framework designed for SSR from the start.
+| ✅ Good fit | ❌ Not a good fit |
+|-------------|-----------------|
+| Single Page Applications (SPA) | SSR frameworks (Next.js, Nuxt, SvelteKit) |
+| Admin dashboards and internal tools | Static Site Generation (SSG) |
+| Progressive Web Apps (PWA) | SEO-critical public-facing pages |
 
 ## Quick Start
 
 ```typescript
 import { app } from '@iyulab/modern-app';
+import { html } from 'lit';
 
 await app.load({
   basepath: '/',
   layout: {
     type: 'sidebar',
-    // ...layout configuration
+    logo: '/assets/logo.svg',
+    title: 'My App',
+    main: [
+      { type: 'link', icon: 'home',  label: 'Home',  href: '/' },
+      { type: 'link', icon: 'users', label: 'Users', href: '/users' },
+    ],
   },
   routes: [
-    { index: true, render: () => html`<home-page></home-page>` },
-    { path: 'about', render: () => html`<about-page></about-page>` },
+    { index: true,       render: () => html`<home-page></home-page>` },
+    { path: 'users',     render: () => html`<users-page></users-page>` },
+    { path: 'users/:id', render: (ctx) => html`<user-detail .userId=${ctx.params.id}></user-detail>` },
   ],
+  fallback: {
+    render: (ctx) => html`<error-page .error=${ctx.error}></error-page>`,
+  },
+  theme: { default: 'system' },
 });
 ```
 
-## API Reference
+## Skills Usage
 
-### Navigation
+AI agent skills for this package are located in `skills/modern-app/`. Install them with `npx skills`:
 
-```typescript
-// Navigate to a path
-app.navigate('/path');
-
-// Access router instance
-app.router?.go('/path');
-app.router?.basepath;   // Get base path
-app.router?.routes;     // Get registered routes
-app.router?.context;    // Get current route context
+**From GitHub:**
+```bash
+npx skills add iyulab/node-modern-app
 ```
 
-### Theme Management
-
-```typescript
-// Get current theme
-app.theme.get();  // Returns: 'system' | 'light' | 'dark' | undefined
-
-// Set theme
-app.theme.set('dark');   // 'system' | 'light' | 'dark'
-
-// Check initialization status
-app.theme.isInitialized;
+**From local `node_modules`:**
+```bash
+npx skills add ./node_modules/@iyulab/modern-app
 ```
 
-### Notifications
-
-```typescript
-// Display notifications (returns Promise<void>)
-await app.notice('Notice message');
-await app.info('Info message');
-await app.success('Success message');
-await app.warning('Warning message');
-await app.error('Error message');
-
-// With options
-await app.success('Saved!', {
-  title: 'Success',
-  duration: 5000,  // milliseconds (default: 3000)
-  position: 'top-right'  // 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
-});
-```
+## Core API
 
-### Localization
+### Navigation
 
 ```typescript
-// Access i18next instance
-app.localizer;  // i18next instance
-
-// Usage with lit-i18n
-import { translate } from 'lit-i18n';
-html`<p>${translate('namespace::key')}</p>`;
+app.navigate('/users/42');     // push a route
+app.router?.go('/users/42');   // via router instance
+app.router?.context;           // current RouteContext
 ```
 
-## Configuration
-
-### AppConfig
+### Theme
 
 ```typescript
-interface AppConfig {
-  root?: Element;              // Root element (default: document.body)
-  basepath?: string;           // Base path for routing (default: '/')
-  routes: RouteConfig[];       // Route definitions
-  fallback?: FallbackConfig;   // Error fallback route
-  theme?: ThemeInitOptions;    // Theme configuration
-  localization?: i18next.InitOptions;  // i18next options
-  layout: LayoutConfig;        // Layout configuration
-}
+app.theme.get();         // 'system' | 'light' | 'dark' | undefined
+app.theme.set('dark');
+app.theme.isInitialized; // boolean
 ```
 
-### Theme Options
+### Notifications
 
 ```typescript
-interface ThemeInitOptions {
-  default?: 'system' | 'light' | 'dark';  // Default theme
-  debug?: boolean;                         // Enable debug logging
-  store?: false | {                        // Persist theme preference
-    type: 'cookie' | 'localStorage' | 'sessionStorage';
-    prefix?: string;
-  };
-  useBuiltIn?: boolean;  // Use built-in styles (default: true)
-}
+await app.success('Saved!', { title: 'Done', duration: 4000, position: 'top-right' });
+await app.error('Something went wrong');
+await app.info('Info message');
+await app.warning('Double-check this');
+await app.notice('Neutral notice');
 ```
 
-### Layout Configuration (Sidebar)
+### Localization (i18next)
 
 ```typescript
-interface SidebarLayoutConfig {
-  type: 'sidebar';
-  breakpoints?: [number, number];  // [small, medium] (default: [768, 1024])
-  logo?: {
-    type: 'icon' | 'image';
-    icon?: string;
-    src?: string;
-    label?: string;
-    onClick?: () => void;
-  };
-  menu?: MenuItem[];     // Navigation menu items
-  footer?: FooterItem[]; // Footer buttons/items
-}
-```
+// Pass i18next plugins and InitOptions
+await app.load({
+  // ...
+  i18n: {
+    plugins: [i18nextHttpBackend],
+    lng: 'en',
+    backend: { loadPath: '/locales/{{lng}}/{{ns}}.json' },
+  },
+});
 
-### Route Configuration
+// Access i18next
+app.i18n.t('common::greeting');
+app.i18n.changeLanguage('ko');
 
-```typescript
-interface RouteConfig {
-  index?: boolean;           // Index route
-  path?: string;             // Route path (supports :param patterns)
-  title?: string;            // Document title
-  force?: boolean;           // Force re-render
-  render: (context: RouteContext) => RenderResult | Promise<RenderResult>;
-}
-
-interface RouteContext {
-  href: string;              // Full URL
-  pathname: string;          // Path portion
-  basepath: string;          // Base path
-  params: Record<string, string>;  // URL parameters
-  progress: (value: number) => void;  // Progress callback (0-100)
-}
+// Reactive translations in Lit templates
+import { translate } from 'lit-i18n';
+html`<p>${translate('common::greeting')}</p>`;
 ```
 
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [getting-started.md](./docs/getting-started.md) | Bootstrap, architecture, entry point setup |
+| [routing.md](./docs/routing.md) | Route config, URL params, async routes, progress |
+| [layout.md](./docs/layout.md) | Sidebar layout, all menu item types, responsive behaviour |
+| [theme.md](./docs/theme.md) | Theme init, runtime switching, CSS tokens |
+| [notifications.md](./docs/notifications.md) | Toast methods and options |
+| [i18n.md](./docs/i18n.md) | i18next setup, plugins, lit-i18n usage |
+| [configuration.md](./docs/configuration.md) | Full TypeScript interface reference |
+
 ## License
 
 MIT

package/dist/components/SidebarButton.js

@@ -29,5 +29,5 @@ var s = class extends n {
 t([o({
 	type: Boolean,
 	reflect: !0
-}), e("design:type", Object)], s.prototype, "compact", void 0), t([o({ type: String }), e("design:type", String)], s.prototype, "icon", void 0), t([o({ type: String }), e("design:type", Object)], s.prototype, "label", void 0), s = t([a("sidebar-button")], s);
+}), e("design:type", Object)], s.prototype, "compact", void 0), t([o({ type: String }), e("design:type", String)], s.prototype, "icon", void 0), t([o({ type: String }), e("design:type", Object)], s.prototype, "label", void 0), s = t([a("u-sidebar-button")], s);
 //#endregion

package/dist/components/SidebarGroup.js

@@ -51,5 +51,5 @@ t([s({
 }), e("design:type", Boolean)], c.prototype, "selected", void 0), t([s({
 	type: Boolean,
 	reflect: !0
-}), e("design:type", Boolean)], c.prototype, "collapsed", void 0), t([s({ type: String }), e("design:type", String)], c.prototype, "icon", void 0), t([s({ type: String }), e("design:type", Object)], c.prototype, "label", void 0), c = t([o("sidebar-group")], c);
+}), e("design:type", Boolean)], c.prototype, "collapsed", void 0), t([s({ type: String }), e("design:type", String)], c.prototype, "icon", void 0), t([s({ type: String }), e("design:type", Object)], c.prototype, "label", void 0), c = t([o("u-sidebar-group")], c);
 //#endregion

package/dist/components/SidebarLink.js

@@ -31,6 +31,6 @@ var s = class extends n {
 t([o({
 	type: Boolean,
 	reflect: !0
-}), e("design:type", Object)], s.prototype, "selected", void 0), t([o({ type: Boolean }), e("design:type", Object)], s.prototype, "compact", void 0), t([o({ type: String }), e("design:type", String)], s.prototype, "icon", void 0), t([o({ type: String }), e("design:type", Object)], s.prototype, "label", void 0), t([o({ type: String }), e("design:type", String)], s.prototype, "href", void 0), t([o({ type: String }), e("design:type", Object)], s.prototype, "pattern", void 0), s = t([a("sidebar-link")], s);
+}), e("design:type", Object)], s.prototype, "selected", void 0), t([o({ type: Boolean }), e("design:type", Object)], s.prototype, "compact", void 0), t([o({ type: String }), e("design:type", String)], s.prototype, "icon", void 0), t([o({ type: String }), e("design:type", Object)], s.prototype, "label", void 0), t([o({ type: String }), e("design:type", String)], s.prototype, "href", void 0), t([o({ type: String }), e("design:type", Object)], s.prototype, "pattern", void 0), s = t([a("u-sidebar-link")], s);
 //#endregion
 export { s as SidebarLink };

package/dist/components/SidebarSection.js

@@ -29,5 +29,5 @@ var s = class extends n {
     `;
 	}
 };
-t([o({ type: Boolean }), e("design:type", Object)], s.prototype, "compact", void 0), t([o({ type: String }), e("design:type", Object)], s.prototype, "mainTitle", void 0), t([o({ type: String }), e("design:type", Object)], s.prototype, "subTitle", void 0), s = t([a("sidebar-section")], s);
+t([o({ type: Boolean }), e("design:type", Object)], s.prototype, "compact", void 0), t([o({ type: String }), e("design:type", Object)], s.prototype, "mainTitle", void 0), t([o({ type: String }), e("design:type", Object)], s.prototype, "subTitle", void 0), s = t([a("u-sidebar-section")], s);
 //#endregion

package/dist/layouts/SidebarLayout.d.ts

@@ -49,6 +49,8 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
     private handleRouteProgress;
     /** 라우트 변경 완료 핸들러 */
     private handleRouteDone;
+    /** 라우트 에러 핸들러 */
+    private handleRouteError;
     /** 화면 크기 변경에 따른 사이드바 상태 업데이트 */
     private handleScreenResize;
 }

package/dist/layouts/SidebarLayout.js

@@ -25,11 +25,17 @@ var m, h = class extends r {
 		}, this.handleBackdropClick = () => {
 			this.state = "slim";
 		}, this.handleRouteBegin = (e) => {
-			this.progressBarEl.value = 0, this.state === "modal" && (this.state = "slim"), this.state === "mobile-open" && (this.state = "mobile"), this.context = e.context;
+			this.progressBarEl.setAttribute("visible", ""), this.progressBarEl.value = 0, this.state === "modal" && (this.state = "slim"), this.state === "mobile-open" && (this.state = "mobile"), this.context = e.context;
 		}, this.handleRouteProgress = (e) => {
 			this.progressBarEl.value = e.progress;
 		}, this.handleRouteDone = (e) => {
-			this.progressBarEl.value = 100;
+			this.progressBarEl.value = 100, setTimeout(() => {
+				this.progressBarEl.removeAttribute("visible");
+			}, 300);
+		}, this.handleRouteError = (e) => {
+			this.progressBarEl.setAttribute("error", ""), this.progressBarEl.value = 100, setTimeout(() => {
+				this.progressBarEl.removeAttribute("visible"), this.progressBarEl.removeAttribute("error");
+			}, 300);
 		}, this.handleScreenResize = (e) => {
 			let t = e.detail.size;
 			t === "large" ? this.state = "default" : t === "medium" ? this.state = "slim" : t === "small" ? this.state = "mobile" : console.warn("Unknown screen size:", t);
@@ -39,10 +45,10 @@ var m, h = class extends r {
 		this.styles = [super.styles, i];
 	}
 	connectedCallback() {
-		super.connectedCallback(), window.addEventListener("route-begin", this.handleRouteBegin), window.addEventListener("route-done", this.handleRouteDone), window.addEventListener("route-progress", this.handleRouteProgress), window.addEventListener("screen-resize", this.handleScreenResize);
+		super.connectedCallback(), window.addEventListener("route-begin", this.handleRouteBegin), window.addEventListener("route-done", this.handleRouteDone), window.addEventListener("route-progress", this.handleRouteProgress), window.addEventListener("route-error", this.handleRouteError), window.addEventListener("screen-resize", this.handleScreenResize);
 	}
 	disconnectedCallback() {
-		window.removeEventListener("route-begin", this.handleRouteBegin), window.removeEventListener("route-done", this.handleRouteDone), window.removeEventListener("route-progress", this.handleRouteProgress), window.removeEventListener("screen-resize", this.handleScreenResize), super.disconnectedCallback();
+		window.removeEventListener("route-begin", this.handleRouteBegin), window.removeEventListener("route-done", this.handleRouteDone), window.removeEventListener("route-progress", this.handleRouteProgress), window.removeEventListener("route-error", this.handleRouteError), window.removeEventListener("screen-resize", this.handleScreenResize), super.disconnectedCallback();
 	}
 	willUpdate(e) {
 		super.willUpdate(e), e.has("config") && (this.styles = this.config?.styles);

package/dist/layouts/SidebarLayout.styles.js

@@ -151,14 +151,25 @@ var t = e`
   }
 
   .main u-progress-bar {
+    --progress-bar-height: 4px;
+    --progres-bar-track-color: transparent;
+    
     position: absolute;
     z-index: 100;
     top: 0;
     left: 0;
     right: 0;
-    height: 4px;
-    border-radius: 0;
-    background-color: transparent;
+    opacity: 0;
+    transform: translateY(-4px);
+    transition: opacity 0.3s ease, transform 0.3s ease;
+    pointer-events: none;
+  }
+  .main u-progress-bar[visible] {
+    opacity: 1;
+    transform: translateY(0);
+  }
+  .main u-progress-bar[error] {
+    --progress-bar-color: var(--u-red-500);
   }
 
   /* Backdrop for modal mode */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/modern-app",
   "description": "web-framework by iyulab based on lit-element",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "keywords": [
     "iyulab",
     "web-framework",
@@ -15,6 +15,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "package.json",
     "README.md",
     "CHANGELOG.md",
@@ -37,7 +38,7 @@
     "build": "vite build"
   },
   "dependencies": {
-    "@iyulab/components": "^1.0.0",
+    "@iyulab/components": "^1.0.1",
     "@iyulab/router": "^0.7.4",
     "i18next": "^25.10.10",
     "lit": "^3.3.2"

package/skills/modern-app/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: modern-app
+description: Client-side SPA framework built on Lit Element. Bootstraps an application with sidebar layout, client-side routing, theme management, toast notifications, and i18n (i18next). Use when working with the @iyulab/modern-app package — setting up a new app, configuring routes, adding navigation menu items, managing theme, showing toasts, or wiring up localization.
+license: MIT
+metadata:
+  author: iyulab
+  version: "0.3.4"
+compatibility: Designed for Lit Element / TypeScript projects. Requires @iyulab/modern-app.
+---
+
+# @iyulab/modern-app
+
+A client-side SPA framework built on Lit Element. Provides a single `app` singleton that wires together routing, layout, theme, notifications, and i18n.
+
+> **Suitable for:** SPAs, admin dashboards, internal tools, PWAs.  
+> **Not suitable for:** SSR (Next.js, Nuxt, SvelteKit), SSG, SEO-critical pages.
+
+## Installation
+
+```bash
+npm install @iyulab/modern-app
+```
+
+---
+
+## Bootstrap
+
+Call `app.load()` once at the entry point. All options are in [`AppConfig`](./references/api.md#appconfig).
+
+```typescript
+import { app } from '@iyulab/modern-app';
+import { html } from 'lit';
+
+await app.load({
+  basepath: '/',
+  layout: {
+    type: 'sidebar',
+    logo: '/assets/logo.svg',
+    title: 'My App',
+    main: [
+      { type: 'link', icon: 'home', label: 'Home',     href: '/' },
+      { type: 'link', icon: 'users', label: 'Users',   href: '/users' },
+    ],
+  },
+  routes: [
+    { index: true,       render: () => html`<home-page></home-page>` },
+    { path: 'users',     render: () => html`<users-page></users-page>` },
+    { path: 'users/:id', render: (ctx) => html`<user-detail .userId=${ctx.params.id}></user-detail>` },
+  ],
+  fallback: {
+    render: (ctx) => html`<error-page .error=${ctx.error}></error-page>`,
+  },
+});
+```
+
+To tear down the app:
+
+```typescript
+app.unload();
+```
+
+---
+
+## Navigation
+
+```typescript
+app.navigate('/users/42');       // push route
+app.router?.go('/users/42');     // same via router instance
+app.router?.basepath;            // base path string
+app.router?.context;             // current RouteContext
+app.router?.routes;              // registered routes
+```
+
+---
+
+## Theme
+
+```typescript
+app.theme.get();          // 'system' | 'light' | 'dark' | undefined
+app.theme.set('dark');    // 'system' | 'light' | 'dark'
+app.theme.isInitialized;  // boolean
+```
+
+Theme `store` options persist the preference across sessions:
+
+```typescript
+theme: {
+  default: 'system',
+  store: { type: 'localStorage', prefix: 'myapp' },
+  useBuiltIn: true,
+}
+```
+
+---
+
+## Notifications (Toast)
+
+All methods return `Promise<void>`.
+
+```typescript
+await app.notice('A general notice');
+await app.info('Loaded successfully');
+await app.success('Saved!', { title: 'Done', duration: 4000, position: 'top-right' });
+await app.warning('Check your input');
+await app.error('Something went wrong');
+```
+
+`position` values: `'top-right'` | `'top-left'` | `'bottom-right'` | `'bottom-left'`  
+`duration` default: `3000` ms
+
+---
+
+## Localization (i18next)
+
+Pass standard i18next `InitOptions` plus an optional `plugins` array.
+
+```typescript
+import i18nextHttpBackend from 'i18next-http-backend';
+
+await app.load({
+  // ...
+  i18n: {
+    plugins: [i18nextHttpBackend],
+    lng: 'en',
+    fallbackLng: 'en',
+    backend: { loadPath: '/locales/{{lng}}/{{ns}}.json' },
+  },
+});
+
+// Access i18next instance
+app.i18n.t('namespace::key');
+```
+
+Use in Lit templates with `lit-i18n`:
+
+```typescript
+import { translate } from 'lit-i18n';
+html`<p>${translate('namespace::greeting')}</p>`;
+```
+
+---
+
+## Sidebar Layout
+
+Full configuration reference: [references/layout.md](./references/layout.md)
+
+### Menu item types
+
+| type | Description |
+|------|-------------|
+| `'link'` | Single navigation link with optional icon |
+| `'group'` | Collapsible group of links |
+| `'section'` | Labelled section grouping links and groups |
+| `'button'` | Action button (non-navigation) |
+| `'html'` | Custom Lit template rendered inline |
+
+```typescript
+layout: {
+  type: 'sidebar',
+  logo: '/logo.svg',
+  title: 'App Name',
+  main: [
+    {
+      type: 'section',
+      title: 'Management',
+      items: [
+        { type: 'link',  icon: 'users', label: 'Users',    href: '/users' },
+        {
+          type: 'group', icon: 'settings', label: 'Settings',
+          items: [
+            { type: 'link', label: 'Profile',  href: '/settings/profile' },
+            { type: 'link', label: 'Security', href: '/settings/security' },
+          ],
+        },
+      ],
+    },
+  ],
+  footer: [
+    { type: 'button', icon: 'logout', label: 'Logout', onClick: () => signOut() },
+  ],
+}
+```
+
+### Responsive breakpoints
+
+```typescript
+layout: {
+  type: 'sidebar',
+  breakpoints: [768, 1024], // [tablet-min-px, desktop-min-px]
+  // ...
+}
+```
+
+Sidebar states: `'default'` | `'slim'` | `'modal'` | `'mobile'` | `'mobile-open'`
+
+---
+
+## Routes with progress
+
+```typescript
+{
+  path: 'dashboard',
+  title: 'Dashboard',
+  render: async (ctx) => {
+    ctx.progress(30);
+    const data = await fetchData();
+    ctx.progress(100);
+    return html`<dashboard-page .data=${data}></dashboard-page>`;
+  },
+}
+```
+
+`RouteContext` fields: `href`, `pathname`, `basepath`, `params`, `progress`
+
+---
+
+## Full `AppConfig` reference
+
+See [references/api.md](./references/api.md) for all TypeScript interfaces.

package/skills/modern-app/references/api.md

@@ -0,0 +1,179 @@
+# API Reference — @iyulab/modern-app
+
+## `AppConfig`
+
+```typescript
+interface AppConfig {
+  /** Root element to render into. Default: document.body */
+  root?: Element;
+
+  /** Base path for all routes. Default: '/' */
+  basepath?: string;
+
+  /** Base URL for icon assets. Default: '/assets/icons/' */
+  iconBasepath?: string;
+
+  /** Route definitions. */
+  routes?: RouteConfig[];
+
+  /** Fallback rendered on 404 or unhandled errors. */
+  fallback?: FallbackRouteConfig;
+
+  /** Layout configuration. Currently only 'sidebar' is supported. */
+  layout: LayoutConfig;
+
+  /** Theme initialization options. */
+  theme?: ThemeInitOptions;
+
+  /** i18next options plus optional plugins array. Omit to skip i18n. */
+  i18n?: I18nInitOptions;
+}
+```
+
+---
+
+## `LayoutConfig`
+
+```typescript
+type LayoutConfig = SidebarLayoutConfig & {
+  /** Responsive breakpoints [tablet-min, desktop-min] in px. Default: [768, 1024] */
+  breakpoints?: [number, number];
+};
+```
+
+---
+
+## `ThemeInitOptions`
+
+```typescript
+interface ThemeInitOptions {
+  /** Initial theme. Default: 'system' */
+  default?: 'system' | 'light' | 'dark';
+
+  /** Log theme decisions to console. */
+  debug?: boolean;
+
+  /**
+   * Persist the user's preference.
+   * Set to `false` to disable persistence.
+   * Default: localStorage with no prefix.
+   */
+  store?: false | {
+    type: 'cookie' | 'localStorage' | 'sessionStorage';
+    prefix?: string;
+  };
+
+  /** Apply built-in CSS custom properties. Default: true */
+  useBuiltIn?: boolean;
+}
+```
+
+---
+
+## `RouteConfig`
+
+```typescript
+interface RouteConfig {
+  /** Matches the root path (equivalent to `path: ''`). */
+  index?: boolean;
+
+  /** Path string. Supports `:param` segments. */
+  path?: string;
+
+  /** Sets `document.title` when the route activates. */
+  title?: string;
+
+  /** Force a re-render even if the path did not change. */
+  force?: boolean;
+
+  /** Render function. May be async. */
+  render: (context: RouteContext) => RenderResult | Promise<RenderResult>;
+}
+```
+
+---
+
+## `RouteContext`
+
+```typescript
+interface RouteContext {
+  /** Full URL string. */
+  href: string;
+
+  /** Pathname portion of the URL. */
+  pathname: string;
+
+  /** Configured basepath. */
+  basepath: string;
+
+  /** Named URL parameters extracted from the path pattern. */
+  params: Record<string, string>;
+
+  /**
+   * Report loading progress (0–100).
+   * Drives the progress bar shown in the layout header.
+   */
+  progress: (value: number) => void;
+}
+```
+
+---
+
+## `FallbackRouteConfig`
+
+```typescript
+interface FallbackRouteConfig {
+  render: (context: RouteContext) => RenderResult | Promise<RenderResult>;
+}
+```
+
+The fallback `RouteContext` will include an `error` property when triggered by
+a routing error.
+
+---
+
+## `I18nInitOptions`
+
+```typescript
+type I18nInitOptions = i18next.InitOptions & {
+  /** i18next plugins to register via i18next.use() before init. */
+  plugins?: (Module | NewableModule<Module> | Newable<Module>)[];
+};
+```
+
+---
+
+## `NotificationOptions`
+
+```typescript
+interface NotificationOptions {
+  title?: string;
+  duration?: number;   // milliseconds, default 3000
+  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+}
+```
+
+---
+
+## `app` singleton methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `load` | `(config: AppConfig) => Promise<void>` | Initialize and mount the application |
+| `unload` | `() => void` | Tear down layout, router, and observers |
+| `navigate` | `(path: string) => void` | Push a new route |
+| `notice` | `(msg, opts?) => Promise<void>` | Show a neutral toast |
+| `info` | `(msg, opts?) => Promise<void>` | Show an info toast |
+| `success` | `(msg, opts?) => Promise<void>` | Show a success toast |
+| `warning` | `(msg, opts?) => Promise<void>` | Show a warning toast |
+| `error` | `(msg, opts?) => Promise<void>` | Show an error toast |
+
+### `app` singleton properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `config` | `AppConfig \| undefined` | Current config passed to `load()` |
+| `router` | `Router \| undefined` | Underlying `@iyulab/router` instance |
+| `screen` | `ScreenSize \| undefined` | Current responsive screen size |
+| `theme` | `Theme` (static) | Theme utility (`get`, `set`, `isInitialized`) |
+| `i18n` | `i18next` | Raw i18next instance |

package/skills/modern-app/references/layout.md

@@ -0,0 +1,204 @@
+# Sidebar Layout Reference — @iyulab/modern-app
+
+## `SidebarLayoutConfig`
+
+```typescript
+interface SidebarLayoutConfig {
+  type: 'sidebar';
+
+  /** URL or path to the logo image. */
+  logo?: string;
+
+  /** Application title displayed beside the logo. */
+  title?: string;
+
+  /** Main (top) navigation items. */
+  main?: SidebarItem[];
+
+  /** Footer (bottom-pinned) items. */
+  footer?: SidebarItem[];
+
+  /** Per-part style overrides (CSS custom properties / inline styles). */
+  styles?: StyleMap<SidebarParts>;
+}
+```
+
+---
+
+## `SidebarItem` union
+
+`SidebarItem` is the union of all six item types below.
+
+### `SidebarLinkConfig` — `type: 'link'`
+
+A single navigation link. Highlights automatically when the current URL matches `href` (or `pattern`).
+
+```typescript
+interface SidebarLinkConfig {
+  type: 'link';
+  label: string | DirectiveResult;
+  href: string;
+  icon?: string;
+  /** Override the URL matching pattern. Accepts a string or URLPattern. */
+  pattern?: string | URLPattern;
+  styles?: StyleMap<'host' | 'base' | 'icon' | 'label'>;
+}
+```
+
+Example:
+
+```typescript
+{ type: 'link', icon: 'dashboard', label: 'Dashboard', href: '/' }
+```
+
+---
+
+### `SidebarGroupConfig` — `type: 'group'`
+
+Collapsible group that contains links.
+
+```typescript
+interface SidebarGroupConfig {
+  type: 'group';
+  icon: string;
+  label: string | DirectiveResult;
+  items: SidebarLinkConfig[];
+  /** Start collapsed. Default: true */
+  collapsed?: boolean;
+  styles?: StyleMap<'host' | 'header' | 'icon' | 'label' | 'caret' | 'items'>;
+}
+```
+
+Example:
+
+```typescript
+{
+  type: 'group',
+  icon: 'settings',
+  label: 'Settings',
+  collapsed: false,
+  items: [
+    { type: 'link', label: 'Profile',  href: '/settings/profile' },
+    { type: 'link', label: 'Security', href: '/settings/security' },
+  ],
+}
+```
+
+---
+
+### `SidebarSectionConfig` — `type: 'section'`
+
+Labelled section that groups links and groups.
+
+```typescript
+interface SidebarSectionConfig {
+  type: 'section';
+  title: string | DirectiveResult;
+  subTitle?: string | DirectiveResult;
+  items: (SidebarGroupConfig | SidebarLinkConfig)[];
+  styles?: StyleMap<'host' | 'header' | 'title' | 'subtitle' | 'items'>;
+}
+```
+
+Example:
+
+```typescript
+{
+  type: 'section',
+  title: 'Administration',
+  items: [
+    { type: 'link', icon: 'users',    label: 'Users',    href: '/admin/users' },
+    { type: 'link', icon: 'database', label: 'Database', href: '/admin/db' },
+  ],
+}
+```
+
+---
+
+### `SidebarButtonConfig` — `type: 'button'`
+
+Action button — triggers a callback instead of navigating.
+
+```typescript
+interface SidebarButtonConfig {
+  type: 'button';
+  icon?: string;
+  label: string | DirectiveResult;
+  onClick: () => void;
+  styles?: StyleMap<string>;
+}
+```
+
+Example:
+
+```typescript
+{ type: 'button', icon: 'logout', label: 'Sign Out', onClick: () => auth.signOut() }
+```
+
+---
+
+### `SidebarHtmlConfig` — `type: 'html'`
+
+Renders a custom Lit template or raw HTML element. The `render` function
+receives the current sidebar state so you can adapt the content.
+
+```typescript
+interface SidebarHtmlConfig {
+  type: 'html';
+  render: (state: SidebarState) => TemplateResult<1> | HTMLElement | string;
+}
+```
+
+`SidebarState` values: `'default'` | `'slim'` | `'modal'` | `'mobile'` | `'mobile-open'`
+
+Example:
+
+```typescript
+{
+  type: 'html',
+  render: (state) => html`
+    <div class="user-card" ?hidden=${state === 'slim'}>
+      <img src="/avatar.png" />
+      <span>John Doe</span>
+    </div>
+  `,
+}
+```
+
+---
+
+## Sidebar parts
+
+Parts available for `styles` overrides on the root layout:
+
+| Part | Element |
+|------|---------|
+| `host` | Outer layout shell |
+| `mobile-header` | Top bar shown on mobile |
+| `sidebar` | Sidebar panel |
+| `sidebar-header` | Logo + title area |
+| `sidebar-main` | Scrollable main nav area |
+| `sidebar-footer` | Pinned footer area |
+| `main` | Main content area |
+| `progress` | Top progress bar |
+
+---
+
+## Responsive behaviour
+
+| Screen width | Sidebar state |
+|--------------|--------------|
+| < breakpoints[0] | `mobile` / `mobile-open` |
+| breakpoints[0] – breakpoints[1] | `slim` (icons only) |
+| > breakpoints[1] | `default` (full labels) |
+
+Default breakpoints: `[768, 1024]` px.
+Override per app:
+
+```typescript
+layout: {
+  type: 'sidebar',
+  breakpoints: [640, 1280],
+  // ...
+}
+```