widgets/Input/index.js
Functions
getInputWidget(id)
getAllInputWidgets()
Constants
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Input Widgets Category User input and data entry widgets Functions Constants <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Layout/Collapse.js
Classes
class Collapse extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Collapse Collapsible content widget for Plauna Provides collapsible/expandable content areas with smooth animations Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Layout/Container.js
Classes
class Container extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Container Layout container widget for Plauna Provides flexible container with multiple variants and layouts Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Layout/Divider.js
Classes
class Divider extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Divider Visual separation widget for Plauna Provides orientation variants with text label support Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Layout/Grid.js
Classes
class Grid extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Grid CSS Grid wrapper widget for Plauna Provides responsive breakpoints and template areas support Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Layout/HeaderFooter.js
Classes
class HeaderFooter extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: HeaderFooter Header and Footer widget for Plauna Provides semantic header and footer containers with comprehensive styling options Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Layout/Panel.js
Classes
class Panel extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Panel Content panel widget for Plauna Provides panel containers with various styles and configurations Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Layout/Section.js
Classes
class Section extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Section Content section widget for Plauna Provides semantic section containers with layout and styling options Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Layout/Spacer.js
Classes
class Spacer extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Spacer Flexible spacing utility widget for Plauna Provides flexible sizing with token integration Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Layout/index.js
Functions
getLayoutWidget(id)
getAllLayoutWidgets()
Constants
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Layout Widgets Category Layout and container widgets Functions Constants <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Navigation/Breadcrumb.js
Classes
class Breadcrumb extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Breadcrumb Navigation hierarchy widget for Plauna Provides breadcrumb navigation with customizable separators Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Navigation/Dropdown.js
Classes
class Dropdown extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Dropdown Context menu widget for Plauna Provides dropdown menus with keyboard navigation and accessibility Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Navigation/Menu.js
Classes
class Menu extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Menu Navigation menu widget for Plauna Provides menu functionality with multiple variants and states Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Navigation/Navbar.js
Classes
class Navbar extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Navbar Navigation bar widget for Plauna Provides navbar functionality with multiple variants and layouts Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Navigation/Pagination.js
Classes
class Pagination extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Pagination Data navigation widget for Plauna Provides page controls with ellipsis and keyboard navigation Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Navigation/Sidebar.js
Classes
class Sidebar extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Sidebar Sidebar navigation widget for Plauna Provides sidebar functionality with multiple variants and states Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Navigation/Stepper.js
Classes
class Stepper extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Stepper Step indicator widget for Plauna Provides stepper functionality with multiple variants and states Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Navigation/Tabs.js
Classes
class Tabs extends UINode
Constants
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Tabs Tab navigation widget for Plauna Provides tabbed interface with keyboard navigation and styling Classes Method Signature Summary Constants <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Navigation/index.js
Functions
getNavigationWidget(id)
getAllNavigationWidgets()
Constants
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Navigation Widgets Category Navigation and menu widgets Functions Constants <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Primitive/Avatar.js
Classes
class Avatar extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Avatar User representation widget for Plauna Provides image, icon, and text fallback with status indicators Classes Method Signature Summary Setup modern avatar surface styling. Modern design pattern: soft card like surface with subtle border and shadow. Border provides definition without harshness Box shadow adds depth and lift from background Backdrop filter creates glassy blur effect behind avatar Transitions are set on transform, shadow, border, and background for smooth state changes This treatment aligns with modern avatar/profile patterns that use subtle elevation rather than flat colors, making the avatar feel more tactile and interactive. Get size specific dimensions and typography. Size scale follows modern UI conventions with consistent spacing: xs: 24px Small avatars for compact lists (e.g., user menus) sm: 32px Small avatars for inline mentions md: 40px Default size for most use cases lg: 48px Large avatars for profile headers xl: 64px Extra large for hero sections 2xl: 96px Extra extra large for detailed profile views Font size scales proportionally with container size for consistent visual weight across all sizes. Get shape specific border radius values. Shape variants provide flexibility for different UI contexts: circle: 50% border radius for classic circular profile images square: Small border radius for modern card like avatars rounded: Medium border radius for softer square profiles Uses design tokens for consistent border radius values across the entire UI system. Setup modern interaction event handlers. Implements modern accessibility and interaction patterns: Hover state: subtle scale up and shadow elevation for tactile feedback Focus state: clear focus


Implements modern accessibility and interaction patterns: Hover state: subtle scale up and shadow elevation for tactile feedback Focus state: clear focus ring with primary color for keyboard navigation visibility Base shadow is restored on blur to maintain modern surface appearance Border is preserved across states (not cleared on blur) for consistent definition The focus ring uses a dual layer shadow (outer ring + inner shadow) for high visibility against both light and dark backgrounds, following WCAG 2.1 guidelines. Build the avatar's DOM structure. Layered structure for flexible avatar rendering: 1. Container: Base element with surface styling and event handlers 2. Content layer: Image, icon, or initials (mutually exclusive) 3. Status indicator: Optional dot in corner for presence (online/offline/busy) This pattern allows avatars to gracefully degrade from images to icons to text based on availability and preferences. Load avatar image asynchronously. Async image loading pattern with error handling: Creates Image object to preload image before rendering Sets onload handler to mark image as loaded and update content Sets onerror handler to fall back to initials/icon/placeholder Updates dirty flags to trigger re render when image loads or fails This pattern ensures avatars always display something, even if the image fails to load or the network is slow. Handle image loading errors. Fallback strategy when image fails to load: Marks image as not loaded and error state Triggers content update to fall back to initials/icon/placeholder Updates dirty flags to re render with fallback content This follows the progressive enhancement pattern: try the best option (image), then fall back to alternatives (initials, icon, placeholder). Generate accessible label for screen readers.


