Build native-feeling PWAs for Apple platforms

zexoskit is consumed via pnpm as a workspace/package import — there is no scaffolding CLI.

Copypnpm add zexoskit
# optional, only needed if you use the supabase plugin:
pnpm add @supabase/supabase-js

Working inside this repo instead? pnpm install at the root, then pnpm dev to serve the demo and examples via Vite, or pnpm test to run the Vitest suite.

The whole public surface is createApp → app.use(plugin, options) → app.mount(selector).

Copyimport { createApp } from 'zexoskit';
import { supabasePlugin } from 'zexoskit/plugins/supabase';
import { pushPlugin } from 'zexoskit/plugins/push';
import 'zexoskit/ui'; // registers every <zk-*> custom element

const app = createApp({ name: 'CronWeather', platform: 'auto' });

app.use(supabasePlugin, { url: SUPABASE_URL, anonKey: SUPABASE_ANON_KEY });
app.use(pushPlugin, { vapidKey: VAPID_PUBLIC_KEY });

await app.mount('#app');

Copyzexoskit/
├── core/          bootstrap, platform detection, router, store, lifecycle
├── ui/            design tokens + native Web Components (zk-*)
├── plugins/       registry + socle plugins (auth, storage, push, supabase) + domain stubs
├── demo/          Vite-served page exercising the public API
├── examples/      real consumer apps built on zexoskit (e.g. PixLearn)
└── index.js       package entry point

Three complementary views explain how zexoskit stays small and composable: independent framework layers, a shared plugin lifecycle, and local-first persistence with an optional remote backend.

Creates the application instance. This is the framework's single entry point — everything else attaches to the object it returns.

Copyfunction createApp(options: {
  name: string,                                   // required
  platform?: 'auto' | 'iphone' | 'ipad' | 'mac',   // default: 'auto'
  serviceWorkerPath?: string,                      // default: '/sw.js'
}): App

App instance

Plugins attach their own namespaces on install — e.g. app.auth, app.storage, app.push, app.webauthn, app.db.

A small history-API router with dynamic params, wildcards, and navigation guards.

Copyimport { createRouter } from 'zexoskit/core/router.js';

const router = createRouter({
  '/users/:id': (ctx) => renderUser(ctx.params.id),
  '/files/*': (ctx) => renderFile(ctx.params.wildcard),
  '/admin': { handler: renderAdmin, guard: () => isAdmin() || '/login' },
});

router.beforeEach((ctx) => {
  if (!isAuthed() && ctx.path !== '/login') return '/login'; // redirect
});

router.start(); // matches current location + listens for popstate
await router.navigate('/users/42');

Route patterns

API

Proxy-based reactive state — mutate nested state directly, subscribe to changes, derive selectors and computed values.

Copyimport { createStore } from 'zexoskit/core/store.js';

const store = createStore({ cards: [], query: '' });

store.subscribe(() => renderFeed());

const savedCount = store.computed(
  (state) => state.cards.filter((c) => c.saved).length
);
savedCount.subscribe((count) => {
  navButton.textContent = `Saved (${count})`;
});

// direct nested mutation triggers reactivity:
store.state.query = 'cats';
store.state.cards = [newCard, ...store.state.cards];

Live device/environment detection — device type, input modality, layout breakpoint and standalone (installed) status.

Copyimport { platform, detectPlatform, refreshPlatform } from 'zexoskit';

// platform: { type, input, layout, standalone }
// type:       'iphone' | 'ipad' | 'mac'
// input:      'touch' | 'pointer' | 'hybrid'
// layout:     'compact' | 'regular'   (breakpoint: 768px)
// standalone: boolean

console.log(platform.type, platform.layout);

platform is a live singleton, recomputed automatically on resize/orientationchange. Call refreshPlatform() to force a recompute.

Install-prompt handling and service-worker update flow. Wired up automatically by app.mount() — you only read app.install / app.updates and build UI around them.

Copyawait app.mount('#app');

if (app.install.shouldShowIosFallback()) showAddToHomeScreenBanner();

app.updates.onAvailable(() => {
  toast.show('Update available');
  updateButton.onclick = () => app.updates.apply();
});

