@pure-ds/core 0.4.24 → 0.4.25

package/.cursorrules

@@ -41,6 +41,210 @@ PDS follows the [Pure Web Manifesto](https://pureweb.dev/manifesto): "The browse
 - `public/assets/pds/vscode-custom-data.json`
 - `src/js/pds-core/pds-ontology.js`
 
+**Path resolution helper:** When looking up SSoT files:
+1. First check if `node_modules/@pure-ds/core/` exists (consuming project)
+2. Otherwise use workspace root paths (pure-ds development)
+3. Prefer reading actual files over guessing - the data is authoritative
+
+---
+
+## 📋 pds-form Best Practices
+
+**When generating pds-form code, ALWAYS follow these patterns:**
+
+### 1. Event Handling - Use `pw:submit`, NOT `submit`
+
+```javascript
+// ✅ CORRECT: Listen to pw:submit custom event
+form.addEventListener('pw:submit', async (e) => {
+  const { json, formData, valid, issues } = e.detail;
+  if (valid) {
+    // Handle submission with json or formData
+  }
+});
+
+// ❌ WRONG: Native submit event
+form.addEventListener('submit', (e) => { /* Won't work */ });
+```
+
+### 2. Submit Button Progress - Add `btn-working` automatically
+
+**When user requests a form with async submission, ALWAYS:**
+- Add `btn-working` class to submit button during processing
+- Remove it when done (PDS automatically shows spinner icon)
+- Use a realistic 2-3 second delay for demos
+
+```javascript
+// ✅ CORRECT: Auto-add progress state
+form.addEventListener('pw:submit', async (e) => {
+  const submitBtn = form.querySelector('button[type="submit"]');
+  submitBtn?.classList.add('btn-working');
+  
+  try {
+    await simulateSubmit(e.detail.json); // 2-3 second promise
+    await PDS.toast('Submitted successfully!', { type: 'success' });
+  } finally {
+    submitBtn?.classList.remove('btn-working');
+  }
+});
+
+async function simulateSubmit(data) {
+  await new Promise(resolve => setTimeout(resolve, 2000));
+  console.log('Submitted:', data);
+}
+```
+
+### 3. Progressive Enhancement - Add `data-required` to form wrapper
+
+```html
+<!-- ✅ CORRECT: Wrap pds-form in form[data-required] -->
+<form data-required>
+  <pds-form id="myForm" hide-actions></pds-form>
+  <div class="form-actions">
+    <button type="submit" class="btn-primary">Submit</button>
+  </div>
+</form>
+
+<!-- ❌ WRONG: No data-required enhancement -->
+<pds-form id="myForm"></pds-form>
+```
+
+### 4. JSON Schema - Use `examples` for placeholders
+
+```javascript
+// ✅ CORRECT: Use examples array for placeholders
+const schema = {
+  type: "object",
+  properties: {
+    name: {
+      type: "string",
+      title: "Full Name",
+      examples: ["John Doe"]  // First example becomes placeholder
+    },
+    email: {
+      type: "string",
+      format: "email",
+      title: "Email",
+      examples: ["user@example.com"]
+    },
+    age: {
+      type: "integer",
+      title: "Age",
+      examples: [25]  // Works for numbers too
+    }
+  }
+};
+
+// ❌ WRONG: No placeholders or using wrong property
+```
+
+### 5. UI Schema - Infer smart icons automatically
+
+**Common field → icon mappings (use these by default):**
+
+```javascript
+const smartIcons = {
+  email: 'envelope',
+  phone: 'phone',
+  name: 'user',
+  password: 'lock',
+  search: 'search',
+  message: 'message',
+  comment: 'comment',
+  address: 'map-marker',
+  website: 'link',
+  date: 'calendar',
+  time: 'clock',
+  subject: 'tag',
+  priority: 'flag',
+  category: 'folder',
+  file: 'file',
+  image: 'image'
+};
+
+const uiSchema = {
+  email: {
+    'ui:widget': 'email',
+    'ui:placeholder': 'user@example.com',
+    'ui:icon': 'envelope',  // Auto-infer
+    'ui:autocomplete': 'email'
+  },
+  phone: {
+    'ui:widget': 'tel',
+    'ui:icon': 'phone',
+    'ui:autocomplete': 'tel'
+  },
+  message: {
+    'ui:widget': 'textarea',
+    'ui:rows': 4,
+    'ui:icon': 'message'
+  }
+};
+```
+
+### 6. Complete Working Example
+
+```javascript
+// Schema with examples for placeholders
+const contactSchema = {
+  type: "object",
+  required: ["name", "email", "message"],
+  properties: {
+    name: {
+      type: "string",
+      title: "Name",
+      minLength: 2,
+      examples: ["John Doe"]
+    },
+    email: {
+      type: "string",
+      format: "email",
+      title: "Email",
+      examples: ["user@example.com"]
+    },
+    message: {
+      type: "string",
+      title: "Message",
+      minLength: 10,
+      examples: ["Your message here..."]
+    }
+  }
+};
+
+// UI schema with smart icons
+const uiSchema = {
+  name: { 'ui:icon': 'user' },
+  email: { 'ui:icon': 'envelope' },
+  message: { 
+    'ui:widget': 'textarea',
+    'ui:rows': 4,
+    'ui:icon': 'message'
+  }
+};
+
+// Setup with pw:submit and btn-working
+const form = document.getElementById('contactForm');
+form.jsonSchema = contactSchema;
+form.uiSchema = uiSchema;
+
+form.addEventListener('pw:submit', async (e) => {
+  const submitBtn = form.querySelector('button[type="submit"]');
+  submitBtn?.classList.add('btn-working');
+  
+  try {
+    // Simulate 2s async operation
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    console.log('Submitted:', e.detail.json);
+    await PDS.toast('Message sent!', { type: 'success' });
+    form.reset();
+  } catch (error) {
+    await PDS.toast('Failed to send', { type: 'error' });
+  } finally {
+    submitBtn?.classList.remove('btn-working');
+  }
+});
+```
+
 ---
 
 ## 🚫 Critical Anti-Patterns (NEVER DO THIS)
@@ -61,12 +265,33 @@ PDS follows the [Pure Web Manifesto](https://pureweb.dev/manifesto): "The browse
 
 ```javascript
 // ❌ NEVER: Browser dialogs - Use PDS.ask() and PDS.toast()
-alert("message");   // → PDS.toast("message", { type: "info" })
+alert("message");   // → await PDS.toast("message", { type: "info" })
 confirm("sure?");   // → await PDS.ask("sure?", { type: "confirm" })
 prompt("name?");    // → await PDS.ask("name?", { type: "prompt" })
 
 // ❌ NEVER: Manual dropdown/modal/tab implementations
 // → Use <nav data-dropdown>, PDS.ask(), <pds-tabstrip>
+
+// ❌ NEVER: Access lazy-loaded component APIs before they're defined
+const form = document.querySelector('pds-form');
+form.getFormData(); // May fail - component not loaded yet
+
+// ❌ NEVER: Use native 'submit' event with pds-form
+form.addEventListener('submit', (e) => { }); // → Use 'pw:submit'
+
+// ❌ NEVER: Forget btn-working class for async operations
+button.onclick = async () => {
+  await fetch('/api'); // No loading indicator!
+};
+// → Add button.classList.add('btn-working') before, remove after
+
+// ❌ NEVER: Hardcode placeholders instead of using schema examples
+const schema = { 
+  properties: { 
+    email: { type: "string" } // Missing examples!
+  }
+};
+// → Add examples: ["user@example.com"]
 ```
 
 ---
@@ -130,7 +355,7 @@ const confirmed = await PDS.ask("Delete this item?", {
   buttons: { ok: { name: "Delete", variant: "danger" } }
 });
 
-PDS.toast("Saved successfully!", { type: "success" });
+await PDS.toast("Saved successfully!", { type: "success" });
 
 // Theme management
 PDS.theme = 'dark';  // 'light' | 'dark' | 'system'
@@ -141,6 +366,19 @@ const results = await PDS.query("border gradient classes");
 
 ---
 
+## 📚 Additional Resources
+
+**For comprehensive pds-form documentation:**
+- Read [pds-form-docs.md](pds-form-docs.md) for complete API reference
+- See [packages/pds-storybook/stories/components/PdsForm.stories.js](packages/pds-storybook/stories/components/PdsForm.stories.js) for real examples
+- Check [custom-elements.json](custom-elements.json) for component API details
+
+**For toast notifications:**
+- Use `PDS.toast()` method (see [src/js/common/toast.js](src/js/common/toast.js) for implementation)
+- Automatically ensures pds-toaster exists and is loaded before displaying
+- See pds-toaster component API in [custom-elements.json](custom-elements.json)
+---
+
 ## How to Look Things Up
 
 | Question | Action |
@@ -166,3 +404,13 @@ Before generating code:
 6. ✅ **Apply enhancements via data-* attributes** — See `pds-enhancer-metadata.js`
 7. ✅ **Components as last resort** — Only when native HTML can't achieve it
 8. ✅ **Prefer primitives** — `.card`, `.badge`, `.alert` over custom components
+9. ✅ **Wait for lazy components** — Use `await customElements.whenDefined()` before accessing APIs
+10. ✅ **Include import map** — When using `pds-form` or `pds-drawer`, ensure `#pds/lit` is mapped
+
+**For pds-form specifically:**
+
+11. ✅ **Use `pw:submit` event** — NOT native `submit` event
+12. ✅ **Add `btn-working` class** — For async submit operations, add during processing
+13. ✅ **Use `examples` in JSON schema** — First example becomes placeholder
+14. ✅ **Add smart icons** — Infer icons based on field names (email→envelope, phone→phone)
+15. ✅ **Wrap in `form[data-required]`** — For asterisk enhancement on required fields

package/.github/copilot-instructions.md

@@ -41,6 +41,210 @@ PDS follows the [Pure Web Manifesto](https://pureweb.dev/manifesto): "The browse
 - `public/assets/pds/vscode-custom-data.json`
 - `src/js/pds-core/pds-ontology.js`
 
+**Path resolution helper:** When looking up SSoT files:
+1. First check if `node_modules/@pure-ds/core/` exists (consuming project)
+2. Otherwise use workspace root paths (pure-ds development)
+3. Prefer reading actual files over guessing - the data is authoritative
+
+---
+
+## 📋 pds-form Best Practices
+
+**When generating pds-form code, ALWAYS follow these patterns:**
+
+### 1. Event Handling - Use `pw:submit`, NOT `submit`
+
+```javascript
+// ✅ CORRECT: Listen to pw:submit custom event
+form.addEventListener('pw:submit', async (e) => {
+  const { json, formData, valid, issues } = e.detail;
+  if (valid) {
+    // Handle submission with json or formData
+  }
+});
+
+// ❌ WRONG: Native submit event
+form.addEventListener('submit', (e) => { /* Won't work */ });
+```
+
+### 2. Submit Button Progress - Add `btn-working` automatically
+
+**When user requests a form with async submission, ALWAYS:**
+- Add `btn-working` class to submit button during processing
+- Remove it when done (PDS automatically shows spinner icon)
+- Use a realistic 2-3 second delay for demos
+
+```javascript
+// ✅ CORRECT: Auto-add progress state
+form.addEventListener('pw:submit', async (e) => {
+  const submitBtn = form.querySelector('button[type="submit"]');
+  submitBtn?.classList.add('btn-working');
+  
+  try {
+    await simulateSubmit(e.detail.json); // 2-3 second promise
+    await PDS.toast('Submitted successfully!', { type: 'success' });
+  } finally {
+    submitBtn?.classList.remove('btn-working');
+  }
+});
+
+async function simulateSubmit(data) {
+  await new Promise(resolve => setTimeout(resolve, 2000));
+  console.log('Submitted:', data);
+}
+```
+
+### 3. Progressive Enhancement - Add `data-required` to form wrapper
+
+```html
+<!-- ✅ CORRECT: Wrap pds-form in form[data-required] -->
+<form data-required>
+  <pds-form id="myForm" hide-actions></pds-form>
+  <div class="form-actions">
+    <button type="submit" class="btn-primary">Submit</button>
+  </div>
+</form>
+
+<!-- ❌ WRONG: No data-required enhancement -->
+<pds-form id="myForm"></pds-form>
+```
+
+### 4. JSON Schema - Use `examples` for placeholders
+
+```javascript
+// ✅ CORRECT: Use examples array for placeholders
+const schema = {
+  type: "object",
+  properties: {
+    name: {
+      type: "string",
+      title: "Full Name",
+      examples: ["John Doe"]  // First example becomes placeholder
+    },
+    email: {
+      type: "string",
+      format: "email",
+      title: "Email",
+      examples: ["user@example.com"]
+    },
+    age: {
+      type: "integer",
+      title: "Age",
+      examples: [25]  // Works for numbers too
+    }
+  }
+};
+
+// ❌ WRONG: No placeholders or using wrong property
+```
+
+### 5. UI Schema - Infer smart icons automatically
+
+**Common field → icon mappings (use these by default):**
+
+```javascript
+const smartIcons = {
+  email: 'envelope',
+  phone: 'phone',
+  name: 'user',
+  password: 'lock',
+  search: 'search',
+  message: 'message',
+  comment: 'comment',
+  address: 'map-marker',
+  website: 'link',
+  date: 'calendar',
+  time: 'clock',
+  subject: 'tag',
+  priority: 'flag',
+  category: 'folder',
+  file: 'file',
+  image: 'image'
+};
+
+const uiSchema = {
+  email: {
+    'ui:widget': 'email',
+    'ui:placeholder': 'user@example.com',
+    'ui:icon': 'envelope',  // Auto-infer
+    'ui:autocomplete': 'email'
+  },
+  phone: {
+    'ui:widget': 'tel',
+    'ui:icon': 'phone',
+    'ui:autocomplete': 'tel'
+  },
+  message: {
+    'ui:widget': 'textarea',
+    'ui:rows': 4,
+    'ui:icon': 'message'
+  }
+};
+```
+
+### 6. Complete Working Example
+
+```javascript
+// Schema with examples for placeholders
+const contactSchema = {
+  type: "object",
+  required: ["name", "email", "message"],
+  properties: {
+    name: {
+      type: "string",
+      title: "Name",
+      minLength: 2,
+      examples: ["John Doe"]
+    },
+    email: {
+      type: "string",
+      format: "email",
+      title: "Email",
+      examples: ["user@example.com"]
+    },
+    message: {
+      type: "string",
+      title: "Message",
+      minLength: 10,
+      examples: ["Your message here..."]
+    }
+  }
+};
+
+// UI schema with smart icons
+const uiSchema = {
+  name: { 'ui:icon': 'user' },
+  email: { 'ui:icon': 'envelope' },
+  message: { 
+    'ui:widget': 'textarea',
+    'ui:rows': 4,
+    'ui:icon': 'message'
+  }
+};
+
+// Setup with pw:submit and btn-working
+const form = document.getElementById('contactForm');
+form.jsonSchema = contactSchema;
+form.uiSchema = uiSchema;
+
+form.addEventListener('pw:submit', async (e) => {
+  const submitBtn = form.querySelector('button[type="submit"]');
+  submitBtn?.classList.add('btn-working');
+  
+  try {
+    // Simulate 2s async operation
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    console.log('Submitted:', e.detail.json);
+    await PDS.toast('Message sent!', { type: 'success' });
+    form.reset();
+  } catch (error) {
+    await PDS.toast('Failed to send', { type: 'error' });
+  } finally {
+    submitBtn?.classList.remove('btn-working');
+  }
+});
+```
+
 ---
 
 ## 🚫 Critical Anti-Patterns (NEVER DO THIS)
@@ -61,7 +265,7 @@ PDS follows the [Pure Web Manifesto](https://pureweb.dev/manifesto): "The browse
 
 ```javascript
 // ❌ NEVER: Browser dialogs - Use PDS.ask() and PDS.toast()
-alert("message");   // → PDS.toast("message", { type: "info" })
+alert("message");   // → await PDS.toast("message", { type: "info" })
 confirm("sure?");   // → await PDS.ask("sure?", { type: "confirm" })
 prompt("name?");    // → await PDS.ask("name?", { type: "prompt" })
 
@@ -71,6 +275,23 @@ prompt("name?");    // → await PDS.ask("name?", { type: "prompt" })
 // ❌ NEVER: Access lazy-loaded component APIs before they're defined
 const form = document.querySelector('pds-form');
 form.getFormData(); // May fail - component not loaded yet
+
+// ❌ NEVER: Use native 'submit' event with pds-form
+form.addEventListener('submit', (e) => { }); // → Use 'pw:submit'
+
+// ❌ NEVER: Forget btn-working class for async operations
+button.onclick = async () => {
+  await fetch('/api'); // No loading indicator!
+};
+// → Add button.classList.add('btn-working') before, remove after
+
+// ❌ NEVER: Hardcode placeholders instead of using schema examples
+const schema = { 
+  properties: { 
+    email: { type: "string" } // Missing examples!
+  }
+};
+// → Add examples: ["user@example.com"]
 ```
 
 ---
@@ -173,7 +394,7 @@ const confirmed = await PDS.ask("Delete this item?", {
   buttons: { ok: { name: "Delete", variant: "danger" } }
 });
 
-PDS.toast("Saved successfully!", { type: "success" });
+await PDS.toast("Saved successfully!", { type: "success" });
 
 // Theme management
 PDS.theme = 'dark';  // 'light' | 'dark' | 'system'
@@ -184,6 +405,20 @@ const results = await PDS.query("border gradient classes");
 
 ---
 
+## 📚 Additional Resources
+
+**For comprehensive pds-form documentation:**
+- Read [pds-form-docs.md](../pds-form-docs.md) for complete API reference
+- See [packages/pds-storybook/stories/components/PdsForm.stories.js](../packages/pds-storybook/stories/components/PdsForm.stories.js) for real examples
+- Check [custom-elements.json](../custom-elements.json) for component API details
+
+**For toast notifications:**
+- Use `PDS.toast()` method (see [src/js/common/toast.js](../src/js/common/toast.js) for implementation)
+- Automatically ensures pds-toaster exists and is loaded before displaying
+- See pds-toaster component API in [custom-elements.json](../custom-elements.json)
+
+---
+
 ## How to Look Things Up
 
 | Question | Action |
@@ -211,3 +446,11 @@ Before generating code:
 8. ✅ **Prefer primitives** — `.card`, `.badge`, `.alert` over custom components
 9. ✅ **Wait for lazy components** — Use `await customElements.whenDefined()` before accessing APIs
 10. ✅ **Include import map** — When using `pds-form` or `pds-drawer`, ensure `#pds/lit` is mapped
+
+**For pds-form specifically:**
+
+11. ✅ **Use `pw:submit` event** — NOT native `submit` event
+12. ✅ **Add `btn-working` class** — For async submit operations, add during processing
+13. ✅ **Use `examples` in JSON schema** — First example becomes placeholder
+14. ✅ **Add smart icons** — Infer icons based on field names (email→envelope, phone→phone)
+15. ✅ **Wrap in `form[data-required]`** — For asterisk enhancement on required fields

package/dist/types/pds.d.ts

@@ -1,408 +1,109 @@
-/**
- * Runtime registry singleton that controls live vs static behavior.
- * Consumers can call `registry.setDesigner(designer)` to enable live mode
- * or `registry.setStaticMode(paths)` to point to static asset modules.
- */
-export interface PDSRegistry {
-  /** Attach a designer instance and switch the registry to live mode. */
-  setDesigner(designer: any, meta?: { presetName?: string }): void;
-  /** Switch to static mode and override static paths (keys: tokens, primitives, components, utilities, styles) */
-  setStaticMode(paths?: Record<string, string>): void;
-  /** Return a constructable stylesheet for the requested layer or null on failure. */
-  getStylesheet(layer: string): Promise<CSSStyleSheet | null>;
-  /** Return a BLOB URL (live mode only) for layer imports used in CSS */
-  getBlobURL(layer: string): string | null;
-  /** 'live' or 'static' */
-  readonly mode: string;
-  /** true when a live designer instance is registered */
-  readonly isLive: boolean;
-  /** true when a designer instance exists */
-  readonly hasDesigner: boolean;
-}
-
-/** A small shape describing component metadata used by the PDS ontology. */
-export interface ComponentDef {
-  /** canonical name of the component (e.g., 'Button') */
-  name: string;
-  /** optional HTML tag name for the component ('pds-button') */
-  tag?: string;
-  /** documented props and their types/metadata */
-  props?: Record<string, any>;
-  /** human-friendly description used by the designer */
-  description?: string;
-}
-
-/** Layer information with CSS content and metadata */
-export interface CompiledLayer {
-  css: string;
-  size: number;
-  sizeKB: string;
-}
-
-/** Complete compiled state of the design system */
-export interface CompiledState {
-  /** Core token groups - the source data used to generate CSS */
-  tokens: {
-    colors: Record<string, any>;
-    spacing: Record<string, any>;
-    radius: Record<string, any>;
-    borderWidths: Record<string, any>;
-    typography: Record<string, any>;
-    shadows: Record<string, any>;
-    layout: Record<string, any>;
-    transitions: Record<string, any>;
-    zIndex: Record<string, any>;
-    icons: Record<string, any>;
-  };
-
-  /** Layer information - CSS content and metadata for each layer */
-  layers: {
-    tokens: CompiledLayer;
-    primitives: CompiledLayer;
-    components: CompiledLayer;
-    utilities: CompiledLayer;
-    combined: CompiledLayer;
-  };
-
-  /** Configuration snapshot - what was used to generate this state */
-  config: {
-    design: any;
-    preset: string | null;
-    debug: boolean;
-  };
-
-  /** Runtime capabilities and environment */
-  capabilities: {
-    constructableStylesheets: boolean;
-    blobURLs: boolean;
-    shadowDOM: boolean;
-  };
-
-  /** References to design system metadata */
-  references: {
-    ontology: any;
-    enums: any;
-  };
-
-  /** Computed metadata about the generated design system */
-  meta: {
-    generatedAt: string;
-    totalSize: number;
-    totalSizeKB: string;
-    layerCount: number;
-    tokenGroups: number;
-  };
-
-  /** Introspection helpers - methods to query the compiled state */
-  helpers: {
-    getColorScales(): Array<{ name: string; scale: any }>;
-    getColorScale(name: string): any;
-    getSpacingValues(): Array<{ key: string; value: any }>;
-    getTypography(): any;
-    getLayerCSS(layer: 'tokens' | 'primitives' | 'components' | 'utilities'): string;
-    usesEnumValue(enumGroup: string, value: any): boolean;
-  };
-}
-
-/**
- * Generator - programmatic API to produce tokens, layered CSS and helper modules from a config.
- * Typical usage:
- * const g = new PDS.Generator({ example: true });
- * // tokens may be returned synchronously or via a Promise
- * const tokens = await g.generateTokens?.();
- * const css = await g.generateCSS?.();
- */
-export class Generator {
-  constructor(options?: any);
-  /** runtime options / config passed to the generator */
-  options: any;
-  /** generated token object */
-  tokens: Record<string, any>;
-  /** concatenated CSS (layered) */
-  css: string;
-  /** Complete compiled representation of the design system state */
-  readonly compiled: CompiledState;
-  /** Generate the token map (may be async in some implementations) */
-  generateTokens?(): Record<string, any> | Promise<Record<string, any>>;
-  /** Generate the CSS string (may be async) */
-  generateCSS?(): string | Promise<string>;
-}
-
-/** Public runtime surface exported as `PDS` */
-export interface PDSEventMap {
-  'pds:ready': CustomEvent<{ mode: 'live' | 'static'; generator?: Generator; config: any; theme: string; autoDefiner?: any }>;
-  'pds:error': CustomEvent<{ error: any }>;
-  'pds:theme:changed': CustomEvent<{ theme: string; requested?: string; source: 'system' | 'programmatic' }>;
-  'pds:design:updated': CustomEvent<{ config: any; designer?: any }>;
-  'pds:design:field:changed': CustomEvent<{ field: string; config: any }>;
-  'pds:inspector:mode:changed': CustomEvent<{ active: boolean }>;
-  'pds:inspector:deactivate': CustomEvent<{}>;
-  'pds:docs:view': CustomEvent<{ file: string }>;
-}
-
-export class PDS extends EventTarget {
-  // Static surface
-  static Generator: typeof Generator;
-  static registry: PDSRegistry;
-  static presets: Record<string, any>;
-  static ontology: any;
-  static adoptLayers: (shadowRoot: ShadowRoot, layers?: string[], additionalSheets?: CSSStyleSheet[]) => Promise<void>;
-  static adoptPrimitives: (shadowRoot: ShadowRoot, additionalSheets?: CSSStyleSheet[]) => Promise<void>;
-  static createStylesheet: (css: string) => CSSStyleSheet;
-  static isLiveMode: () => boolean;
-  static findComponentForElement: (el: Element) => ComponentDef | null;
-  static validateDesign: (designConfig: any, options?: { minContrast?: number }) => { ok: boolean; issues: Array<{ path: string; message: string; ratio: number; min: number; context?: string }> };
-  static validateDesigns: (designs: Array<any> | Record<string, any>, options?: { minContrast?: number }) => { ok: boolean; results: Array<{ name?: string; ok: boolean; issues: Array<{ path: string; message: string; ratio: number; min: number; context?: string }> }> };
-  
-  /** 
-   * Current configuration after PDS.start() completes - read-only, frozen after initialization.
-   * Contains the complete configuration used to initialize PDS, including mode, design, preset, and theme.
-   */
-  static readonly currentConfig: any;
-  
-  /**
-   * Compiled design system state - provides structured access to all generated tokens,
-   * layers, and metadata. Available in live mode when a generator is active.
-   * Returns null if not in live mode or if no generator is present.
-   */
-  static readonly compiled: CompiledState | null;
-
-  // Static EventTarget-like facade for default instance
-  static addEventListener<K extends keyof PDSEventMap>(type: K, listener: (ev: PDSEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
-  static removeEventListener<K extends keyof PDSEventMap>(type: K, listener: (ev: PDSEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
-  static dispatchEvent(event: PDSEventMap[keyof PDSEventMap] | Event): boolean;
-
-  // Static entry point
-  static start(config?: {
-    mode?: 'live' | 'static';
-    preset?: string;
-    design?: any;
-    autoDefine?: {
-      baseURL?: string;
-      predefine?: string[];
-  mapper?: (tag: string) => string | undefined | null | false;
-      scanExisting?: boolean;
-      observeShadows?: boolean;
-      patchAttachShadow?: boolean;
-      debounceMs?: number;
-      onError?: (tag: string, err: any) => void;
-    };
-    applyGlobalStyles?: boolean;
-    manageTheme?: boolean;
-    themeStorageKey?: string;
-    public?: {
-      root?: string;
-    };
-    // live-only
-    preloadStyles?: boolean;
-    criticalLayers?: string[];
-    // static-only
-    staticPaths?: Record<string, string>;
-    enhancers?: Array<any>;
-  }): Promise<PDS>;
-
-  constructor();
-
-  // Instance state
-  readonly mode: 'live' | 'static';
-  readonly generator?: Generator;
-  readonly config: any;
-  readonly theme: string;
-  readonly autoDefiner?: any;
-
-  // Instance helpers
-  setTheme(theme: 'light' | 'dark' | 'system', options?: { storageKey?: string; persist?: boolean }): Promise<string>;
-  preloadCritical(config: any, options?: { theme?: string; layers?: string[] }): void;
-}
-
-export { PDS as default };
-
-// ===== pds-form Types =====
-
-export interface JsonFormOptions {
-  widgets?: {
-    booleans?: 'toggle' | 'checkbox';
-    numbers?: 'input' | 'range';
-    selects?: 'standard' | 'dropdown';
-  };
-  layouts?: {
-    fieldsets?: 'default' | 'flex' | 'grid' | 'accordion' | 'tabs' | 'card';
-    arrays?: 'default' | 'compact';
-  };
-  enhancements?: {
-    icons?: boolean;
-    datalists?: boolean;
-    rangeOutput?: boolean;
-  };
-  validation?: {
-    showErrors?: boolean;
-    validateOnChange?: boolean;
-  };
-  // Path-specific options (JSON Pointer paths)
-  [path: string]: any;
-}
-
-export interface UISchema {
-  // Field-level UI customization (JSON Pointer paths as keys)
-  [path: string]: {
-    'ui:widget'?: string;
-    'ui:layout'?: 'default' | 'flex' | 'grid' | 'accordion' | 'tabs';
-    'ui:columns'?: number | 'auto';
-    'ui:autoSize'?: 'sm' | 'md' | 'lg' | 'xl';
-    'ui:gap'?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-    'ui:wrap'?: boolean;
-    'ui:direction'?: 'row' | 'column';
-    'ui:surface'?: 'card' | 'elevated' | 'dialog';
-    'ui:accordion'?: boolean;
-    'ui:tabs'?: boolean;
-    'ui:defaultOpen'?: number[];
-    'ui:dialog'?: boolean;
-    'ui:dialogButton'?: string;
-    'ui:dialogSize'?: 'sm' | 'lg' | 'xl' | 'full';
-    'ui:submitLabel'?: string;
-    'ui:cancelLabel'?: string;
-    'ui:help'?: string;
-    'ui:placeholder'?: string;
-    'ui:icon'?: string;
-    'ui:iconPosition'?: 'start' | 'end';
-    'ui:datalist'?: string[];
-    'ui:rows'?: number;
-    'ui:min'?: number;
-    'ui:max'?: number;
-    'ui:dropdown'?: boolean;
-    'ui:autocomplete'?: string;
-    'ui:accept'?: string;
-    'ui:multiple'?: boolean;
-    'ui:maxFiles'?: number;
-    'ui:maxSize'?: number;
-    'ui:submitOnEnter'?: boolean;
-    'ui:spellcheck'?: boolean;
-    'ui:order'?: string[];
-  };
-}
-
-export interface JsonFormEvent<T = any> extends CustomEvent {
-  detail: T;
-}
-
-export interface JsonFormSubmitDetail {
-  json: any;
-  formData: FormData;
-  valid: boolean;
-  issues: Array<{ path?: string; message: string }>;
-}
-
-export interface JsonFormValueChangeDetail {
-  name: string;
-  value: any;
-  validity: { valid: boolean };
-}
-
-export interface JsonFormArrayEventDetail {
-  path: string;
-  index?: number;
-  from?: number;
-  to?: number;
-}
-
-export interface JsonFormDialogEventDetail {
-  path: string;
-  schema?: any;
-  value?: any;
-}
-
-export interface JsonFormRendererContext {
-  id: string;
-  path: string;
-  label: string;
-  value: any;
-  required: boolean;
-  ui: any;
-  schema: any;
-  get: (path?: string) => any;
-  set: (value: any, path?: string) => void;
-  attrs: {
-    placeholder?: string;
-    minLength?: number;
-    maxLength?: number;
-    min?: number;
-    max?: number;
-    step?: number;
-    pattern?: string;
-    readOnly?: boolean;
-    required?: boolean;
-    autocomplete?: string;
-    list?: string;
-  };
-  host: any;
-}
-
-export type JsonFormRenderer = (context: JsonFormRendererContext) => any;
-
-export interface JsonFormEventMap {
-  'pw:schema-resolve': JsonFormEvent<{ schema: any }>;
-  'pw:compile-node': JsonFormEvent<{ path: string; schema: any; ui: any; node?: any }>;
-  'pw:choose-widget': JsonFormEvent<{ path: string; schema: any; ui: any; widget: string | null }>;
-  'pw:before-render-field': JsonFormEvent<{ path: string; schema: any; ui: any; mount?: any; render?: () => any }>;
-  'pw:render-field': JsonFormEvent<{ path: string; schema: any; node: any }>;
-  'pw:after-render-field': JsonFormEvent<{ path: string; schema: any }>;
-  'pw:value-change': JsonFormEvent<JsonFormValueChangeDetail>;
-  'pw:array-add': JsonFormEvent<JsonFormArrayEventDetail>;
-  'pw:array-remove': JsonFormEvent<JsonFormArrayEventDetail>;
-  'pw:array-reorder': JsonFormEvent<JsonFormArrayEventDetail>;
-  'pw:serialize': JsonFormEvent<JsonFormSubmitDetail>;
-  'pw:submit': JsonFormEvent<JsonFormSubmitDetail>;
-  'pw:dialog-open': JsonFormEvent<JsonFormDialogEventDetail>;
-  'pw:dialog-submit': JsonFormEvent<JsonFormDialogEventDetail>;
-}
-
-declare global {
-  interface HTMLElementTagNameMap {
-    'pds-form': SchemaForm;
-  }
-}
-
-export class SchemaForm extends HTMLElement {
-  // Properties
-  jsonSchema: any;
-  uiSchema: UISchema;
-  options: JsonFormOptions;
-  values: any;
-  action?: string;
-  method: 'get' | 'post' | 'dialog';
-  disabled: boolean;
-  hideActions: boolean;
-  submitLabel: string;
-  resetLabel: string;
-  hideReset: boolean;
-  hideSubmit: boolean;
-
-  // Methods
-  defineRenderer(widgetKey: string, renderer: JsonFormRenderer): void;
-  useValidator(validator: (data: any, schema: any) => Promise<{ valid: boolean; errors?: Array<{ path?: string; message: string }> }>): void;
-  getValuesFlat(): Record<string, any>;
-  serialize(): { json: any; formData: FormData };
-  submit(): Promise<JsonFormSubmitDetail>;
-
-  // Event listeners
-  addEventListener<K extends keyof JsonFormEventMap>(
-    type: K,
-    listener: (ev: JsonFormEventMap[K]) => any,
-    options?: boolean | AddEventListenerOptions
-  ): void;
-  addEventListener(
-    type: string,
-    listener: EventListenerOrEventListenerObject,
-    options?: boolean | AddEventListenerOptions
-  ): void;
-  removeEventListener<K extends keyof JsonFormEventMap>(
-    type: K,
-    listener: (ev: JsonFormEventMap[K]) => any,
-    options?: boolean | EventListenerOptions
-  ): void;
-  removeEventListener(
-    type: string,
-    listener: EventListenerOrEventListenerObject,
-    options?: boolean | EventListenerOptions
-  ): void;
-}
+/**
+ * Public PDS runtime object exported to consumers.
+ *
+ * This object exposes the core runtime building blocks for the Pure Design System.
+ * It intentionally provides a small, stable surface area so consuming apps can:
+ * - programmatically generate design system artifacts (via `Generator`),
+ * - adopt styles into Shadow DOM (via `adoptLayers` / `adoptPrimitives`),
+ * - query runtime mode and obtain constructable stylesheets (via `registry`).
+ *
+ * Common events in the PDS ecosystem (emitted by other packages/components):
+ * - `design-updated` — emitted by the designer component when the in-memory design changes (detail: { config }).
+ * - `pds-generated` — emitted by the PDS configurator when generation completes (detail: { modules, meta }).
+ * - `pds-error` — emitted by the PDS configurator when generation fails (detail: Error).
+ *
+ * Error handling notes:
+ * - Methods that perform dynamic imports (e.g. `adoptLayers` via the registry) may log and return fallbacks
+ *   rather than throwing; consumers should check return values (e.g. null) and listen for `pds-error` in UI flows.
+ * - `createStylesheet(css)` will throw synchronously if the provided CSS cannot be parsed by the browser's
+ *   `CSSStyleSheet.replaceSync()` — callers should guard invalid input or wrap calls in try/catch.
+ */
+export type PDSAPI = {
+    /**
+     * - Generator class to produce design system assets
+     */
+    Generator: typeof import("./pds-core/pds-generator.js").Generator;
+    /**
+     * - Singleton runtime registry for live/static mode
+     */
+    registry: import("./pds-core/pds-registry.js").PDSRegistry;
+    /**
+     * - Ontology helpers and metadata for components
+     */
+    ontology: any;
+    /**
+     * - Adopt multiple layers into a ShadowRoot. May log errors and fallback to additionalSheets when static imports fail.
+     */
+    adoptLayers: (shadowRoot: ShadowRoot, layers?: string[], additionalSheets?: CSSStyleSheet[]) => Promise<void>;
+    /**
+     * - Adopt primitives layer into a ShadowRoot. Designed as a convenience for components.
+     */
+    adoptPrimitives: (shadowRoot: ShadowRoot, additionalSheets?: CSSStyleSheet[]) => Promise<void>;
+    /**
+     * - Create a constructable stylesheet from CSS text.
+     */
+    createStylesheet: (css: string) => CSSStyleSheet;
+};
+/** @type {PDSAPI & PDSBase} */
+export const PDS: PDSAPI & PDSBase;
+/**
+ * Validate a design configuration for accessibility sanity checks.
+ * Currently validates color contrast for primary buttons and base surface text
+ * in both light and dark themes.
+ *
+ * @param {object} designConfig - A full or partial PDS config object
+ * @param {object} [options]
+ * @param {number} [options.minContrast=4.5] - Minimum contrast ratio for normal text
+ * @returns {{ ok: boolean, issues: Array<{path:string, message:string, ratio:number, min:number, context?:string}> }}
+ */
+export function validateDesign(designConfig?: object, options?: {
+    minContrast?: number;
+}): {
+    ok: boolean;
+    issues: Array<{
+        path: string;
+        message: string;
+        ratio: number;
+        min: number;
+        context?: string;
+    }>;
+};
+/**
+ * Public PDS runtime object exported to consumers.
+ *
+ * This object exposes the core runtime building blocks for the Pure Design System.
+ * It intentionally provides a small, stable surface area so consuming apps can:
+ * - programmatically generate design system artifacts (via `Generator`),
+ * - adopt styles into Shadow DOM (via `adoptLayers` / `adoptPrimitives`),
+ * - query runtime mode and obtain constructable stylesheets (via `registry`).
+ *
+ * Common events in the PDS ecosystem (emitted by other packages/components):
+ * - `design-updated` — emitted by the designer component when the in-memory design changes (detail: { config }).
+ * - `pds-generated` — emitted by the PDS configurator when generation completes (detail: { modules, meta }).
+ * - `pds-error` — emitted by the PDS configurator when generation fails (detail: Error).
+ *
+ * Error handling notes:
+ * - Methods that perform dynamic imports (e.g. `adoptLayers` via the registry) may log and return fallbacks
+ *   rather than throwing; consumers should check return values (e.g. null) and listen for `pds-error` in UI flows.
+ * - `createStylesheet(css)` will throw synchronously if the provided CSS cannot be parsed by the browser's
+ *   `CSSStyleSheet.replaceSync()` — callers should guard invalid input or wrap calls in try/catch.
+ *
+ * @typedef {Object} PDSAPI
+ * @property {typeof import("./pds-core/pds-generator.js").Generator} Generator - Generator class to produce design system assets
+ * @property {import("./pds-core/pds-registry.js").PDSRegistry} registry - Singleton runtime registry for live/static mode
+ * @property {any} ontology - Ontology helpers and metadata for components
+ * @property {(shadowRoot: ShadowRoot, layers?: string[], additionalSheets?: CSSStyleSheet[]) => Promise<void>} adoptLayers - Adopt multiple layers into a ShadowRoot. May log errors and fallback to additionalSheets when static imports fail.
+ * @property {(shadowRoot: ShadowRoot, additionalSheets?: CSSStyleSheet[]) => Promise<void>} adoptPrimitives - Adopt primitives layer into a ShadowRoot. Designed as a convenience for components.
+ * @property {(css:string) => CSSStyleSheet} createStylesheet - Create a constructable stylesheet from CSS text. @throws {DOMException} on invalid CSS in some browsers.
+ * @property {() => boolean} isLiveMode - Returns true when running in live/designer-backed mode
+ * @property {(el: Element) => import("./pds-core/pds-ontology.js").ComponentDef | null} findComponentForElement - Helper to find a component definition for a DOM element
+ */
+/**
+ * Workspace for the Pure Design System runtime API
+ * PDS is now an EventTarget so consumers can subscribe to a single, consistent
+ * event bus instead of listening on window/document or individual elements.
+ */
+declare class PDSBase extends EventTarget {
+}
+export {};
+//# sourceMappingURL=pds.d.ts.map

package/dist/types/src/js/common/toast.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Display a toast notification
+ *
+ * This method automatically ensures the pds-toaster component exists and is loaded
+ * before displaying the notification. The toaster element is appended to document.body
+ * if not already present.
+ *
+ * @param {string} message - The message to display
+ * @param {Object} [options={}] - Toast configuration
+ * @param {"information"|"success"|"warning"|"error"} [options.type="information"] - Toast type/severity
+ * @param {number} [options.duration] - Duration in milliseconds (auto-calculated if not provided based on message length)
+ * @param {boolean} [options.closable=true] - Whether the toast can be manually closed
+ * @param {boolean} [options.persistent=false] - If true, toast won't auto-dismiss (requires manual close)
+ * @returns {Promise<string>} Toast ID (can be used to dismiss programmatically)
+ *
+ * @example
+ * // Simple success toast
+ * await PDS.toast('Changes saved successfully!', { type: 'success' });
+ *
+ * @example
+ * // Error with custom duration
+ * await PDS.toast('Failed to save changes', {
+ *   type: 'error',
+ *   duration: 8000
+ * });
+ *
+ * @example
+ * // Persistent warning (must be manually closed)
+ * await PDS.toast('This action cannot be undone', {
+ *   type: 'warning',
+ *   persistent: true
+ * });
+ *
+ * @example
+ * // Get toast ID to dismiss later
+ * const toastId = await PDS.toast('Processing...', { persistent: true });
+ * // ... later
+ * const toaster = document.querySelector('pds-toaster');
+ * toaster.dismissToast(toastId);
+ */
+export function toast(message: string, options?: {
+    type?: "information" | "success" | "warning" | "error";
+    duration?: number;
+    closable?: boolean;
+    persistent?: boolean;
+}): Promise<string>;
+export namespace toast {
+    /**
+     * Display a success toast (convenience method)
+     *
+     * @param {string} message - The success message
+     * @param {Object} [options={}] - Additional toast options (type is preset to 'success')
+     * @returns {Promise<string>} Toast ID
+     *
+     * @example
+     * await PDS.toast.success('Profile updated!');
+     */
+    function success(message: string, options?: any): Promise<string>;
+    /**
+     * Display an error toast (convenience method)
+     *
+     * @param {string} message - The error message
+     * @param {Object} [options={}] - Additional toast options (type is preset to 'error')
+     * @returns {Promise<string>} Toast ID
+     *
+     * @example
+     * await PDS.toast.error('Failed to connect to server');
+     */
+    function error(message: string, options?: any): Promise<string>;
+    /**
+     * Display a warning toast (convenience method)
+     *
+     * @param {string} message - The warning message
+     * @param {Object} [options={}] - Additional toast options (type is preset to 'warning')
+     * @returns {Promise<string>} Toast ID
+     *
+     * @example
+     * await PDS.toast.warning('Session will expire in 5 minutes');
+     */
+    function warning(message: string, options?: any): Promise<string>;
+    /**
+     * Display an information toast (convenience method)
+     *
+     * @param {string} message - The information message
+     * @param {Object} [options={}] - Additional toast options (type is preset to 'information')
+     * @returns {Promise<string>} Toast ID
+     *
+     * @example
+     * await PDS.toast.info('New features available!');
+     */
+    function info(message: string, options?: any): Promise<string>;
+}
+//# sourceMappingURL=toast.d.ts.map

package/dist/types/src/js/common/toast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toast.d.ts","sourceRoot":"","sources":["../../../../../src/js/common/toast.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,+BAjCW,MAAM,YAEd;IAA4D,IAAI,GAAxD,aAAa,GAAC,SAAS,GAAC,SAAS,GAAC,OAAO;IACxB,QAAQ,GAAzB,MAAM;IACY,QAAQ,GAA1B,OAAO;IACW,UAAU,GAA5B,OAAO;CACf,GAAU,OAAO,CAAC,MAAM,CAAC,CA8B3B;;IAED;;;;;;;;;OASG;IACH,0BAPW,MAAM,kBAEJ,OAAO,CAAC,MAAM,CAAC,CAO3B;IAED;;;;;;;;;OASG;IACH,wBAPW,MAAM,kBAEJ,OAAO,CAAC,MAAM,CAAC,CAO3B;IAED;;;;;;;;;OASG;IACH,0BAPW,MAAM,kBAEJ,OAAO,CAAC,MAAM,CAAC,CAO3B;IAED;;;;;;;;;OASG;IACH,uBAPW,MAAM,kBAEJ,OAAO,CAAC,MAAM,CAAC,CAO3B"}

package/dist/types/src/js/pds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pds.d.ts","sourceRoot":"","sources":["../../../../src/js/pds.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;eAuBc,cAAc,6BAA6B,EAAE,SAAS;;;;cACtD,OAAO,4BAA4B,EAAE,WAAW;;;;cAChD,GAAG;;;;iBACH,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,gBAAgB,CAAC,EAAE,aAAa,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC;;;;qBAChG,CAAC,UAAU,EAAE,UAAU,EAAE,gBAAgB,CAAC,EAAE,aAAa,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC;;;;sBAC7E,CAAC,GAAG,EAAC,MAAM,KAAK,aAAa;;AAW3C,+BAA+B;AAC/B,kBADW,MAAM,GAAG,OAAO,CACD;AA2R1B;;;;;;;;;GASG;AACH,8CALW,MAAM,YAEd;IAAyB,WAAW,GAA5B,MAAM;CACd,GAAU;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC;QAAC,IAAI,EAAC,MAAM,CAAC;QAAC,OAAO,EAAC,MAAM,CAAC;QAAC,KAAK,EAAC,MAAM,CAAC;QAAC,GAAG,EAAC,MAAM,CAAC;QAAC,OAAO,CAAC,EAAC,MAAM,CAAA;KAAC,CAAC,CAAA;CAAE,CAyIpH;AAldD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;GAIG;AACH;CAAoC"}
+{"version":3,"file":"pds.d.ts","sourceRoot":"","sources":["../../../../src/js/pds.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;eAuBc,cAAc,6BAA6B,EAAE,SAAS;;;;cACtD,OAAO,4BAA4B,EAAE,WAAW;;;;cAChD,GAAG;;;;iBACH,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,gBAAgB,CAAC,EAAE,aAAa,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC;;;;qBAChG,CAAC,UAAU,EAAE,UAAU,EAAE,gBAAgB,CAAC,EAAE,aAAa,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC;;;;sBAC7E,CAAC,GAAG,EAAC,MAAM,KAAK,aAAa;;AAW3C,+BAA+B;AAC/B,kBADW,MAAM,GAAG,OAAO,CACD;AA6R1B;;;;;;;;;GASG;AACH,8CALW,MAAM,YAEd;IAAyB,WAAW,GAA5B,MAAM;CACd,GAAU;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC;QAAC,IAAI,EAAC,MAAM,CAAC;QAAC,OAAO,EAAC,MAAM,CAAC;QAAC,KAAK,EAAC,MAAM,CAAC;QAAC,GAAG,EAAC,MAAM,CAAC;QAAC,OAAO,CAAC,EAAC,MAAM,CAAA;KAAC,CAAC,CAAA;CAAE,CAyIpH;AApdD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;GAIG;AACH;CAAoC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pure-ds/core",
   "shortname": "pds",
-  "version": "0.4.24",
+  "version": "0.4.25",
   "description": "Pure Design System - Why develop a Design System when you can generate one?",
   "repository": {
     "type": "git",

package/src/js/pds.d.ts

@@ -154,6 +154,68 @@ export class PDS extends EventTarget {
   static validateDesign: (designConfig: any, options?: { minContrast?: number }) => { ok: boolean; issues: Array<{ path: string; message: string; ratio: number; min: number; context?: string }> };
   static validateDesigns: (designs: Array<any> | Record<string, any>, options?: { minContrast?: number }) => { ok: boolean; results: Array<{ name?: string; ok: boolean; issues: Array<{ path: string; message: string; ratio: number; min: number; context?: string }> }> };
   
+  /**
+   * Display a toast notification.
+   * 
+   * Automatically ensures the pds-toaster component exists and is loaded before displaying.
+   * 
+   * @param message - The message to display
+   * @param options - Toast configuration
+   * @param options.type - Toast type/severity ("information" | "success" | "warning" | "error")
+   * @param options.duration - Duration in milliseconds (auto-calculated if not provided)
+   * @param options.closable - Whether toast can be manually closed (default: true)
+   * @param options.persistent - If true, toast won't auto-dismiss (default: false)
+   * @returns Toast ID (can be used to dismiss programmatically)
+   * 
+   * @example
+   * await PDS.toast('Changes saved!', { type: 'success' });
+   * 
+   * @example
+   * await PDS.toast('Error occurred', { type: 'error', persistent: true });
+   */
+  static toast(
+    message: string,
+    options?: {
+      type?: 'information' | 'success' | 'warning' | 'error';
+      duration?: number;
+      closable?: boolean;
+      persistent?: boolean;
+    }
+  ): Promise<string>;
+  
+  /**
+   * Display a success toast (convenience method).
+   * 
+   * @param message - The success message
+   * @param options - Additional toast options (type is preset to 'success')
+   * @returns Toast ID
+   * 
+   * @example
+   * await PDS.toast.success('Profile updated!');
+   */
+  static toast: {
+    (message: string, options?: { type?: 'information' | 'success' | 'warning' | 'error'; duration?: number; closable?: boolean; persistent?: boolean }): Promise<string>;
+    success(message: string, options?: { duration?: number; closable?: boolean; persistent?: boolean }): Promise<string>;
+    error(message: string, options?: { duration?: number; closable?: boolean; persistent?: boolean }): Promise<string>;
+    warning(message: string, options?: { duration?: number; closable?: boolean; persistent?: boolean }): Promise<string>;
+    info(message: string, options?: { duration?: number; closable?: boolean; persistent?: boolean }): Promise<string>;
+  };
+  
+  /**
+   * Display a modal dialog for user input or confirmation.
+   * 
+   * @param message - The message or prompt to display
+   * @param options - Dialog configuration
+   * @returns User's response (string for prompt, boolean for confirm, true for alert)
+   * 
+   * @example
+   * const confirmed = await PDS.ask('Delete this item?', { type: 'confirm' });
+   * 
+   * @example
+   * const name = await PDS.ask('Enter your name:', { type: 'prompt' });
+   */
+  static ask(message: string, options?: any): Promise<any>;
+  
   /** 
    * Current configuration after PDS.start() completes - read-only, frozen after initialization.
    * Contains the complete configuration used to initialize PDS, including mode, design, preset, and theme.

package/src/js/pds.js

@@ -56,6 +56,7 @@ import { findComponentForElement } from "./pds-core/pds-ontology.js";
 import { presets, defaultLog } from "./pds-core/pds-config.js";
 import { enums } from "./pds-core/pds-enums.js";
 import { ask } from "./common/ask.js";
+import { toast } from "./common/toast.js";
 import { PDSQuery } from "./pds-core/pds-query.js";
 import * as common from "./common/common.js";
 import { defaultPDSEnhancers } from "./pds-core/pds-enhancers.js";
@@ -87,6 +88,7 @@ PDS.isLiveMode = () => registry.isLive;
 PDS.enums = enums;
 
 PDS.ask = ask;
+PDS.toast = toast;
 
 // Expose common utilities (deepMerge, isObject, etc.)
 PDS.common = common;