enhancement pattern: try the best option (image), then fall back to alternatives (initials, icon, placeholder). Generate accessible label for screen readers. Modern accessibility pattern: uses fallback chain for descriptive labels. Prefers explicit name (user's display name) Falls back to alt text (image description) Falls back to initials (generated from name) for avatars without alt Includes shape for context (circle/square/rounded) Includes status for presence information This ensures screen readers always have meaningful text even when images fail to load or alt text is omitted, following WCAG 2.1 guidelines. <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount


widgets/Primitive/Badge.js
Classes
class Badge extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Badge Status indicator widget for Plauna Provides status indicators, counts, and labels with variants Classes Method Signature Summary Setup modern badge surface styling. Badge surface pattern for status indicators: Inline flex for proper alignment with text Font weight medium for clear visibility Transitions for smooth state changes User select none to prevent text selection Default cursor (badges are typically non interactive) Badges are designed to be small status indicators that can be placed inline with text or positioned absolutely on elements. <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Primitive/Button.js
Classes
class Button extends UINode
Constants
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Button Interactive button widget for Plauna Provides clickable button with styling, states, and event handling Classes Method Signature Summary Build button content with optional icon and text. Content structure pattern for flexible button rendering: Clear existing children first Add icon on left if specified and iconPosition is 'left' Add text content (or loading spinner) Add icon on right if specified and iconPosition is 'right' This pattern supports icons on either side of the text, or text only buttons, or icon only buttons. Get variant specific styling with semantic meaning. Variant system provides semantic visual feedback for different actions: primary: Main action, high emphasis with solid primary color secondary: Secondary action, medium emphasis with background color outline: Low emphasis, border only style with primary color ghost: Minimal emphasis, text only style with primary color danger: Destructive action, error color for caution warning: Cautionary action, warning color for attention success: Positive action, success color for confirmation Disabled state is handled uniformly across all variants: Reduced opacity (0.6) for visual de emphasis Removed shadow for flat appearance Neutral background color Changed cursor to not allowed Get minimum width for each button size. Modern accessibility pattern: ensures touch targets meet WCAG 2.1 minimum 44x44px recommendation for better mobile usability. sm: 36px (smaller compact buttons) md: 44px (default, meets accessibility minimum) lg: 52px (large touch targets) Get minimum height for each button size. Modern accessibility pattern: ensures touch targets meet WCAG 2.1 minimum 44x44px recommendation for better mobile


Get minimum height for each button size. Modern accessibility pattern: ensures touch targets meet WCAG 2.1 minimum 44x44px recommendation for better mobile usability. sm: 32px (slightly below minimum for compact layouts) md: 40px (near minimum, comfortable for most users) lg: 44px (meets accessibility minimum for large buttons) Activate button (trigger click action). Activation pattern for button interaction: Early return if disabled or loading to prevent accidental activation Creates synthetic click event with preventDefault support Dispatches event for parent components to handle Calls onClick callback if provided This pattern allows buttons to be activated programmatically (e.g., by keyboard Enter/Space) with the same behavior as mouse clicks. Constants <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Primitive/Chip.js
Classes
class Chip extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Chip/Tag Removable tag widget for Plauna Provides chip functionality with multiple variants and states Classes Method Signature Summary Get variant specific styles with alpha transparent colors. Modern alpha transparent variant pattern: Uses RGBA colors with low opacity for backgrounds Stronger opacity for borders for definition Works across both light and dark themes without theme specific values Semantic colors: primary, secondary, success, warning, error Alpha transparency allows chips to work as overlays on any background while maintaining semantic meaning through color hue. Get background color based on variant and disabled state. Color cascade pattern: Disabled state: neutral tertiary background Enabled state: variant specific color from design tokens Falls back to default if variant is unknown Uses design tokens for theme consistency while allowing variant specific semantic coloring. Get text color based on variant and disabled state. Color cascade pattern: Disabled state: disabled text color Enabled state: variant specific color with contrast awareness Success/warning/error variants use inverse text for readability Ensures text remains readable against variant backgrounds by using appropriate contrast ratios. Get border color based on variant and disabled state. Color cascade pattern: Disabled state: subtle border for de emphasis Enabled state: variant specific border for definition Primary/success/warning/error use colored borders Borders provide definition even on similar colored backgrounds, helping chips stand out in dense UI layouts. Build the chip's flexible DOM structure. Flexible chip structure pattern: 1. Container: Base element with pill styling and event


stand out in dense UI layouts. Build the chip's flexible DOM structure. Flexible chip structure pattern: 1. Container: Base element with pill styling and event handlers 2. Avatar (optional): Small user avatar on the left 3. Icon (optional): Icon on the left if no avatar 4. Label: Text content in the center 5. Remove button (optional): Dismissible action on the right This structure supports various chip types: Simple text chips (label only) Avatar chips (avatar + label) Icon chips (icon + label) Removable chips (label + remove button) Combined chips (avatar + label + remove button) Create avatar sub component for chip. Sub component pattern: Creates UINode for avatar with appropriate styling Uses size based dimensions that scale with chip size Circular border radius for consistent profile appearance Object fit cover for proper image scaling Create icon sub component for chip. Sub component pattern: Creates UINode for icon with text content Inherits font size from parent for consistent scaling Flex layout for proper alignment with label Create remove button sub component for chip. Sub component pattern: Creates UINode for dismissible action button Uses × (multiplication sign) as universal close icon Sets up click handler to trigger onRemove callback Dispatches 'remove' event for parent component handling Update visual state based on hover and disabled conditions. Modern interaction pattern: Hover: subtle lift (translateY) and elevated shadow for tactile feedback Idle: maintains base shadow (var( shadow sm)) for modern surface appearance Disabled: reduced opacity and not allowed cursor The base shadow is preserved when not hovered to maintain the modern pill surface treatment across interaction states. <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and


not hovered to maintain the modern pill surface treatment across interaction states. <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Primitive/Modal.js
Classes
class Modal extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Modal Overlay dialog widget for Plauna Provides modal dialogs with focus trapping, accessibility, and backdrop Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Primitive/Panel.js
Classes
class Panel extends UINode
Constants
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Panel Basic container widget for Plauna Provides a container for other UI elements with styling and layout options Classes Method Signature Summary Constants <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Primitive/Progress.js
Classes
class Progress extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Progress Task completion indicator widget for Plauna Provides linear and circular progress indicators with multiple states Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Primitive/Skeleton.js
Classes
class Skeleton extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Skeleton Content loading placeholder widget for Plauna Provides loading placeholders with realistic shapes and shimmer animation Classes Method Signature Summary Get shimmer animation styles for loading effect. Modern shimmer animation pattern: Static: Solid background color when animation is disabled Animated: Linear gradient moving across the background Background size 200% allows gradient to slide across Animation duration 1.5s for smooth, non distracting motion willChange hint for GPU acceleration The gradient moves from quaternary → secondary → quaternary colors, creating a light sweep effect that indicates content is loading. <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Primitive/Text.js
Classes
class Text extends UINode
Constants
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Text Basic text widget for Plauna Provides text rendering with styling and layout options Classes Method Signature Summary Constants <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/Primitive/Tooltip.js
Classes
class Tooltip extends UINode
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Tooltip Contextual help widget for Plauna Provides positioning engine with arrow support and accessibility Classes Method Signature Summary <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/WidgetConfig.js

class UnsupportedWidgetConfigVersionError extends Error

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Widget Configuration System Manages widget configurations, presets, and user preferences Following the same pattern as the editor's theme system Classes Method Signature Summary Functions Constants — Singleton export for WidgetConfigManager. Ensures a single instance is used throughout the application: Consistent configuration state across all components Single storage persistence point Centralized event notification system <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/WidgetItem.js

widgets/WidgetItem.js
Classes
class MyWidget extends WidgetItem
class WidgetItem
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: WidgetItem Base class for all Plauna widgets. Follows the same pattern as SpawnableItem from the editor: Static properties for metadata Static methods for configuration Registry based discovery Category based organization Classes Method Signature Summary WidgetItem Base class for all Plauna widgets. Follows the same pattern as SpawnableItem from the editor: Static properties for metadata Static methods for configuration Registry based discovery Category based organization Method Signature Summary Default widget options Widget theme tokens configuration Widget event handlers configuration Create widget instance Validate widget options Get widget metadata Check if widget supports a specific event Get widget documentation <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/WidgetRenderer.js

widgets/WidgetRenderer.js
Classes
class WidgetRenderer
Constants
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ============================================================================ WidgetRenderer UINode to DOM Converter ============================================================================ WidgetRenderer is the bridge between Plauna's retained UINode tree and the actual browser DOM. It converts UINode instances into DOM elements recursively. RENDERING PIPELINE: 1. render(node) Entry point, converts UINode tree to DOM tree 2. createDOMElement(node) Creates appropriate DOM element for UINode type 3. Applies styles, classes, IDs, text content, and attributes 4. Recursively renders children and appends to parent 5. Returns root DOM element ready for insertion into document MAPPING TABLES: nodeToDOM: Map<UINode, HTMLElement UINode → DOM element domToNode: Map<HTMLElement, UINode DOM element → UINode (reverse lookup) ELEMENT TYPE MAPPING: SVG elements: svg, circle, path, etc. → created with createElementNS Text nodes: type='text' → rendered as <span Form elements: button, input, textarea, select, label, form, img → native elements HTML elements: h1 h6, p, div, header, footer, nav, etc. → native elements Unknown types: fallback to <div SPECIAL HANDLING: Raw HTMLElements: If node is already an HTMLElement, return it directly Pre existing DOM: If node.element exists (created by widget), use it Back reference: Sets element. plaunaNode for reverse lookup (used by SmartContextMenu) STYLE APPLICATION: 1. node.style: Direct inline styles (highest priority) 2. node.computedStyle: Computed styles from layout engine 3. node.className: CSS class names 4. node.id: Element ID TEXT CONTENT: node.textContent: Plain text content node.innerHTML: HTML string content If node has children, text content


widgets/WidgetRenderer.js

class names 4. node.id: Element ID TEXT CONTENT: node.textContent: Plain text content node.innerHTML: HTML string content If node has children, text content is ignored Classes ============================================================================ WidgetRenderer UINode to DOM Converter ============================================================================ WidgetRenderer is the bridge between Plauna's retained UINode tree and the actual browser DOM. It converts UINode instances into DOM elements recursively. RENDERING PIPELINE: 1. render(node) Entry point, converts UINode tree to DOM tree 2. createDOMElement(node) Creates appropriate DOM element for UINode type 3. Applies styles, classes, IDs, text content, and attributes 4. Recursively renders children and appends to parent 5. Returns root DOM element ready for insertion into document MAPPING TABLES: nodeToDOM: Map<UINode, HTMLElement UINode → DOM element domToNode: Map<HTMLElement, UINode DOM element → UINode (reverse lookup) ELEMENT TYPE MAPPING: SVG elements: svg, circle, path, etc. → created with createElementNS Text nodes: type='text' → rendered as <span Form elements: button, input, textarea, select, label, form, img → native elements HTML elements: h1 h6, p, div, header, footer, nav, etc. → native elements Unknown types: fallback to <div SPECIAL HANDLING: Raw HTMLElements: If node is already an HTMLElement, return it directly Pre existing DOM: If node.element exists (created by widget), use it Back reference: Sets element. plaunaNode for reverse lookup (used by SmartContextMenu) STYLE APPLICATION: 1. node.style: Direct inline styles (highest priority) 2. node.computedStyle: Computed styles from layout engine 3. node.className: CSS class names 4. node.id: Element ID TEXT CONTENT: node.textContent: Plain


widgets/WidgetRenderer.js

2. node.computedStyle: Computed styles from layout engine 3. node.className: CSS class names 4. node.id: Element ID TEXT CONTENT: node.textContent: Plain text content node.innerHTML: HTML string content If node has children, text content is ignored Method Signature Summary Render a UINode widget tree to DOM Create DOM element from UINode Update existing DOM element from UINode Get DOM element for a node Unmount and clean up a rendered widget Clear all mappings Constants <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the edi


widgets/WidgetStyleManager.js

widgets/WidgetStyleManager.js
Classes
class WidgetStyleManager
Constants
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: WidgetStyleManager Widget specific styling system Provides theme based styling utilities for widgets and UI components Classes WidgetStyleManager Theme aware widget styling system. Architecture pattern: Singleton pattern for consistent styling across the application Style caching for performance (memoization by widgetType:variant:theme) Theme integration with ThemeManager for dynamic theme switching Observer pattern for reactive style updates on theme changes Base token fallback for graceful degradation Features: Generates CSS styles based on theme tokens Supports multiple widget types (modal, tooltip, dropdown, etc.) Automatic cache invalidation on theme changes Token based styling for consistency Method Signature Summary Get widget styles based on type, variant, and current theme. Caching pattern for performance: Cache key format: widgetType:variant:theme Returns cached styles if available (O(1) lookup) Generates and caches new styles on cache miss Cache is cleared on theme changes to ensure consistency Generate widget styles based on theme tokens Generate modal component styles Generate tooltip component styles Generate dropdown component styles Generate card component styles Generate avatar component styles Generate breadcrumb component styles Generate pagination component styles Generate widget container styles Generate default fallback styles Get base tokens as fallback. Fallback pattern for graceful degradation: Provides default values when theme tokens are unavailable Ensures widgets render even without a theme Covers all token categories (colors, spacing, typography, etc.) Used as starting point, then merged with theme specific tokens Apply styles to element Create


widgets/WidgetStyleManager.js

Covers all token categories (colors, spacing, typography, etc.) Used as starting point, then merged with theme specific tokens Apply styles to element Create styled element Handle theme changes. Reactive update pattern: Clears style cache to force regeneration with new theme Notifies all observers of theme change Observers can re render with new styles Error handling for observer failures Subscribe to style changes Clear style cache Constants — Singleton export for WidgetStyleManager. Ensures a single instance is used throughout the application: Consistent style caching across all components Single theme subscription point Centralized style generation <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


widgets/index.js

createWidget(widgetId, container, options = {})

createWidgetWithTheme(widgetId, container, theme, options = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ============================================================================ PLAUNA WIDGET REGISTRY ============================================================================ This file serves as the central registry for all Plauna widgets. It imports widgets from their category folders and provides: 1. widgets array Flat array of all widget classes 2. widgetRegistry Map of widget.id → widget class for O(1) lookup 3. categories Map of category name → array of widgets in that category 4. Helper functions for querying and filtering widgets WIDGET CATEGORIES: Primitive: Basic building blocks (Button, Badge, Avatar, Chip, etc.) Input: Form input controls (Search, Color, Date, File, etc.) Form: Form elements (Checkbox, Radio, Switch, Select, etc.) Layout: Layout containers (Card, Grid, Panel, Divider, etc.) Navigation: Navigation components (Menu, Tabs, Sidebar, etc.) DataViews: Data presentation (List, Table, Tree, etc.) Feedback: User feedback (Alert, Toast, Spinner, etc.) WIDGET PATTERN: Each widget class MUST have: static id: Unique string identifier (e.g., 'button') static name: Display name (e.g., 'Button') static category: Category name (e.g., 'primitive') static icon: Emoji or icon for UI display static description: Short description of widget purpose static tags: Array of searchable tags static dependencies: Array of required widget IDs static getDefaultOptions(): Returns default configuration object static stories(): Returns named story configurations for showcase constructor(id, options): Initializes widget instance IMPORTANT: Do NOT use widget.create() it has require() that breaks in ESM Instead, instantiate directly: new WidgetClass(id, options) Use


widgets/index.js

widget instance IMPORTANT: Do NOT use widget.create() it has require() that breaks in ESM Instead, instantiate directly: new WidgetClass(id, options) Use widgetRegistry.get(id) to find widget class by ID Functions Constants <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


workspace/Panel.js

workspace/Panel.js
Classes
class Panel
class DOMPanel extends Panel
class GPUPanel extends Panel
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Panel.js — Base panel and two concrete flavours: DOMPanel — a positioned <div container for Plauna widgets / HTML content GPUPanel — owns a GPUTexture render target; blitted to canvas by WorkspaceCompositor Lifecycle: create → mount(container) → [resize / focus / show / hide] → destroy() Classes Panel Base class for workspace panels. Architecture pattern: Abstract base class for DOMPanel and GPUPanel Lifecycle: create → mount → [resize/focus/show/hide] → destroy Observer pattern for event emission (move, resize, visibility, focus, blur) Position/size constraints with min size enforcement Z index management for panel stacking Panel types: DOMPanel: Renders Plauna widgets in DOM elements GPUPanel: Renders to WebGPU textures, composited by WorkspaceCompositor Method Signature Summary Mount panel into container. Lifecycle hook called by Workspace.addPanel: Sets mounted flag to true Subclasses override to create DOM elements or GPU resources Called once per panel lifetime Destroy panel and release resources. Lifecycle cleanup: Sets mounted flag to false Clears all observers to prevent memory leaks Subclasses override to remove DOM elements or release GPU resources Update position (float layout). Update size — both DOM and GPU subclasses override to respond. Subscribe to panel events. Returns an unsubscribe function. Method Signature Summary Build the title bar icon element from , or null if none. Accepts an emoji/glyph (rendered as text) or an image/video URL (data:/blob:/http(s) with a known extension → <img /<video ). Kept self contained so Plauna has no dependency on the host shell. Update the title bar icon and rebuild the bar in place. Clamp (x,y) so a reachable strip of the


workspace/Panel.js

self contained so Plauna has no dependency on the host shell. Update the title bar icon and rebuild the bar in place. Clamp (x,y) so a reachable strip of the titlebar always stays inside the work area — prevents dragging/restoring a window fully off screen. Re clamp into the visible work area (e.g. after a viewport/resolution change). Full viewport transparent overlay installed for the duration of a drag or resize. It sits above every window's content — crucially above guest <iframe s, which otherwise swallow mousemove/mouseup the moment the cursor crosses them, freezing the gesture and making the window "jump" to catch up. The shield keeps all pointer events flowing to the document listeners until the gesture ends. Build the 8 resize handles (corners + edges) into the panel root. Each carries a direction string (n/s/e/w combos) consumed by onResizeStart. Resize from one edge/corner. is any combination of n/s/e/w. Holding Shift resizes symmetrically about the window's center so all sides change equally (the center stays fixed); otherwise the opposite edge stays anchored. Method Signature Summary Called by WorkspaceCompositor to hand over the GPU device. Called by WorkspaceCompositor each frame. <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full


workspace/Panel.js

command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


workspace/PanelLayout.js

workspace/PanelLayout.js
Classes
class LayoutEngine
Constants
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PanelLayout.js — Layout engine for arranging panels in a workspace. Modes: fullscreen — one panel fills the entire workspace float — panels are free position windows (drag/resize) split — tmux/VS Code style binary split tree (horizontal vertical) tile — auto arranged fixed grid Classes LayoutEngine Panel layout orchestration. Layout modes: fullscreen: First visible panel fills entire workspace float: Panels are free position windows with drag/resize split: Binary tree layout (like tmux/VS Code) with recursive splits tile: Auto arranged grid layout Architecture: Mode based layout dispatch (apply() switches between modes) Split tree cached for efficiency (reused if panels unchanged) Z index management for float mode (focused panel on top) Observer pattern for mode change notifications Method Signature Summary Apply layout to a list of panels. Constants <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


workspace/Workspace.js

workspace/Workspace.js
Classes
class Workspace
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Workspace.js — Virtual desktop for panels. Architecture: Virtual desktop that holds an ordered list of panels DOM layer that sits over WebGPU canvas LayoutEngine for panel arrangement (fullscreen/float/split/tile) WorkspaceManager handles switching between workspaces via CSS transitions Lifecycle: mount(container): Creates DOM layer and mounts panels activate(): Shows workspace (opacity 1, pointer events auto) deactivate(): Hides workspace (opacity 0, pointer events none) CSS transitions for smooth workspace switching Panel management: addPanel(): Adds panel to workspace and mounts it removePanel(): Removes panel from workspace Layout applied automatically on mount and resize Classes Workspace Virtual desktop container. Virtual desktop pattern: Each workspace is a separate DOM layer Workspaces are stacked with CSS z index Only one workspace active/visible at a time CSS opacity transitions for smooth switching Panels are mounted into workspace DOM layer Method Signature Summary Mount workspace into container element. Mounting pattern: Creates absolute positioned DOM layer Sets up CSS transitions for smooth switching Mounts all panels into the workspace layer Applies initial layout Sets up resize handler for layout re application CSS properties: opacity: 0 initially (activated via activate()) pointer events: none initially (enabled via activate()) willChange: opacity, transform for GPU acceleration Activate workspace (make visible and interactive). Activation pattern: Sets opacity to 1 for visibility Enables pointer events for interaction Applies translateZ(0) for GPU layer promotion Emits 'activated' event for observers Deactivate workspace (hide and disable interaction).


workspace/Workspace.js

events for interaction Applies translateZ(0) for GPU layer promotion Emits 'activated' event for observers Deactivate workspace (hide and disable interaction). Deactivation pattern: Sets opacity to 0 for invisibility Disables pointer events to prevent interaction Applies translateZ( 20px) for depth effect Emits 'deactivated' event for observers Add a panel to this workspace. Remove a panel from this workspace. Remove all panels. Get the currently focused panel (if any). Destroy this workspace and all its panels. <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


workspace/WorkspaceCompositor.js

workspace/WorkspaceCompositor.js
Classes
class WorkspaceCompositor
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: WorkspaceCompositor.js — WebGPU blit pipeline for GPU panels. Architecture: Each GPUPanel owns a GPUTexture render target Compositor blits all visible GPU panels onto canvas swap chain each frame DOM panels are rendered directly by browser (compositor only handles WebGPU) Simple blit shader: just copies texture to canvas Pipeline components: Sampler: Linear filtering for panel textures Bind group layout: Single texture binding (binding 0) Shader: Simple vertex + fragment shader for texture copy Blend state: Alpha blending for layered panels Render loop: Called by WorkspaceManager each frame Iterates visible GPU panels in z order Creates bind group per panel Issues draw call (6 vertices for quad) Classes WorkspaceCompositor WebGPU texture compositor. Compositor pattern: Blits GPU panel textures to canvas swap chain Handles only WebGPU panels (DOM panels rendered by browser) Simple texture copy pipeline (no post processing) Alpha blending for layered panel support Method Signature Summary Initialize the blit pipeline. Pipeline initialization: Creates sampler with linear filtering Creates bind group layout for texture binding Creates shader module with vertex + fragment stages Creates render pipeline with blend state Shader details: Vertex: Full screen quad (6 vertices) Fragment: Texture load at (0,0) for full texture copy Blend: Standard alpha blending for layered panels Compose all GPU panels onto the canvas. Hand off GPU device to panels (they need it to allocate textures). <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the


workspace/WorkspaceCompositor.js

Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


workspace/WorkspaceManager.js

workspace/WorkspaceManager.js
Classes
class WorkspaceManager
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ============================================================================ WorkspaceManager Virtual Desktop Management ============================================================================ WorkspaceManager provides a virtual desktop system for Plauna, allowing multiple workspaces with different layouts and panel configurations. WORKSPACE CONCEPT: A Workspace is a virtual desktop that holds panels Each workspace can have its own layout mode (fullscreen, float, split, tile) Workspaces are DOM layers stacked over the canvas Only one workspace is active/visible at a time PANEL TYPES: DOMPanel: Wrapper for Plauna widgets (div based) GPUPanel: WebGPU texture panel (for GPU accelerated content) LAYOUT MODES: fullscreen: One panel fills the entire workspace float: Draggable, resizable windows with z order split: Recursive binary tree layout (like tmux/VS Code) tile: Auto arranged grid layout COMPOSITOR: WorkspaceCompositor blits GPU panel textures to canvas swap chain Iterates visible GPU panels in z order Required for GPU panel support SWITCHER: WorkspaceSwitcher provides HUD overlay (Ctrl+ : Open workspace switcher Arrow keys: Navigate switcher Enter: Switch to selected workspace Escape: Close switcher USAGE: const manager = new WorkspaceManager({ container: document.body, device: gpuDevice, canvas: canvasElement, format: 'bgra8unorm' }); await manager.initialize(); const ws = manager.createWorkspace({ name: 'Main', layout: 'float' }); manager.switchTo(ws.id); manager.createPanel('dom', { title: 'Panel 1' }); Classes Method Signature Summary Initialize the manager. Initialization pattern: Creates WorkspaceCompositor for GPU panel blitting Sets up keyboard shortcuts (Ctrl+


workspace/WorkspaceManager.js

Method Signature Summary Initialize the manager. Initialization pattern: Creates WorkspaceCompositor for GPU panel blitting Sets up keyboard shortcuts (Ctrl+ createWorkspace createWorkspace(options = {}) switchTo async switchTo(id) removeWorkspace removeWorkspace(id) createPanel createPanel(type, options = {}) list list() getCompositor getCompositor() destroy destroy() onWorkspaceActivated onWorkspaceActivated(ws) onWorkspaceDeactivated onWorkspaceDeactivated(ws) setupKeyboardShortcuts setupKeyboardShortcuts() openSwitcher openSwitcher() on on(event, fn) emit emit(event, data)` <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


workspace/WorkspaceSwitcher.js

workspace/WorkspaceSwitcher.js
Classes
class WorkspaceSwitcher
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: WorkspaceSwitcher.js — HUD overlay for workspace switching. Architecture: Triggered by Ctrl+ class WorkspaceSwitcher constructor constructor(options) show show() hide hide() buildContent buildContent() buildWorkspaceCard buildWorkspaceCard(ws, idx) setupKeyboardNav setupKeyboardNav() teardownKeyboardNav teardownKeyboardNav() refreshSelection refreshSelection()` <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


workspace/index.js

workspace/index.js
Re-exports
Notes & Examples
App & widget lifecycle
App & widget lifecycle

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: plauna/workspace — Virtual desktop / multi panel system for Plauna. Exported classes: Panel, DOMPanel, GPUPanel Workspace WorkspaceManager WorkspaceCompositor WorkspaceSwitcher LayoutEngine, LayoutMode Re exports , , , , , , , , <! HUMAN NOTES Notes & Examples App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. See also: Plauna Architecture · Plauna Overview App & widget lifecycle Plauna apps and widgets follow a mount → update → unmount lifecycle; services (storage, command bus, theming) are injected rather than imported, so the same widget runs in the editor, the OS shell, and standalone. Example: Widget with full lifecycle See also: Plauna Architecture · Plauna Overview


AI Echo Artifact Studio

Choosing artifacts, files, and Live Patch

File-backed, versioned work products and safe generative previews for AI Echo. AI Echo Artifact Studio AI Echo can turn substantial responses into durable work products that open beside the conversation. Documents, code, data, tables, charts, declarative interfaces, and static web presentations remain ordinary WebGPU OS files under . The Files app can browse them, and ordinary deletion sends the complete artifact project to the Recycle Bin. Artifact Studio is separate from AI Echo Live Patch. Artifacts are user owned content. Live Patch is the reviewed, reversible way to promote selected content into an existing OS or browser surface. Interaction model 1. AI Echo calls a declared tool when a substantial work product should remain editable or previewable. 2. The Artifact Workspace validates the exact project, blocks likely secrets, writes an immutable revision, and verifies every file by SHA 256 readback. 3. Only a small revision qualified artifact reference travels through the executor, conversation record, and Navi task. It binds the artifact ID, exact revision, and SHA 256 content hash, so an older message never silently resolves to a newer edit. Provider prose never becomes canonical state. 4. The response shows an artifact card. Opening it reveals Artifact Studio without leaving the task. 5. Direct edits create another immutable revision with compare and swap protection. Stale editors receive a revision conflict instead of silently overwriting newer work. 6. Copy, download, revision restore, Recycle Bin, and Open in Files remain direct user actions. The Studio refreshes through the storage event stream already shared by Files, other apps, tabs, and workers. It does not create a second synchronization or locking layer. On disk contract Each artifact uses a locally


AI Echo Artifact Studio

shared by Files, other apps, tabs, and workers. It does not create a second synchronization or locking layer. On disk contract Each artifact uses a locally generated identifier. Models choose content and metadata, but they never choose an OS path. The files directly inside are the current, manageable working projection shown by Files and Artifact Studio. Logical project paths such as , , and stay modular; they are not flattened or hidden under an opaque revision key. and are reserved OS owned metadata directories and cannot be supplied by a model as content. is the atomically advanced pointer. A revision records its parent revision, parent content hash, entrypoint, file descriptors, source provenance, and aggregate content hash. The manifest retains a bounded history of committed revisions. Artifact Workspace first writes and verifies the immutable revision, then publishes and verifies the direct working projection, and advances last. A crash may leave unreferenced derived files or a revision directory, but cannot replace the last committed pointer with partially written canonical content. Canonical reads continue to verify the immutable revision and its root level projection independently. This boundary follows the browser platform rather than pretending it offers a multi file transaction. The File System specification defines safe replacement for one file; the project therefore uses immutable revision files, per file compare and swap, readback hashes, and manifest last publication to detect an interrupted multi file projection. Artifact data is still origin storage, so the OS storage health and backup controls remain authoritative under the Storage Standard persistence model. Rendering trust tiers Tier Artifact kinds Execution boundary Native Document, code, data DOM


AI Echo Artifact Studio

remain authoritative under the Storage Standard persistence model. Rendering trust tiers Tier Artifact kinds Execution boundary Native Document, code, data DOM nodes built with ; no generated code runs. Declarative Table, chart, UI A strict JSON grammar selects known components; unknown fields, nodes, URLs, depth, or size are rejected. Opaque sandbox Static web presentation A unique origin iframe with no script, same origin, form, popup, download, navigation, or network authority and a restrictive content security policy. Declarative buttons emit typed artifact intents. They cannot call tools, storage, the network, Live Patch, or credentials directly. An intent must re enter AI Echo's planner, Faculty runtime


AI Echo Clicks and Clankers

React and stateful application synchronization

Clean-room WebMCP discovery, verified semantic browser control, approval, receipts, and state synchronization for AI Echo. AI Echo Clicks and Clankers AI Echo supports a hybrid browser workflow. A person can keep using the visible page, while the Navi can discover typed page actions or perform bounded semantic controls through the WebGPU OS browser extension. WebMCP is the preferred path. Semantic inspection and exact target actions are the fallback. The implementation does not use Playwright, copy browser agent source, evade bot controls, export browser credentials, or expose an unrestricted JavaScript, mouse, keyboard, or Chrome DevTools channel to a model. (Sources: and .) Capability ladder AI Echo chooses the narrowest available capability: 1. Discover a same origin page tool with . 2. Review its untrusted name, description, input schema, annotations, origin, and exact descriptor hash. 3. Invoke that exact descriptor with after one use approval. 4. Use semantic snapshot, extract, focus, hover, scroll, click, type, bounded key, wait, and verify controls when the page exposes no suitable tool. 5. Use Live Patch only for a declared, reversible interface edit. 6. Keep raw browser JavaScript behind explicit developer mode and exact hash approval. The extension feature detects the current API. It keeps the older navigator location as a temporary compatibility branch. WebMCP remains an experimental Community Group draft, so the browser specific execution method stays behind the extension adapter instead of becoming a durable Navi contract. (WebMCP draft, Chrome imperative API.) Discovery and invocation Page provided tools are untrusted resources. They do not enter the kernel tool registry and their annotations never grant authority. Discovery applies strict limits to tool


AI Echo Clicks and Clankers

tools are untrusted resources. They do not enter the kernel tool registry and their annotations never grant authority. Discovery applies strict limits to tool count, text, schemas, JSON depth, and bridge bytes. It excludes cross origin tools and removes credentials from projected URLs. Each descriptor hash covers the tool name, title, description, input schema, origin, and annotations. Invocation performs a fresh discovery and requires one exact matching name and descriptor hash. The extension binds the approval to the tab, frame, Chrome document ID, origin, descriptor, and canonical argument hash. A navigation, ambiguous tool, changed schema, changed metadata, expired grant, or different arguments fails before dispatch. (Sources: and .) The runtime redacts likely credentials and bounds returned JSON. AI Echo records the result as untrusted. A timeout after invocation begins becomes ; the task must inspect page or domain state before any retry. (Sources: and .) Semantic control The semantic fallback exposes no raw screen coordinates. It identifies visible targets by a selector or a bounded page derived fingerprint. Click and hover require a successful viewport hit test. Password fields, forms containing a password, and credential, private, restricted, or system secret surfaces remain blocked. Keyboard control accepts only navigation and control keys. Text entry uses the separate typed field operation. Every mutation returns target evidence, and AI Echo performs an independent readback before recording success. Synthetic hover and key events are marked ; the UI never represents them as hardware input. (Source: .) React and stateful application synchronization The application store remains canonical. The DOM and React tree are projections. A WebMCP tool should read the


AI Echo Clicks and Clankers

React and stateful application synchronization The application store remains canonical. The DOM and React tree are projections. A WebMCP tool should read the latest store snapshot when execution begins, apply one domain command, wait for the commit, and return the committed revision. It should not close over render time state. Use a stable store facade so React Strict Mode can register, clean up, and register again without duplicating commands. Treat as an invalidation notice and run a complete discovery again. An operation ID makes a retry idempotent, while detects simultaneous human edits. (React , React .) Security boundary WebMCP discovery is same origin only. Tool descriptions, schemas, page text, and res


AI Echo Live Patch

AI Echo Live Patch
Clean-room research boundary
Architecture
RealmForge-informed prepared activation
Surface identities
Allowed operations
Example patch
Markup, CSS, and event safety
AI Echo tools and approval behavior
Storage, history, and recovery
Causal replay and last-good remount
Browser extension boundary
Limits and non-goals
Verification
See also

Clean-room, declarative, reversible live editing for WebGPU OS apps, shell surfaces, AI Echo, and extension-backed browser tabs. AI Echo Live Patch AI Echo Live Patch lets the resident Navi inspect and update a mounted interface without rebuilding the OS. It edits registered WebGPU OS app surfaces, selected shell surfaces, AI Echo itself, and browser tabs exposed by the WebGPU OS browser extension. Live Patch is not a raw JavaScript or unrestricted DOM tool. AI Echo proposes a small versioned document. The kernel validates the document, creates a reversible preview, verifies the visible result, and writes a receipt before an OS surface change becomes durable. (Source: .) Clean room research boundary The public behavior of informed the product goal: a model can stream partial interface updates into named regions instead of regenerating the entire application. Its public README shows named insertion points and describes HTML, CSS, JavaScript, and SVG generation in a multi user chat environment. Its public protocol document describes a streaming server to browser update channel. (Public behavior, public protocol.) The upstream project also states that it is not hardened for production and is intended for local development. It warns that malicious prompts can create unbounded model loops and costs. (Upstream warning.) WebGPU OS uses an independent design: It does not use upstream source code, prompts, delimiters, WebSocket messages, storage records, or client runtime. It does not execute model generated JavaScript, event handlers, scripts, SVG, remote styles, or remote media. The kernel owns target selection, validation, preview, verification, persistence, rollback, and receipts. Existing Tool Firewall, capability, Faculty, and approval rules remain in force. A generated


AI Echo Live Patch

preview, verification, persistence, rollback, and receipts. Existing Tool Firewall, capability, Faculty, and approval rules remain in force. A generated interface cannot grant itself authority. Browser editing uses packaged extension functions. It never sends a provider credential or reusable extension authority into the edited page. The upstream repository is MIT licensed, but Live Patch remains a clean room WebGPU OS implementation under the repository's own source available license. (Upstream license.) Chrome's independent declarative partial update design likewise separates scoped declarative updates and sanitization from explicitly unsafe script capable paths. Live Patch adopts that security distinction without adopting Chrome's API or the upstream project runtime. (Chrome design.) Architecture The kernel service owns one contract. A complete edit uses this sequence: 1. lists registered targets. 2. returns a bounded, redacted structural snapshot. 3. validates a strict patch, records its pre edit inspection, and binds the exact normalized operations and target fingerprint into the patch hash and approval payload. 4. rechecks the approved fingerprint immediately before applying the patch with an in memory undo journal. 5. The service reads the surface back and verifies every operation. 6. The operator can inspect the visible preview. 7. compare and swaps the surface's causal head, then publishes the canonical patch and SHA 256 receipt as one compensated transaction. 8. reverts the active edit, advances the same causal head, and records a rollback receipt. RealmForge informed prepared activation Live Patch adopts RealmForge's offside prepare and last good activation pattern without importing RealmForge documents, scripts, or runtime authority. During , the kernel


AI Echo Live Patch

adopts RealmForge's offside prepare and last good activation pattern without importing RealmForge documents, scripts, or runtime authority. During , the kernel treats the normalized operation list as pure input and compiles a evidence record twice. The two canonical results must be byte identical. The candidate binds the operation hash and semantic diff to the exact surface generation, precondition, expected after state, parent causal head, next , and browser document epochs when the target is a browser tab. A remount, changed target, new head, or non deterministic compilation invalidates the candidate before activation. A successful preview produces a hashed proof. It binds the staged patch hash, candidate an


App Catalog

App Catalog
System & shell
Developer & diagnostics
Files, storage & packages
Security & accounts
Network & browser
Productivity
Science & engineering
Media & creative
Games
Adding an app

Every built-in OS app grouped by purpose, with the authoritative registry and manifest fields (entry, surface, permissions, capabilities). App Catalog Every app shipped in the OS, grouped by purpose. The authoritative registry is ; each app's manifest ( ) declares its , , , and . There are 44 built in apps . Note: Permissions listed here are typical for the category. The manifest is authoritative — see Security & Trust Model for how they are gated. System & shell App id Purpose Quick Settings Fast toggles for common system settings. Command Palette Fuzzy command launcher for OS actions. Notification History Past notifications from the notification center. Control Panel Aggregated system configuration hub. Settings Primary OS settings app. Theme Manager Manage and switch shell themes ( ). System Monitor Live system/resource monitoring. Task Manager View and manage running app processes ( ). Service Manager Manage background OS services. Developer & diagnostics App id Purpose Dev Console In OS developer console / REPL. Terminal Command line terminal. Log Viewer Browse OS logs (e.g. ). Command Registry Inspect registered commands ( ). GPU Manager GPU device/VRAM inspection ( , ). Files, storage & packages App id Purpose Files File browser over the virtual filesystem. Storage Manager Manage OPFS/IndexedDB/mounts ( ). Package Manager Install/remove/update packages ( ). Package Studio Build, sign, and inspect packages ( ). Security & accounts App id Purpose Permissions Review/grant per app capabilities ( / ). User Management Manage user profiles/sessions ( , ). Network & browser App id Purpose Browser Web browser surface ( , browser bridge). Browser Bridge Manager Manage the native browser bridge ( ). Tab Manager Manage browser tabs. Request Rule Manager Manage network


App Catalog

surface ( , browser bridge). Browser Bridge Manager Manage the native browser bridge ( ). Tab Manager Manage browser tabs. Request Rule Manager Manage network request rules / adblock ( , extension). Chatroom Networked chat (collab/net). Productivity App id Purpose Calendar Local first scheduling with reminders, recurring events, recovery, subscriptions, and ICS, CSV, Google Takeout, Apple, and Outlook interchange. Calculator Calculator. Notepad Plain text editor (writes via ). Clock Clock / timers. Calendar stores a versioned primary file and recovery copy, and uses browser storage as a fallback. Its background service runs reminders, daily agenda notifications, and public calendar refreshes even when the Calendar window is closed. Month, week, day, and agenda views support quick creation, detail inspection, drag to move, time grid resizing, recurring event exceptions, tasks, attendees, meeting links, attachments, travel time, duplication, copy and paste, undo, and a 30 day trash. The taskbar date flyout shows the next seven days and exposes quick event creation. Calendar previews imports before applying one undoable batch. It reads and writes RFC 5545 ICS data, including VEVENT, VTODO, RRULE, alarms, attendees, organizers, conferences, and attachments. This supports file exports from Google Calendar, Apple Calendar and iCloud, Microsoft Outlook, and other iCalendar applications. It also imports CSV and Google Takeout ZIP archives and can subscribe to public HTTP, HTTPS, or webcal feeds with conditional refresh and last known good recovery. Private Google, Microsoft, and Apple account synchronization is intentionally not presented as connected until the OS has provider issued OAuth or CalDAV credentials and a secure token vault flow; Calendar never asks users to paste


App Catalog

not presented as connected until the OS has provider issued OAuth or CalDAV credentials and a secure token vault flow; Calendar never asks users to paste provider passwords into ordinary settings. Calendar preferences are available from the app and the OS Control Panel. (Sources: , , , , , .) Science & engineering App id Purpose Smith Lab Guided 2D/3D Smith Chart learning, Touchstone measurement analysis, and deterministic impedance matching synthesis. Media & creative App id Purpose Paint Raster drawing app. Sound Audio playback/synthesis ( ). Particles GPU particle playground (engine ). Fractal GPU fractal explorer. Games App id Purpose Minesweeper Classic minesweeper. Snake Classic snake. Dimensional Pinball


AppForge Contracts

AppForge Contracts
Part Definition
Tags And Scoring
Registry
Service Container
Context Graph
Command Objects
Layout
Blueprints And AppFactory
Terminal Service
Package Exports
Timeline
Lenses
Starter Packs
Workspace Builder
AppForge Syscalls
Security Invariants

Public contracts for the AppForge registry, tags, services, context graph, command objects, layouts, blueprints, package exports, timeline, lenses, builder, and starter packs. AppForge Contracts AppForge is the deterministic assembly layer inside WebGPU OS. It does not replace the kernel, shell, package manager, permission model, or current apps. It registers reusable parts, scores them with tags, assembles blueprints into workspace layouts, records workspace history, and exposes builder tooling. Primary source files: Part Definition Every registered part is a plain object. The shared definition validator accepts these part types: Required fields: Field Meaning Dot or dash namespaced ID that starts with a lowercase letter. One of the supported AppForge part types. Human readable title. Semver like string. Defaults to when omitted. Common optional fields: Field Meaning Human readable summary. Namespaced semantic tags. Capabilities or outputs this part offers. Context, service, or capability dependencies. OS permissions this part needs. / Structured command or tool IO metadata. Numeric scoring tiebreaker. Plain object describing lifecycle hooks or module entry data. Provenance metadata such as app manifest, package export, or starter pack. Part specific metadata. Definitions are cloned on public reads. Callers should treat returned values as snapshots, not live registry objects. Tags And Scoring Tags use form. Supported namespaces are: Examples: uses deterministic scoring from tags, type, zone affinity, permissions, available context, co occurrence data, and risk filters. It returns scored candidates with explanation strings. Registry is the source of truth for reusable AppForge parts. Public API: Rules: Duplicate IDs are rejected unless the caller unregisters the prior


AppForge Contracts

strings. Registry is the source of truth for reusable AppForge parts. Public API: Rules: Duplicate IDs are rejected unless the caller unregisters the prior part first. and return clones. returns scored results and never mutates the registry. Existing app manifests remain in ; AppForge imports them as panel candidates with . Service Container exposes existing kernel owned services through stable IDs. Public API: Kernel provided AppForge services include: ID Backing owner Context Graph stores current OS context as directed nodes and edges. It is used for active file, selection, project, shell cwd, process, theme, panel, registry, layout, terminal, builder, and pack state. Public API: Invalidations are microtask batched. Tests that assert subscriber behavior should wait for a tick before reading callback results. Command Objects AppForge command objects promote local app actions into typed command contracts. Required shape: validates the command object, wraps it in the existing , and exposes public metadata without the handler function. Object pipelines intentionally require exact AppForge command object IDs. Layout owns serializable AppForge workspace state. It does not replace the Desktop window manager. Existing floating windows still launch through the current shell path. Required zones: Public API: is the DOM adapter that exposes AppForge zones while keeping the normal Desktop launch behavior intact. Blueprints And AppFactory A blueprint is a part that declares workspace slots. Slots can require exact parts, prefer optional parts, or select parts by wanted tags. Slot shape: resolves a blueprint and returns selections, permission summary, proposed workspace state, and layout diff without mutating live state. applies a valid preview to the live layout engine. Terminal


AppForge Contracts

permission summary, proposed workspace state, and layout diff without mutating live state. applies a valid preview to the live layout engine. Terminal Service backs the Terminal panel with persistent sessions. Sessions store session ID, cwd, pid, command, stdout/stderr records, exit state, history, and timestamps. The Terminal app attaches to the service and runs commands through the guarded syscall object attached to the session, not through raw kernel syscalls. Exposed syscall namespace: . Package Exports manifests may include AppForge exports: Rules: Export groups imply the part type when is omitted. Exported part permissions must be declared in package or . Export IDs cannot replace parts owned b


WebGPU OS Architecture

WebGPU OS Architecture
Layout
Kernel (webgpu-os/kernel/)
AppForge (webgpu-os/appforge/)
Shell (webgpu-os/shell/)
Packages (webgpu-os/packages/)
Storage (webgpu-os/storage/)
Drivers (webgpu-os/drivers/)
The app entry contract
See also

The kernel, shell, package system, storage, and drivers — and how an app moves from a folder or .prpkg to a running, capability-gated panel. WebGPU OS Architecture The kernel, shell, package system, storage, and drivers — and how an app moves from a folder or to a running, capability gated panel. Layout Kernel ( ) The privileged core. Notable components: — brings up kernel services in order: → → → . — the syscall surface exposed to apps; wraps them with capability checks; reports coverage. This is a stable Tier 2 contract . / — discover apps/mods at runtime. / / — capability resolution, consent UI, persisted grants. / / — trust roots, pinning, provenance. — Tier 1 capability gate stand in. — full posture report. GPU mediation: , , (see GPU Device Sharing). Buses: , , . Surfaces/theme/sound: , , , , . Misc: , , , , , , . AppForge ( ) AppForge is a modular composition layer over the existing OS. It keeps , , , , , Desktop, and Plauna panels as the backing runtime, then adds folders for definitions, registry, tags, scoring, services, context graph, command objects, layout zones, blueprints, package exports, timeline, lenses, starter packs, and the visual workspace builder. See AppForge Contracts for the public API and security invariants. Shell ( ) The desktop UI, built on Plauna workspaces (every window is a Plauna panel): — the compositor/window manager; wraps an app's syscalls with , routes entries to the package loader. , , — shell chrome. , — dialogs + notifications. — host realm for packaged apps. , , — window sizing/state/icons. Packages ( ) The v2 system (encrypted ZIP container + cross verified public envelope): — install/remove/verify/rollback; the choke point chains integrity → trust → provenance → scan → policy → verdict. — loads installed apps from OPFS as a


WebGPU OS Architecture

— install/remove/verify/rollback; the choke point chains integrity → trust → provenance → scan → policy → verdict. — loads installed apps from OPFS as a blob URL module graph (patch overlay aware). — build, sign, verify, scan, register. — differential updates with anti rollback + version cooldown. , , , , , — supporting tools. See Security & Trust Model for the trust pipeline. Storage ( ) Virtual filesystem over browser primitives: / (syscall facing), , , , , (per app isolation), (orchestration). See Data Flow. Drivers ( ) , , , , . The browser bridge ( ) and extension ( ) provide native browser integration and an adblock relay. The app entry contract Manifests declare , , , , , , and . The entry module default exports a class with (and optional ). Dev tree apps live at ; packaged apps embed a manifest and load via . (Source: .) See also Boot Sequence Security & Trust Model App Catalog WebGPU OS API Reference


WebGPU OS Getting Started

WebGPU OS Getting Started
Boot the OS
then browse to:
http://127.0.0.1:9001/webgpu-os/
Build a minimal app
Key rules
See also

Boot the OS in a browser and build a minimal capability-gated app. WebGPU OS Getting Started Boot the OS and build a minimal app. Assumes Install & Run is done. Boot the OS Or embed it (see Quickstart): Build a minimal app 1. Create the folder . 2. Add a manifest : 3. Add the entry module — default export a class with : 4. Register it — add to . 5. Reload the OS. The app appears in the Start Menu and is discovered by . Key rules Declare only the permissions you use; they are checked by . See Security & Trust Model. Treat GPU resources as reconstructable — handle the fan out. See GPU Device Sharing. For distribution, package the app as a v2 ( / ). See also Architecture — the app entry contract and package pipeline. App Catalog — existing apps to learn from. — / starters.


WebGPU OS

WebGPU OS
In this section
Module map
Related concepts

Section index for the WebGPU OS — GPU-first compositor, shell, kernel, and package system (overview, architecture, getting started, app catalog, API reference). WebGPU OS GPU first compositor, shell, kernel, and package system that boots in a browser tab. Source: . In this section Overview — what it is, tier framing, subsystems. Architecture — kernel, shell, packages, storage, drivers, app contract. Realm Network — portable identity, content, resumable links, semantic replication, governance, discovery, V3 compatibility, and one shot deployment policy. Navi Architecture and Delivery — persistent identity, cognition, Faculties, causal memory, bounded autonomy, Manifestations, and recovery gates. AI Echo Live Patch — clean room declarative, reversible live editing for OS apps, shell surfaces, AI Echo, and extension backed browser tabs. AI Echo Artifact Studio — file backed, versioned work products with native, declarative, and opaque sandbox previews beside the conversation. AI Echo Clicks and Clankers — clean room WebMCP discovery, verified semantic browser control, exact approvals, receipts, and React state synchronization. AppForge Contracts — modular part registry, deterministic assembly, context graph, layout zones, package exports, timeline, lenses, starter packs, and builder contracts. Getting Started — boot the OS and build an app. App Catalog — all 35 built in apps. API Reference — per file symbols from , , , , , , (browse ). Module map Related concepts Boot Sequence GPU Device Sharing Security & Trust Model Data Flow