Release history

Mobile chrome and live surfaces, plus the reliability pass from the logic review. The application shell gains a bottom tab bar, drawers gain a bottom-sheet placement, and any region can now keep itself fresh from a host endpoint. On top of that, this release fixes 15 issues. Public names stay the same. Every change is additive, except the behavior notes listed at the end.

• Live surfaces keep regions fresh. A data-smart-live element (or the universal surface property live) fetches a host endpoint on an interval and applies the response as trusted markup — the same contract as update({ html: true }): inserted, never sanitized, and components in the fragment re-hydrate. The endpoint must return a fragment the host trusts; for user-authored content, use agent surfaces or rich text instead. Polling is the default; data-smart-live-transport="sse" uses an EventSource and falls back to polling if the stream fails — and because EventSource cannot send custom headers, SSE endpoints authenticate with same-origin cookies or a query token rather than the poll path’s X-Requested-With header. Fast SSE bursts coalesce to the newest payload. Refreshing pauses while the tab is hidden, the region scrolls offscreen, or the browser is offline — and returning to view refreshes at once. Failures back off up to 8× the interval and mark the region .is-live-stale. data-smart-live-indicator renders a small status chip; data-smart-live-updated carries the ISO time of the last refresh. Events: smart:live-update, smart:live-error. Programmatic twin: SmartWebUI.observeLive(target, { url, interval, transport, indicator }) returns { refresh, stop }. The endpoint belongs to the host — the library owns only the fetch rhythm and the insertion contract.
• The shell gains a mobile tab bar. An AppShell accepts up to six tabs[] ({ label, href, icon, current, badge }), rendered as a bottom navigation rail below 50rem with safe-area padding and an optional badge slot; the desktop shell is unchanged. Tab entries use aria-current="page".
• Drawers can be bottom sheets. Drawer placement: "sheet" (or the .smart-drawer--sheet class) docks the dialog to the bottom edge, capped below the notch, with a drag-to-dismiss grip. The grip is a pointer-only extra — Escape and the close button remain the keyboard path.
• Safe areas are tokens. --smart-safe-area-top/right/bottom/left wrap env() with zero fallbacks; the tab bar and sheet consume them, and hosts can reach the same values anywhere.
• Focus rings follow the keyboard. This corrects the 1.5.5 note. A mouse click no longer draws a ring on a menu item, select option, date day, or time option that stays open. The ring appears after a key press inside an open popover.
• Hydration starts on load. A script loaded after DOMContentLoaded has fired now hydrates its page. Before this fix, the page stayed inert until a manual SmartWebUI.hydrate() call.
• Date events carry a mode. smart:date reports { mode: "single", value }. smart:date-range reports { mode: "range", start, end }. A completed range dispatches input and change on the start and end inputs, so form listeners see the whole range.
• Banner close is documented. smart:bannerclose now has the hyphenated alias smart:banner-close, and both are declared in smartwebui.d.ts.
• Every change event says where it came from. smart:change payloads carry component: "richtext", "menu", or "agent".
• Rich text removes unsafe elements with their contents. script, style, iframe, object, embed, template, and noscript are dropped. Their text no longer stays visible.
• Trusted HTML gets a warning. SmartWebUI.update() with { html: true } logs a console warning when the markup has a script, iframe, object, embed, inline on* handler, or javascript: URL. The content is still inserted as given, so use it for trusted markup only.
• Coarse-pointer tap areas never overlap. The 44px area on menu rows, icon buttons, tree toggles, and carousel toggles is split between neighbours. The runtime writes --smart-hit-slop-x and --smart-hit-slop-y on coarse pointers and rebalances on resize.
• Busy indicators pulse under reduced motion. Spinners, load-more, pull-to-refresh, and map loading keep a slow opacity pulse instead of rotating or shimmering.
• Accessibility preferences win by layer order. Reduced transparency, higher contrast, and forced colors live in a smart.preferences layer that is declared last. The !important flags were removed from those rules. Your own unlayered CSS still overrides them.
• Overlays and runtime values are tokens. Media badges, carousel captions, and the lightbox read --smart-on-media*, --smart-media-scrim, --smart-media-fade, and --smart-lightbox-backdrop. Runtime values such as range fill, tab position, lightbox transform, and liquid highlight position have defaults in :root.
• One agent namespace. window.SmartWebUI.agent groups the agent API. The flat names stay.
• Double loads are ignored. A second copy of the core or agent script returns and listeners are no longer registered twice. A second copy of a different version also warns in the console.
• Types match the runtime. smartwebui.d.ts declares the date modes, the component field, the agent namespace, and every dispatched smart: event, including the aliases.
• Updated Figma and Blocks libraries Full sync of the new capabilities and components.