The contract every zexoskit plugin implements. Use it to build your own plugins.

Copyimport { definePlugin } from 'zexoskit';

const myPlugin = definePlugin({
  name: 'analytics',                                  // required
  isSupported: (platform) => true,                     // default: always supported
  onInstall(app, options) { app.analytics = client; },  // called by app.use()
  onReady(app) { /* called once, after app.mount() */ },
  onDestroy(app) { /* called by app.destroy() */ },
});

app.use(myPlugin, { apiKey: '...' });

Ready-made plugins, importable from documented subpaths per package.json's exports map:

A generic authentication contract — bring your own adapter (Supabase, a REST backend, a local mock, …).

Copy// AuthAdapter contract:
{
  login(credentials: Object): Promise<Object>,
  logout(): Promise<void>,
  getSession(): Object | null,
  onAuthChange(callback: (session) => void): unsubscribe,
}

Copyimport { createAuthPlugin } from 'zexoskit/plugins/auth';

app.use(createAuthPlugin(myAdapter));

app.auth.onAuthChange((session) => updateAuthUi(session));
loginForm.addEventListener('zk-submit', (e) => {
  app.auth.login({ email: e.detail.email, password: e.detail.password });
});

Passkey registration/authentication ceremonies. Only wraps the browser API — challenge issuance and attestation verification stay on your backend.

Copyimport { webauthnPlugin } from 'zexoskit/plugins/webauthn';
app.use(webauthnPlugin);

const options = await fetch('/webauthn/register/options').then((r) => r.json());
const credential = await app.webauthn.register(options);
await fetch('/webauthn/register/verify', { method: 'POST', body: JSON.stringify(credential) });

IndexedDB-backed local cache with an optional remote adapter and an offline write queue — flushed automatically on online and when the app returns to the foreground.

Copyimport { storagePlugin } from 'zexoskit/plugins/storage';
import { createSupabaseStorageAdapter } from 'zexoskit/plugins/supabase/storage-adapter';

app.use(storagePlugin, { remote: createSupabaseStorageAdapter(supabaseClient) });

await app.storage.set('cards', cards);
const cards = await app.storage.get('cards');

Web Push subscribe/unsubscribe flow via VAPID. Only supported for installed (standalone) PWAs — matches iOS 16.4+'s own push requirement.

Copyimport { pushPlugin } from 'zexoskit/plugins/push';

app.use(pushPlugin, {
  vapidKey: VAPID_PUBLIC_KEY,
  onSubscribe: (subscription) => fetch('/push/subscribe', { method: 'POST', body: JSON.stringify(subscription) }),
});

await app.mount('#app'); // app.serviceWorkerRegistration must exist before subscribe()
await app.push.subscribe();

Wires up a Supabase client as app.db, plus a matching app.auth adapter and app.realtime.

Copyimport { supabasePlugin } from 'zexoskit/plugins/supabase';

app.use(supabasePlugin, { url: SUPABASE_URL, anonKey: SUPABASE_ANON_KEY });
// app.db, app.auth, app.realtime become available once the plugin's
// async onInstall() resolves — see the caveat below.

Two standalone adapters build on it:

Structurally valid, deliberately unimplemented. Their business logic is deferred until a first real consumer app picks one, so today they only log a debug message identifying themselves.

Plain CSS custom properties, framework/bundler-agnostic. Every component reads them from :root, so shadow DOM inherits them for free.

Light values include bg #ffffff, primary #007aff; dark values include bg #000000, primary #0a84ff — see ui/tokens.js for the full light/dark maps. Override any token with normal CSS cascade, or target a component's internal parts with ::part(...) for deeper overrides.

A pro-grade SVG vector icon set (SF Symbols / Lucide-style stroke design, 24×24 viewBox) as a single lightweight custom element — no icon font, no external requests.

Copy<zk-icon name="bell" size="20"></zk-icon>
<zk-icon name="heart" size="20" color="var(--zk-color-danger)" filled></zk-icon>

Registered on the barrel import (import 'zexoskit/ui'), or standalone via import { Icon } from 'zexoskit/ui'. The raw path lookup table is also exported directly from the source module: import { ICONS } from '../ui/icon.js' (not re-exported from the ui barrel).

Icon gallery (Click to copy name)

Injects the active token set as global CSS custom properties and tracks OS prefers-color-scheme when in auto mode.

Copy<zk-theme-provider theme="auto">
  <div id="app"></div>
</zk-theme-provider>

Root layout container: bottom nav on compact layout, left sidebar on regular layout.

Slots

Copy<zk-shell>
  <zk-sidebar-collapsible slot="nav" active-id="feed">
    <button data-id="feed">Discover</button>
  </zk-sidebar-collapsible>
  <div slot="content">...</div>
</zk-shell>

A large title that condenses into a compact centered title on scroll (iOS-style).

Slots

Copy<zk-nav-bar scroll-target="#content">
  <span slot="leading"></span>
  <span slot="title">Feed</span>
  <span slot="trailing"></span>
</zk-nav-bar>

Safe-area-aware bottom navigation for compact layouts.

Events

Copy<zk-tab-bar active-id="home">
  <button data-id="home">Home</button>
  <button data-id="settings">Settings</button>
</zk-tab-bar>

Adaptive nav: a bottom tab bar on compact layout, a collapsible left sidebar on regular layout.

Events

Copy<zk-sidebar-collapsible slot="nav" active-id="feed">
  <button data-id="feed">Discover</button>
  <button data-id="saved">Saved</button>
  <button data-id="settings">Settings</button>
</zk-sidebar-collapsible>

Copynav.addEventListener('zk-navigate', (e) => showPage(e.detail.id));

macOS/iPad windowed-mode navigation aid. Hidden entirely on compact layout — not part of the iOS nav vocabulary.

Copy<zk-breadcrumb>
  <a href="/">Home</a>
  <a href="/section">Section</a>
  <span>Current page</span>
</zk-breadcrumb>

Full-screen slide-up on compact layout, centered panel on regular layout.

Methods

Events

Slots

Copy<zk-modal id="login-modal">
  <div slot="content"><zk-login-form></zk-login-form></div>
</zk-modal>

CopyopenButton.addEventListener('click', () => { modal.open = true; });
modal.addEventListener('zk-close', () => { modal.open = false; });

Centered alert dialog — never full-screen, on any platform.

Events

Slots

Copy<zk-alert id="confirm-delete">
  <span slot="title">Delete?</span>
  <span slot="message">This action can't be undone.</span>
  <button slot="actions" data-id="cancel" data-role="cancel">Cancel</button>
  <button slot="actions" data-id="confirm" data-destructive>Delete</button>
</zk-alert>

Contextual choice list — bottom sheet on compact layout, small centered panel on regular layout.

Methods

Events

Copy<zk-action-sheet id="post-actions">
  <button data-id="reply">Reply</button>
  <button data-id="delete" data-destructive>Delete</button>
  <button data-id="cancel" data-role="cancel">Cancel</button>
</zk-action-sheet>

Non-blocking, auto-dismissing feedback message — purely imperative API.

Methods

Copy<zk-toast id="toast"></zk-toast>

Copytoast.show('Card saved!', { icon: 'check' });

Soft pre-permission prompt shown before the real OS dialog — since a denied OS prompt on iOS can't be re-triggered without a manual Settings visit.

Events

Slots

Copyprompt.addEventListener('zk-accept', () => app.push.subscribe());

Email/password fields. Does not call any auth adapter itself.

Events

Slots

CopyloginForm.addEventListener('zk-submit', (e) => {
  app.auth.login({ email: e.detail.email, password: e.detail.password });
});

Grouped list, Settings.app style. Fully data-driven via the .sections property (not an attribute). Toggle rows render as a real <zk-switch> internally rather than a native checkbox.

Each row accepts an optional icon field (an icon name), rendered before the label for any row type.

Events