Behavior notes. Live regions replace their content in place; a live endpoint returns the region’s inner markup — trusted HTML, inserted without sanitization — and anything inside it re-hydrates. Bottom sheets render a decorative drag grip inside the dialog. Rich text now removes the text of style and script blocks instead of showing it. Form listeners on a date range receive input and change from the end input as well. Layered CSS that depended on the forced !important values in the reduced-transparency or higher-contrast modes should check its precedence. Custom code using the flat agent names needs no change.

One contract for layers, direction, and focus. This release tightens the design system without renaming public events, changing type steps, or changing the default theme.

• Layers have a complete scale. --smart-z-menu (30), --smart-z-drag (35), and --smart-z-overlay (45) sit between the existing tooltip, toast, and banner values. Context menus use the menu layer. Drag ghosts use the drag layer, so a toast stays above a dragged row. Toast remains 40 and banner remains 50.
• Writing direction is logical. Drawers dock to the inline end. Tree groups indent from the inline start, and their disclosure keys follow that direction. Pinned column seams and collapsed group markers flip in RTL. Horizontal split panes measure and step from the start edge.
• Focus stays visible. A menu opened with a pointer keeps the focus ring on the focused item. The first item focused inside a menu, select, date, or time popover requests a visible focus, including when that focus happens on the next frame.
• Coarse pointers get a 44px hit area on icon buttons, menu rows, carousel controls (including the autoplay toggle), and tree disclosures. The visible control and the layout box stay the same size. The token is --smart-hit-target. On a coarse pointer the filmstrip expand button stays visible, because there is no hover state to reveal it.
• A 14px type step is available as --smart-font-size-footnote. Existing numbered type steps are unchanged. Segmented thumbs use a concentric radius based on --smart-segment-inset.
• Dark Liquid has one recipe. Explicit dark theme and the operating-system dark preference both read the same values. An unset theme still follows the system. Browsers that support contrast-color() choose status-label color from the accent; other browsers keep the existing pairs.
• Materials are a closed set. setMaterial() accepts solid, liquid, minimal, and relief. An unknown name warns and leaves the current material in place.
• Events keep their names and also emit kebab-case aliases: smart:tooltip-open, smart:stream-start, smart:stream-end, smart:stream-stop, smart:filter-view, smart:refresh-start, smart:refresh-end, smart:inline-commit, smart:inline-cancel, and smart:load-more. A date range also emits smart:date-range. smart:date, smart:board, and smart:move still fire.
• Popover anchors. A .smart-popover without data-smart-anchor still opens, and the console explains that it cannot be placed on its trigger.
• One family index. Family numbers 01–50 are the public index. Older gate numbers in previous release notes stay historical.

No breaking API changes. Right-to-left layouts move drawers, trees, pinned columns, and split panes to the writing direction. Browsers with contrast-color() may change status-label color when a custom accent is set.

Charts that fit, and a missing logo. This maintenance release makes agent charts legible at any layout width and closes the gap between the AppHeader catalog and the server renderer.

• Charts paint at their display width. Browser-painted plots measure their container and render at native size (320–1200 units) instead of stretching a fixed 320-unit drawing, so axis text keeps its true size on wide layouts instead of scaling into oversized labels. Charts repaint when their container resizes.
• Cleaner axes. Tick labels sit on their own row with the axis title clear below them, the tick count scales with the plot width, and labels longer than twelve characters truncate with an ellipsis and a full-text tooltip — matching the server-side painter, which keeps its natural 640-unit width and gains the same truncation.
• AppHeader logos render. The catalog’s optional logo property (source, alt text, size) now draws an image before the brand link in the PHP surface renderer, clamped to 12–96 px. The schema accepts the property, and an unsafe or missing source degrades to no image instead of failing the surface.

No breaking API changes.

Declarative runtime parity. This maintenance release aligns server- and browser-rendered agent surfaces with their optional companions and tightens rollback, teardown, validation, and TypeScript contracts.

• Media surfaces remain operable. Native controls stay enabled when no custom toolbar is rendered. Playlist surfaces now use audio playback and emit the source, title, artist, artwork, type, and current-track metadata required for switching tracks.
• DataGrid surfaces match the companion. Browser and PHP output now share stable row and column markers, CSV values, sortable headers, selectable rows, summaries, and pagination controls with smartwebui-datagrid.js.
• Atomic agent patches. A failed multi-operation patch restores the prior surface instead of leaving earlier operations applied. Replaced DataGrid, Media, Signature, and Map companions are destroyed before removal.
• Stricter nested records. Board cards, conversation messages/composers, map locations, grid rows/cells, and media tracks now receive matching nested type checks in JavaScript and PHP.
• Public contract corrections. TypeScript separates agent media tracks from runtime event details, declares SmartWebUI.update() as asynchronous, and matches the emitted smart:update payload. Replacement updates dispatch from a connected target.
• Lifecycle and documentation. Dirty-form reset listeners and delayed grid filters are removed on teardown, unused strong grid references are gone, and icon documentation now matches the 519-symbol catalog.
• Filter and notification parity. Agent-rendered filter and notification surfaces now use instance-scoped ids; notification panels anchor to their bell triggers; saved-view labels update after selection; declared unread totals survive hydration and consistently use 99+; and the FilterBar catalog lists smart:filter-add.

No breaking API changes.

Maintenance reliability. This release hardens lifecycle cleanup, optional service loading, and interaction state without changing the public API.

• Streaming agent replies. Conversation bubbles accept live text through SmartWebUI.stream() — pending, streaming, done, and stopped states with a blinking caret, an auto-scrolled log protected by aria-busy, a declarative stop control with Escape parity, and smart:streamstart, smart:streamend, and smart:streamstop events for the host fetch. Catalog Conversation messages accept a streaming flag, and the PHP surface renderer emits pending targets.
• Pull to refresh & load more. The observeLoadMore hook gains a declarative pattern — data-smart-load-more fetches data-url fragments into a target list with automatic busy and end states (auto mode triggers on scroll) — and SmartWebUI.observePullToRefresh() adds a touch pull-to-refresh gesture for scrollable containers: library spinner, threshold damping, overscroll-behavior containment, and smart:refreshstart/smart:refreshend events. Touch-only by design; pointer devices are untouched.
• Inline editable text. Any plain-text element takes data-smart-inline and becomes click-to-edit — the one-element version of the data-grid cell edit contract. Click or Enter/Space edits in place with an input that inherits the element's typography and sizes to its content; Enter or blur commits, Escape or an empty commit restores the previous value, and cancelable smart:inlinecommit plus smart:inlinecancel let the host validate remotely. Not exposed to the agent catalog: editable text is a user-input surface.
• Small completions. Tooltips toggle on tap for touch devices (outside tap or Escape dismisses them), data-smart-read-more clamps long text behind a "Show more" toggle that appears only on overflow, data-smart-banner makes announcements dismissible with localStorage persistence keyed by data-smart-banner-key, and toasts pause their countdown while hovered or focused.
• Recoverable integrations. MapKit loading now settles instead of waiting indefinitely on stale script elements, and Stripe loading can retry after a transient network or content-security-policy failure.
• Predictable interaction state. Looping carousel lightboxes wrap at both boundaries and their swipe navigation mirrors right-to-left layouts, canceled data-grid column drags clear their pending state, and Escape-canceled signature strokes return their points to the drawing budget.
• Drag lifecycle hardening. Split-pane splitters clean up their move listener when a pointer drag is canceled, and data-grid column resize updates live while persisting the layout and emitting smart:grid-column once at drag end instead of on every pointer move.
• Reliable teardown. Destroying a virtualized list cancels any queued render and ignores later handle calls so removed padding and content cannot reappear afterward.
• Type contract parity. Element-level smart:grid-column listeners now expose the same resize, pin, visibility, and reorder details as document-level listeners.

No breaking API changes.

New Relief material. A fourth global material option — data-material="relief" — gives surfaces a raised, soft-edge look: warm canvas tint, crisply outlined controls and cards with diffuse depth shadows, sunken text fields, and a gentle hover lift. Pure CSS custom properties, dark-theme aware, and tunable with the new --smart-relief-* tokens alongside Solid, Liquid, and Minimal.

• Fields sit below, actions sit above. Buttons, cards, and surfaces carry the raised treatment while text inputs, textareas, and selects render sunken — the contrast is the affordance. Pressed buttons briefly sink.
• No JavaScript required. SmartWebUI.setMaterial("relief") works out of the box; the preference persists through the existing material storage and the smart:material event.
• TypeScript and catalog. The SmartMaterial union and the agent catalog version reflect the new option.

Liquid buttons feel like real glass. The Liquid material's is updated. A prismatic refraction gradient is now enabled on every button, the body is more translucent, the lens blur deepens with 210% saturation, and a two-stage bloom shadow lifts buttons off the page. Edges keep the soft shipped border recipe — no added rim.

• Glossy accent glass. Primary, Success, Warning, Info, and Danger render as tinted glass with a gentle top sheen and an accent-colored bloom; fills now follow --smart-liquid-accent-opacity (84% light, 78% dark) instead of a fixed mix, and dark theme keeps the refraction layer.
• Hover and press keep their feel. The hover lift, border brightening, and specular filter stay, now over the glass body with the bloom shadow; pressing settles the shadow instead of an inset ring.
• Expanded menu trigger repaired. The open-state background of aria-haspopup="menu" buttons wrapped a gradient variable inside another gradient, which silently invalidated the declaration; it now renders its intended tinted surface.