CopysettingsForm.sections = [
  { id: 'appearance', title: 'Appearance', rows: [
    { id: 'dark-mode', label: 'Force dark mode', icon: 'moon', type: 'toggle', value: false },
  ]},
  { id: 'account', title: 'Account', rows: [
    { id: 'logout', label: 'Sign out', icon: 'user', type: 'link' },
  ]},
];

settingsForm.addEventListener('zk-change', (e) => {
  if (e.detail.rowId === 'dark-mode') {
    themeProvider.setAttribute('theme', e.detail.value ? 'dark' : 'auto');
  }
});

OTP input with separated boxes — auto-advance focus, backspace navigation, full-code paste support.

Events

Copy<zk-code-validation-form length="6"></zk-code-validation-form>

Debounced search bar with a leading search icon. On compact layout, focus expands it into a full-screen overlay with a Cancel button; once there's a value, an inline clear button also appears (both dispatch zk-search with an empty query).

Events

Slots

Copy<zk-search-engine placeholder="Search a topic…"></zk-search-engine>

Copysearch.addEventListener('zk-search', (e) => { store.state.query = e.detail.query; });

iOS-style wheel picker built on CSS scroll-snap.

Events

Copy<zk-picker>
  <option value="a">Option A</option>
  <option value="b" selected>Option B</option>
</zk-picker>

Styled wrapper around native <input type="range">.

Events

Copy<zk-slider min="0" max="100" value="40"></zk-slider>

iOS-style toggle switch.

Events

Copy<zk-switch checked></zk-switch>

iOS-style segmented control with a sliding highlight.

Events

Copy<zk-segmented-control value="a">
  <button value="a">A</button>
  <button value="b">B</button>
</zk-segmented-control>

Flippable image/fact card. Added while building the PixLearn example, promoted to the shared catalog as broadly reusable.

Events

Copyconst el = document.createElement('zk-image-card');
el.setAttribute('image', card.image);
el.setAttribute('title', card.title);
el.setAttribute('fact', card.fact);
el.setAttribute('likes', String(card.likes));
el.toggleAttribute('liked', card.liked);

In-app scrollable log panel mirroring console.log/info/warn/error/debug — useful since installed iOS PWAs have no devtools access. Caps at 200 entries.

Copy<zk-logs-viewer></zk-logs-viewer>

Illustrated empty-state placeholder. The icon slot defaults to <zk-icon name="inbox" size="36"> inside a circular badge when the consumer doesn't supply their own.

Slots

Copy<zk-empty-state>
  <zk-icon slot="icon" name="bookmark" size="36"></zk-icon>
  <span slot="title">No saved cards</span>
  <span slot="message">Save cards from Discover to find them here.</span>
</zk-empty-state>

Shimmering placeholder block, and an indeterminate rotating spinner.

Copy<zk-loading-skeleton width="240px" height="14px"></zk-loading-skeleton>
<zk-spinner size="20"></zk-spinner>

Swipeable carousel with a dots indicator, built on native CSS scroll-snap.

Events

Slots

Copy<zk-onboarding-carousel>
  <div slot="slide">Welcome!</div>
  <div slot="slide">Discover the features.</div>
</zk-onboarding-carousel>

Catches uncaught errors app-wide via window error/unhandledrejection listeners (Web Components have no render tree to wrap in try/catch), swapping to the fallback slot.

Methods

Events

Slots

Copy<zk-error-boundary>
  <div id="app">...</div>
  <div slot="fallback">
    <p>Something went wrong.</p>
    <button onclick="location.reload()">Reload</button>
  </div>
</zk-error-boundary>

A self-contained image-sharing / learning app: browse a feed of flippable image cards, reveal an educational fact, like/save/create cards, search, and manage settings — no backend, all local (IndexedDB via storagePlugin, a mock auth adapter).

What it exercises

Run it from the repo root: pnpm dev, then open /examples/pixlearn/index.html. Sign in with any email/password (mock auth, no validation).

Surfaced while documenting the current source — not bugs the docs paper over, but real behavior to design around today.

Full history lives in CHANGELOG.md at the repo root — Sprint 1 (core skeleton + first working slice), Sprint 2+3 (full UI catalog, router, store, remaining plugins), and the PixLearn example app with two real bugs fixed along the way.