No breaking API changes.

More components for professional applications, new minimal material theme option. Version 1.5 adds deeper operational, administrative, and data-intensive product interfaces while keeping authored HTML and declarative surfaces aligned.

• Advanced Data grid. A new optional smartwebui-datagrid.js companion adds server-side sort/filter/pagination contracts, pinned/resizable/reorderable and hideable columns, row grouping, keyboard-accessible inline editing, selection, persisted layouts, and formula-safe CSV export while retaining native table semantics.
• Professional charts. Chart expands from five to nine marks with stacked bars, dual-axis combo charts, scatter plots, and operational gauges. Series-level marks, axes, units, thresholds, targets, explicit summaries, accessible data tables, and AI/computer-use showcase examples. Donuts accept a numeric hole between 0 and 0.85; hole: 0 renders a filled pie. Charts no longer pre-select their first point or slice on hydration; selection appears only when authored or chosen.
• Media players. Native Video, Audio, and Playlist layouts gain a shared optional smartwebui-media.js runtime for playback, seeking, volume, speed, captions, fullscreen, Picture in Picture, track navigation, auto-next, keyboard shortcuts, and Media Session integration. The production surfaces now include richer feature metadata, media badges, editorial artwork, a dedicated now-playing area, denser track rows, and polished Solid, dark, and Liquid treatments. Applications retain ownership of media delivery, authorization, captions, codecs, and DRM.
• Signature pad. A new optional smartwebui-signature.js companion adds responsive pointer drawing, an accessible typed-signature alternative, undo and clear actions, required-state handling, bounded form serialization, and optional PNG export. The host remains responsible for consent, identity, document integrity, audit evidence, retention, and legal compliance.
• Application navigation patterns. Tree, Context Menu, and Split Pane add keyboard-navigable hierarchy, native-popover contextual actions, and pointer/keyboard-resizable workspaces. They ship with CSS, hydration, PHP and browser declarative renderers, catalog and TypeScript contracts, component documentation, and showcase examples.
• Filter bar and notification center. Filter bar (#49) composes search, saved views, and removable active filter chips for data-heavy screens, dispatching smart:filter-add, smart:filter-change, smart:filter-remove, and smart:view-change while the host owns its chooser, queries, and saved views. Notification center (#50) adds a bell trigger with grouped inbox notifications, unread badges, and mark-read affordances through smart:notification-read. Both ship with CSS, hydration, PHP and browser declarative renderers, catalog and TypeScript contracts, component documentation, and showcase examples.
• Formatted fields. Text fields can now declare locale-aware number and currency presentation with canonical hidden form values, or an E.164-preserving phone display. Partial masks retain the caret during editing; phone validation remains application-owned.
• Accessibility and token hardening. Public focus and disabled-state tokens, semantic status foreground tokens, SVG data-grid controls, stronger placeholder contrast, and compact-density isolation remove several production accessibility and consistency hazards.
• Liquid material refinement. The Liquid material option was updated for a more premium feeling, tighter dark-mode borders, softer depth instead of harsh inset rims, expanded frosted-glass coverage across dual-range, OTP, button groups, and related controls, and cleaner hero and field surfaces in dark theme.
• Minimal material. A third global material option — data-material="minimal" — delivers a modern flat skin for dense admin and data-heavy apps: tighter radii, flush surfaces, and outline actions (accent text and border instead of fill) across buttons, badges, chips, and alerts. Tune it with the --smart-minimal-* tokens alongside Solid and Liquid.
• Figma Solid + Minimal variants. The Starter-compatible local Figma library now exposes Material: Solid | Minimal alongside Light/Dark theme variants for every generated family. Liquid remains intentionally browser-only because its backdrop compositing and pointer response cannot be represented faithfully as static Figma variants.
• Complete agent-family coverage. The catalog now exposes 47 component nodes plus four layout primitives (51 total), giving all 50 HTML families a safe declarative path. RichText, Board, Conversation, Composer, Map, DataGrid, MediaPlayer, and SignaturePad now render consistently in the browser and dependency-free PHP renderer. Integration contracts stay intentionally bounded: agents cannot inject rich-text HTML, credentials, server endpoints, callbacks, DRM settings, prefilled messages, or signature evidence.
• Agent contract conformance. The catalog generates the browser validation schema and directly drives the PHP allowlist. Shared valid and fail-closed JSON fixtures cover the eight new nodes; a release check detects catalog, browser schema, TypeScript union, and public inventory drift.

No breaking API changes.

Version 1.4 was skipped for a major 1.5 version

Production design-system workflows. Version 1.3 connects the browser library, server-rendered applications, and the downloadable Figma system more closely while adding accessible reordering for real product-management interfaces. There is also a new Map component.

• Sortable lists. The List family now has an opt-in, handle-only sortable variant with pointer, touch, and keyboard operation, a pointer-following row preview, animated sibling displacement and settling, polite move announcements, edge autoscroll, hidden form-order synchronization, and a bubbling smart:reorder event. Ordinary lists are unchanged, and reduced-motion preferences are respected.
• Figma production library. The downloadable design file now covers the existing component inventory with reusable variants, auto layout, documented states, and token-aligned light and dark modes. Option available at olevator.com
• Apple MapKit JS component A new responsive Map family ships with light/dark tokens, compact sizing, semantic location fallbacks, and an optional smartwebui-mapkit.js companion. Applications retain ownership of Apple Maps tokens and may provide a same-origin refresh endpoint; the library bundles no credentials or map imagery.
• Deliverable packaging. The source synchronizer now atomically builds and verifies smartwebUI-Blocks.zip alongside the core distribution. The Figma file uses a leaner documentation sequence: Cover, Getting Started, and Components Index.

No breaking API changes. The surface protocol remains smartwebui.surface/1.0.

Accessibility and layout hardening. This maintenance release completes the quality contract for the 1.2 collaborative components and aligns the published package with its documentation.

• RichText accessibility. The editable surface is now explicitly named, formatting controls expose their selected state, and form synchronization uses an unfocusable hidden input. Required-content validation is performed on, announced from, and focused back to the visible editor.
• Conversation sizing. Conversation headers now take their natural content height while the message list consumes the remaining space. Headerless conversations use the full available message area.
• Reference integrity. Documentation now includes RichText, Board, and Conversation + composer (families 39–41); the showcase, accessibility contract, README, and QA matrix agree on 41 HTML families and 516 icons.
• Block library. More than 30 blocks built for developers. Option available at olevator.com

No breaking API changes. Legacy RichText textarea sync fields are converted to a hidden input when hydrated.

Collaborative components. Version 1.2 adds three interactive families that real support, project, and messaging products need — a rich-text editor, a Kanban board, and conversation + composer chat primitives — all framework-free and token-driven.

• RichText editor. data-smart-richtext turns any container into a contenteditable rich-text field with a toolbar (bold, italic, lists, links), sanitized HTML output via a built-in tag allowlist (subset with data-smart-richtext-allow, e.g. p, br, strong, em, ul, ol, li), and a hidden input that stays in sync for form submission. Emits smart:change with { value, control }. The toolbar uses the same smartwebUI buttons and icons as the rest of the library.
• Kanban board. data-smart-board renders columns and cards with drag-and-drop reordering across columns. DnD is keyboard-accessible (focus a card, press Enter or Space to lift, arrow keys to preview a move, Enter or Space to drop, Escape to cancel), works with pointer and touch, and emits smart:board plus a compatibility smart:move event with the card ID, source and target columns, and indexes. No jQuery UI or external DnD library.
• Conversation + Composer. data-smart-conversation renders a scrollable message list with avatars, timestamps, and sender alignment; data-smart-composer renders a textarea with a send button, auto-resize, and Enter-to-send (Shift+Enter for newline). Together they cover ticket threads, live chat, and project comment flows.
• Icon alias map. SmartWebUI.icon() and the PHP se_icon() helper resolve common alternate icon names (e.g. house → home, check-circle → circle-check) so applications can use natural names without maintaining a custom map.
• Application layout utilities. Generic helpers for page shells, auth columns, reading-width content, card grids, and log panels — no product-specific class names. Includes smart-page-main, smart-shell-main, smart-cluster--center, smart-stack--tight, smart-auth-layout, smart-auth-logo, smart-reading-card, smart-tile-card, smart-grid--cards, smart-grid--tiles, smart-grid--pickers, smart-card--picker, smart-card__feature-icon, and smart-log-panel. Documented in the README layout table and on the docs.
• Page header toolbar. The reusable smart-page-header--toolbar modifier and smart-page-header__toolbar element give headers a responsive, single-row home for filters, search, view controls, and a primary page action. Controls wrap naturally on smaller screens without application-specific CSS.
• Card and picker grids. Equal-height card grids (smart-grid--cards), tile grids with larger feature icons (smart-grid--tiles, smart-card__feature-icon), and centered picker tiles (smart-grid--pickers, smart-card--picker). Card title icons scale with the heading.
• Form sizing refresh. Comfortable-density defaults are roomier: control height 3rem, wider horizontal padding, larger label and input type, and vertical input padding derived from control height. New tokens --smart-form-gap and --smart-field-gap widen row spacing in form.smart-stack, card bodies, dialog bodies, and fieldsets; grids containing fields get a wider column gap. Dialog default width is 40rem with more internal padding; auth layout max width is 44rem. Filter toolbars still use smart-control-sm.
• Documentation. Token reference, utilities, and layout sections on the docs now cover the new form spacing tokens and application layout helpers. The README layout utilities table lists every helper class.

No breaking changes. The surface protocol remains smartwebui.surface/1.0.

The application release. Version 1.1 grows smartwebUI from a component collection into a complete, dependency-free application foundation, with a native icon language and the patterns real products repeatedly need. This is the release for ambitious web apps.

• Carousels and lightbox. One Carousel family adds momentum media browsing: a snap-scrolling slide strip with iOS-style page dots, an optional autoplay that pauses on hover, focus, and offscreen, a gallery grid variant, and a fullscreen native-dialog viewer with swipe navigation, drag-to-dismiss, and pinch, double-tap, ⌘-scroll, or keyboard zoom (1–4×, reset on navigation). Slides accept captions and nested catalog content over the media; image URLs follow the surface src policy; smart:slide reports the active index and the snapshot records it.
• 500 stable symbols. The generated SVG sprite includes canonical names and compatibility aliases, while a searchable JSON catalog carries tags, categories, and directional metadata. The runtime pins sprite and catalog URLs to the loaded catalog payload (?v=version.count), so a rebuilt sprite can never lag a fresh catalog in a browser cache — the mismatch that renders blank icons.
• Any size. --smart-icon-size accepts every valid CSS length, from pixels and ems to viewport units and clamp(); stroke weight is independently adjustable.
• Motion utilities. Opt-in entrance, exit, and one-shot attention effects add a compact animation vocabulary for product interfaces. Timing, delay, easing, and iteration count are locally token-controlled; logical start/end directions mirror in RTL and every effect respects reduced-motion preferences.
• Application utilities. Public clipboard and confirm helpers, Intl formatters, debounce/throttle, breakpoint observation, infinite-scroll sentinels, dividers, keyboard hints, line clamps, sticky helpers, and tablet/desktop utilities stay small and framework-free.
• Layout utilities. Spacing steps run 0–8 with complete logical padding and margin axes (pt/pb/ps/pe, mt/mb/ms/me, mx/my). .smart-skip-link provides a focus-revealed bypass to the main landmark.
• One rendering contract. Authored HTML, SmartWebUI.icon(), agent Icon nodes, icon-bearing buttons, and the PHP renderer use the same sprite; action and status controls no longer depend on font glyphs.
• Accessible and international. Decorative icons are hidden, standalone icons accept labels, and directional symbols mirror automatically in RTL layouts.
• Complete chrome. AppHeader adds horizontal navigation and mobile collapse; AppShell gains nested disclosure groups; Footer completes the Header / Footer family, while consent is an Alert placement.
• Production tables. Sticky headers, expandable rows, column widths, totals, and a page-size selector cover dense admin and reporting workflows.
• Advanced forms and files. Field gains multi-select, dual numeric range, masks, rating, and color controls; the List family gains post-upload attachments.
• Safer form summaries. SmartWebUI.validate() builds the FormErrors summary with DOM text nodes instead of HTML interpolation.
• Command-first navigation. CommandPalette pairs live filtering and keyboard result navigation with a public, normalized shortcut registry.
• Persistent product data. Avatar gains groups and presence; List gains timeline, key-value, notification, and attachment variations; Progress gains a circular ring variation.
• Frosted Liquid art direction. A deeper blur substrate, asymmetric refraction, bright upper rims, and quiet lower-edge depth give controls and content surfaces a genuine frosted-glass character; connected split actions still share one glass container and accessibility preferences retain priority.
• Badge labels without a marker. .smart-badge--plain (agent plain) hides the leading status dot when the badge is a classification, not a live state.
• Hardening details. Toast placement, textarea counters, input icons, connectivity and scroll-to-top affordances, collapsing breadcrumbs, public focus and dirty/query-state helpers, fixed-row virtualization, accordion events, and z-index utilities close the remaining application-level gaps without adding component families.
• One additive contract. The browser renderer, dependency-free PHP renderer, TypeScript types, catalog, docs, and agent guidance all expose the same 34 components and 4 layout primitives.
• Catalog coherence. Split actions remain Button, advanced controls remain Field, structured feeds remain List, groups remain Avatar, and consent remains Alert. Existing Card, Badge, Tabs, Dialog, Menu, Tooltip, Stepper, and Table variations are catalog-exposed.
• Inventory, catalog, and contract clarity. HTML families (38) and catalog types (34 + 4, including Icon) are labeled as two lists. Field and List catalog events match the 1.1 runtime. The optional PHP renderer is documented as the included smartwebui-surface.php helper, not as the absence of PHP. Showcase variation cards no longer reuse family numbers 34–48.
• A clearer site experience. The landing page now presents a dashboard composition, the full style-switchable catalog lives in demo.php, and the agent surface lab has its own focused agents.php destination.

No breaking changes. The surface protocol remains smartwebui.surface/1.0.

Contract hardening and maintenance. This patch release aligns every shipped description of the surface protocol and fixes history edge cases without changing the protocol version.

• Server validation parity. The PHP renderer now rejects unknown node properties, enforces required properties, applies the node limit during traversal, and validates nodes nested inside tabs, accordions, and steppers.
• Reliable patch history. Undo restores the complete prior node after data.patch, handles node.upsert by its node ID, and records multi-operation inverses in execution order.
• Streaming ID safety. A node.append batch now rejects duplicate stable IDs before mounting the duplicate.
• Catalog alignment. node.append is included in the machine-readable patchOperations list.
• TypeScript clarity. Surface-validation and form-validation issues have distinct types, with a deprecated compatibility union for the previous shared name.
• Inventory clarity. Documentation consistently distinguishes the 33-family homepage showcase from the 34-family component reference, where Payment is demonstrated in the reference and agent demo.
• Shared demo stability. Page-specific customizer controls are now guarded when the shared showcase script runs on documentation, changelog, or agent-demo pages.

No breaking changes. The surface protocol remains smartwebui.surface/1.0.

Wider vocabulary, longer reach. This release grows the component vocabulary — files, print, and input ergonomics — and extends the surface contract from first paint on the server to live token streams.

• Dropzone file upload with progress. File gains drag-and-drop, per-file progress events, and client-side validation through data-max-size and accept.
• Print and document styles. A base @media print layer, a .smart-no-print utility, and a print-optimized document card for printable pages such as invoices, quotes, and receipts.
• Vertical tabs. A vertical variant of the tabs family for settings-style layouts.
• Quantity stepper. .smart-quantity with [data-smart-step] buttons that respect min, max, and step; part of Fields as Field control: "quantity".
• Split-button dropdown. A primary action with an attached menu of secondary actions.
• Password strength meter. A Field extension that scores password input and reports missing requirements.
• Server-side surface rendering. A reference renderer in PHP (and the spec for any language) that emits the same semantic HTML as the browser runtime. Agents compose, the server renders first paint, and the browser runtime adopts the DOM by stable ID for patching — turning "agent UI" into "progressively enhanced agent UI."
• Streaming surfaces. An append-friendly render mode for SSE/WebSocket token streams — partial Trees/Lists that grow as the model emits. Every serious LLM product needs this and nobody has a safe, validated answer.
• Patch history / undo. SmartWebUI.history() records surface operations with undo/redo, so agents can roll back their own UI mistakes.
• Form validation helper. SmartWebUI.validate(form, rules) wires aria-invalid, hints, and the FormErrors summary together.
• API clarity. SmartWebUI.validate(form, rules) is the form validation helper; surface declarations are checked with SmartWebUI.validateSurface(surface). The 1.0.1 validate() alias on the agent runtime was removed to keep one meaning per name.
• OTP verification input. .smart-otp digit rows with auto-advance, arrow-key movement, paste distribution, a synced hidden input, and smart:otp events — Field control: "otp" with length in the catalog and both renderers.
• Countdown helper. SmartWebUI.countdown(el, seconds, { warnBelow, onExpire }) or data-smart-countdown markup for the session-timeout pattern, with a stop/start/reset controller and smart:countdown events.
• Scroll panes. .smart-scroll-y/x with contained overscroll plus .smart-pane-fill/tall/screen heights (--smart-pane-offset) for messenger-style layouts.
• Stripe Address + Express Checkout. The companion's mount() now documents and supports elementType: "address" (with addressMode: "billing" | "shipping") and "expressCheckout" for Apple Pay / Google Pay, with elementOptions forwarded verbatim.
• i18n chrome strings. A SmartWebUI.setLocale({ … }) dictionary for component chrome ("Select dates", "Close", placeholders), complementing the existing Intl-based dates and currency and letting agents localize surfaces without re-rendering.
• Source license. smartwebUI ships under the smartwebUI Source License — free to use and customize for your own projects; redistributing modified or rebranded versions requires written permission. See LICENSE.md in the distribution archive.

One agent-runtime breaking change: rename validate(surface) → SmartWebUI.validateSurface(surface) (the 1.0.1 alias is removed; form validation now owns validate()). The surface protocol stays at smartwebui.surface/1.0 (additive properties only); new components ship as HTML-first families.

Utility layer. The infrastructure between components — spacing, typography, visibility, and surface helpers — is now part of the library instead of host-app homework.

• Spacing utilities. .smart-p-*, .smart-px-*, .smart-py-*, .smart-m-* (steps 0–5), .smart-m-auto / .smart-mx-auto, and .smart-gap-* for stack, cluster, and grid.
• Layout utilities. .smart-container--sm/md/lg width caps (backed by new --smart-container-* tokens), fixed .smart-grid--2/3/4 grids with .smart-span-2 / .smart-span-full.
• Typography utilities. Sizes .smart-text-xs–xl, semantic tones, logical alignment, .smart-truncate, .smart-balance, .smart-mono, and .smart-font-* weights.
• Visibility utilities. .smart-hidden, .smart-invisible, .smart-hidden-mobile / .smart-visible-mobile (50rem breakpoint), plus SmartWebUI.hide(el) / SmartWebUI.show(el) and a universal hidden property on agent nodes.
• Surface utilities. .smart-elevated-0/1/2, .smart-rounded-sm/md/lg/full, .smart-bordered, .smart-w-full, .smart-min-w-0, .smart-overflow-x-auto.
• Media ratio utilities. .smart-ratio-1x1 / -4x3 / -16x9 / -21x9, plus two markup behaviors: data-smart-collapse="#id" for remote disclosure toggles and data-smart-scrollspy for table-of-contents highlighting.
• Native validation states. :user-invalid / :user-valid styling, automatic required markers, and .smart-error--live messages that reveal only while invalid — complementing server-side .smart-field--invalid.
• RTL pass. Logical properties verified across the library, with physical-direction corrections for the switch knob, combobox chevron, calendar nav glyphs, and toast region.
• Opt-in compatibility banner. data-smart-compat on <html> feature-detects the required browser capabilities and shows a dismissible update-browser warning on unsupported clients, with a smart:compat event for telemetry.
• Layering tokens. --smart-z-raised/sticky/tooltip/toast/banner replace hardcoded z-indexes so host apps can restack the library. Stepper panel swaps now run through the View Transitions API (like SmartWebUI.update()) with a fade-slide fallback, and .smart-reveal adds scroll-triggered entrance animation with --smart-reveal-delay stagger.
• Agent loop closure. SmartWebUI.snapshot(target) reads values, selections, and progress back from a live surface by stable id, validateSurface() gains structured issues with JSON paths (also exposed as a validate() alias in 1.0.1 only — removed in 1.0.2), and a new /llms.txt teaches coding agents the library's conventions, catalog, and events.
• Media polish. Native <figure>/<figcaption> base styling (caption tone and spacing, no classes) and .smart-object-contain / -cover / -fill / -scale-down utilities as an escape hatch from cover-cropped ratio boxes.
• Sizing utilities. Dimension classes (.smart-w-25/33/50/66/75/full, .smart-w-auto, .smart-h-full) and generic control sizing — .smart-control-sm / .smart-control-lg override --smart-control-height locally, so inputs, selects, date pickers, segmented controls, tabs and buttons align at any size.
• The agent demo is now interactive end-to-end. A live surface JSON editor with validateSurface() feedback (issues listed with their JSON paths), three presets (dashboard, checkout with a Payment slot, settings form), and a real-time snapshot() state panel that follows every interaction and patch.
• E-commerce. Optional smartwebui-stripe.js companion lazy-loads Stripe.js and maps --smart-* tokens to the Elements appearance API (theme/density/material aware). New agent Payment node renders an intent-only checkout slot the host mounts into — keys, secrets, and card data never enter agent JSON.
• Fix. Date pickers now close their popover and return focus to the trigger once a day (or a completed range) is chosen — the grid re-render was detaching the clicked day before the popover lookup ran.

No breaking changes. All utilities live in @layer smart.utilities and reference design tokens, so density and overrides apply automatically.

Initial release. A standards-native UI library for building polished web interfaces without a framework, compiler, Node.js runtime, or dependency — designed for server-rendered applications while remaining stack-independent.

• Thirty-three showcase families. Semantic HTML mapped to 27 agent catalog types plus four layout primitives. Field covers combobox, search, file, date, time, tags, and date range; Dialog variant: "confirm" covers confirm dialogs. App shell collapse, table bulk actions, busy buttons, input add-ons, and Stepper are first-class.
• Themes, density, and materials. Light and dark themes resolved through color-scheme and light-dark(), compact density, and the optional Liquid material with pointer tracking that respects reduced motion, reduced transparency, increased contrast, and forced colors.
• Optional behavior script exposing SmartWebUI. Live region toasts, View Transition updates, theme, density, and material preferences, and hydration for dynamically inserted components. update() inserts plain text by default; HTML requires an explicit { html: true } opt-in.
• Agent runtime. Declarative, validated surfaces with stable IDs and live data.patch, node.upsert, and node.remove operations, plus a machine-readable component catalog for generative systems.
• Accessibility and quality. Component-level WCAG 2.2 AA engineering target with documented release gates, a component showcase, agent demo, and this documentation set.

Read the documentation, try the agent demo, or browse the component showcase.