@mangtre/core 0.1.0

package/LICENSE

@@ -0,0 +1,26 @@
+Măng — Proprietary License
+
+Copyright © 2026 RumitX. All rights reserved.
+
+This software and its source code (the "Software"), including the Măng shell,
+the @mangtre/* packages, and the bundled mini-apps in this repository, are the
+confidential and proprietary property of RumitX.
+
+No license, right, or permission is granted to any person to use, copy, modify,
+merge, publish, distribute, sublicense, sell, or create derivative works of the
+Software, in whole or in part, without the prior written consent of RumitX.
+
+Unauthorized copying, distribution, or use of the Software, via any medium, is
+strictly prohibited.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL RUMITX BE LIABLE
+FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Note: this proprietary notice protects the codebase during the early (NOW)
+horizon. When Măng opens to third-party creators, a separate license may be
+issued for the fork-able starter kit.
+
+For licensing inquiries: RumitX — https://rumitx.com

package/dist/index.d.ts

@@ -0,0 +1,706 @@
+/**
+ * @mangtre/core — the stable contract between the Măng shell and every mini-app.
+ *
+ * Golden rule: a mini-app NEVER touches real storage, `fetch`, or native APIs
+ * directly — always through `sdk.*`. Today these are backed by the monolith
+ * (dynamic import); later by a sandbox bridge. The app changes zero lines.
+ *
+ * See `sot/Mang_Tech_Foundations_v0.1.1.md` §2.
+ */
+/** Capabilities a mini-app may request. Declared up front, even if granted freely now. */
+type Permission = "storage" | "theme" | "ai" | "identity" | "context" | "data";
+/**
+ * Languages Măng ships. The shell owns the active locale (detect + switch + persist) and
+ * hands it to every mini-app at mount via `MangCore.locale`. Vietnamese-first; English second.
+ */
+type Locale = "vi" | "en";
+/** A short string in every language Măng ships. */
+type LocalizedText = Record<Locale, string>;
+/**
+ * Where a mini-app feature can run. The shell can host an app on different *surfaces*, each with a
+ * different capability ceiling: `desktop` (Tauri Win/Mac — native sidecar, filesystem, heavy/local
+ * AI) is highest; `web` (browser + PWA — sandboxed, no heavy local AI) is mid; `zalo` (Zalo Mini
+ * App runtime) is most constrained. `"web"` covers PWA too (install/offline add nothing to the
+ * capability ceiling). Mobile-native is LATER — deliberately not in this union yet.
+ *
+ * Declared per feature so a single app can mix surfaces (e.g. "generate quiz with AI" → desktop
+ * only; "view/answer quiz" → everywhere). See `sot/Mang_Tech_Foundations` §2.1.
+ */
+type Surface = "desktop" | "web" | "zalo";
+/**
+ * A feature a mini-app exposes to the shell so it can be searched and launched directly from the
+ * host (e.g. the command palette). Declared STATICALLY on the manifest, so the shell can index
+ * every app's features WITHOUT loading its (code-split) runtime — keep this module data-only.
+ * The shell hands the chosen `id` back to the app at mount via `MangCore.launch`.
+ */
+interface MangCommand {
+    /** Unique within the app, e.g. "history", "export", "jwt". Becomes the `/app/<id>/<command>` segment. */
+    id: string;
+    /** Shown in the palette — the app owns its own copy (vi + en). */
+    title: LocalizedText;
+    /** Extra search terms beyond the title ("csv", "bảng công", "decode"). */
+    keywords?: string[];
+    /** Emoji for the palette row; falls back to the app icon. */
+    icon?: string;
+    /**
+     * Surfaces this feature runs on. Omitted = ALL surfaces (the default — runs everywhere).
+     * Narrows within the app's `MangManifest.surfaces` envelope; a command should not claim a
+     * surface its app doesn't support. The shell will LATER use this to badge/disable unsupported
+     * features (an unavailable feature stays discoverable, never silently hidden) — for now it is a
+     * declared seam with no runtime gating. See `sot/Mang_Tech_Foundations` §2.1.
+     */
+    surfaces?: Surface[];
+}
+/**
+ * One screen in a mini-app's **main flow** (luồng chính) — the canonical happy-path a reviewer (and
+ * LATER a bot) walks to PROVE the real screens render and to AUTO-CAPTURE the store gallery/guide.
+ * Declared STATICALLY on the manifest (data-only, like `commands`) so the platform can read the flow
+ * WITHOUT loading the app's runtime.
+ *
+ * The contract a step asserts is a single DOM convention: when the screen is ready, the app MUST
+ * render an element carrying `data-mang-checkpoint="<step.checkpoint>"`. The walker navigates to the
+ * step (re-mounting with `launch: { command }`), waits for that element, screenshots, and records
+ * pass/fail. Populated screens come from the optional `MiniAppModule.prepareDemo` seed — steps do NOT
+ * simulate typing/clicking. See `sot/Mang_Tech_Foundations` §2.8.
+ */
+interface FlowStep {
+    /** Unique within the app, e.g. "home", "settle". Becomes the screenshot/file key. */
+    id: string;
+    /** Step label shown in the generated guide (vi + en). */
+    title: LocalizedText;
+    /**
+     * A `MangCommand.id` to activate this screen via the launch seam. Omitted = the app's default
+     * screen on a plain mount (use for the first step / single-screen apps).
+     */
+    command?: string;
+    /**
+     * The app MUST render `[data-mang-checkpoint="<this>"]` when this screen is ready. This single DOM
+     * marker is the whole contract the walker waits on; a missing checkpoint fails the step.
+     */
+    checkpoint: string;
+    /** Optional caption shown under the captured screenshot in the guide. */
+    caption?: LocalizedText;
+    /**
+     * Surfaces this step applies to. Omitted = ALL (default). Narrows within the app's `surfaces`
+     * envelope — lets a desktop-only screen be skipped when walking the web surface.
+     */
+    surfaces?: Surface[];
+}
+/**
+ * An app's declared AI needs. DECLARATION-ONLY this phase (mirrors `surfaces`): the shell will
+ * LATER use it to badge / route / pre-warm / provision, but nothing gates on it now. This is the
+ * developer-facing contract that lets a creator TARGET the platform's AI seam ("I need a 'quality'
+ * power") instead of shipping their own model — local today, possibly remote LATER, zero app change.
+ * See `sot/Mang_Tech_Foundations` §2.4.
+ */
+interface MangAiDeclaration {
+    /** Capability tiers the app's AI features rely on. The shell may use this to recommend downloads. */
+    capabilities: AICapability[];
+}
+/**
+ * An app's declared remote-data needs. DECLARATION-ONLY this phase (mirrors `ai`/`surfaces`): the
+ * shell uses it to BADGE the app (☁️ cloud-backed, ⚡ realtime) and LATER to route/provision, but
+ * nothing gates on it at runtime. This is the developer-facing contract that lets a creator TARGET
+ * the platform's hosted-data seam ("my app keeps data on Măng's server / is multiplayer") instead
+ * of shipping their own backend — the implementation (polling today, realtime LATER) swaps with zero
+ * app change. See `sot/Mang_Tech_Foundations` §2.7.
+ */
+interface MangDataDeclaration {
+    /**
+     * The app coordinates many users on ONE shared dataset (a room shared by link). Drives the ⚡
+     * "Thời gian thực / nhiều người" badge. Omitted/false = private cross-device save only.
+     */
+    shared?: boolean;
+    /**
+     * The app benefits from live updates (vs. occasional save/restore). Today every transport is
+     * near-live (poll); a future WebSocket transport makes it truly realtime — declaration is stable.
+     */
+    realtime?: boolean;
+}
+/** A mini-app's identity + declared permissions + the features it exposes to the shell. */
+interface MangManifest {
+    /** Stable slug, e.g. "chia-tien-nhom". Also the storage namespace. */
+    id: string;
+    name: string;
+    /** Emoji or asset reference for the launcher. */
+    icon: string;
+    version: string;
+    permissions: Permission[];
+    /** Features the app exposes to the host (searchable + launchable). Optional + additive. */
+    commands?: MangCommand[];
+    /**
+     * Surfaces the app supports overall (its envelope). Omitted = ALL surfaces. A `MangCommand`'s own
+     * `surfaces` narrows within this. See `sot/Mang_Tech_Foundations` §2.1.
+     */
+    surfaces?: Surface[];
+    /**
+     * The app's **main flow** (luồng chính) — the canonical happy-path screens, in order, that the
+     * platform walks to verify the app renders and to auto-capture its gallery/guide. A standard part
+     * of the mini-app contract (declared in code, not just docs); see `sot/Mang_Tech_Foundations` §2.8.
+     * Optional in the type but REQUIRED by curation policy (validation warns when absent, will fail).
+     */
+    flow?: FlowStep[];
+    /**
+     * Declared AI capabilities (developer-facing contract). Present only when `permissions` includes
+     * "ai". Declaration-only now (no runtime gate), like `surfaces`. See `sot/Mang_Tech_Foundations` §2.4.
+     */
+    ai?: MangAiDeclaration;
+    /**
+     * Declared remote-data needs (developer-facing contract). Present only when `permissions` includes
+     * "data". Declaration-only now (drives badges), like `ai`. See `sot/Mang_Tech_Foundations` §2.7.
+     */
+    data?: MangDataDeclaration;
+}
+/**
+ * What the shell asks a mini-app to do at mount. Set when the app is opened via a command
+ * (palette, deep link `/app/<id>/<command>`); absent on a plain open. The app reads it once on
+ * mount and routes to that feature. A focused launch seam — distinct from the reserved
+ * `context?` (Tre SDK) seam.
+ */
+interface LaunchIntent {
+    /** The `MangCommand.id` the app should activate. */
+    command: string;
+    /** Optional extra arguments for the command (reserved; unused by current apps). */
+    params?: Record<string, string>;
+}
+/**
+ * Per-app key/value storage. Local now (e.g. localStorage/IndexedDB), sync later —
+ * the app cannot tell the difference. Keys are scoped to the owning app.
+ */
+interface ScopedStorage {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, val: T): Promise<void>;
+    list(prefix?: string): Promise<string[]>;
+}
+/**
+ * Măng brand design tokens, supplied by the shell (values live in `@mangtre/ui`).
+ * Palette per `sot/Mang_Art_Direction_v0.2.md` §5 — the Măng *product* identity
+ * ("Mầm số" — clean-modern, organic-bamboo), NOT the RumitX studio palette. The shell chrome wears
+ * these; a mini-app MAY use them but isn't required to (creator apps style
+ * themselves). The single shared thread with RumitX is `mangGreen`.
+ */
+interface ThemeTokens {
+    color: {
+        mangGreen: string;
+        shoot: string;
+        bamboo: string;
+        soil: string;
+        sun: string;
+        paper: string;
+        dark: string;
+    };
+    font: {
+        heading: string;
+        body: string;
+    };
+}
+/** Sign-in / identity client. Reserved seam. */
+type IdentityClient = Record<string, never>;
+/** Shared context/memory layer ("Tre SDK", a future bet — NOT `tre-mem`). Reserved seam. */
+type TreContext = Record<string, never>;
+/** Why local AI isn't usable right now — drives the app's degraded-mode copy. */
+type AIUnavailableReason = "no-runtime" | "no-model" | "unknown";
+/**
+ * What KIND of work a request needs — a device-/transport-neutral tier the resolver maps to a
+ * concrete model. The app expresses INTENT ("I need quality Vietnamese text"); it never names a
+ * model. The resolver (TS transport + Rust `ai.rs`) routes tier → model and DEGRADES to a smaller
+ * installed model rather than hard-failing. User-facing, each tier is a white-label "power"
+ * ("Năng lực AI") — the user never sees the tier id or the model. Researched local roles today:
+ *   - "fast"      → tiny router/classifier (qwen3:0.6b)
+ *   - "balanced"  → everyday default (qwen3:1.7b)            ← the seam's default tier
+ *   - "quality"   → best text + strong Vietnamese (qwen3:4b-instruct-2507-q4_K_M)
+ *   - "code"      → code generation/editing (qwen2.5-coder:1.5b / 3b)
+ *   - "reasoning" → deep/multi-step (qwen2.5 ~7B)
+ * Open by intent, NOT by model: a future remote transport maps the SAME tiers to its own models.
+ */
+type AICapability = "fast" | "balanced" | "quality" | "code" | "reasoning";
+/** The tier assumed when a request omits `capability` — keeps `generate()` fully backward-compatible. */
+declare const DEFAULT_AI_CAPABILITY: AICapability;
+/**
+ * The user-facing "power" (năng lực AI) — the white-label face of an `AICapability`, presented
+ * WITHOUT naming a model or runtime. The setup/onboarding UI renders these chips instead of model
+ * ids; one power may be backed by several downloadable models (the resolver's table decides). Labels
+ * are localized because they're a primary user surface (Vietnamese-first).
+ */
+interface AIPower {
+    /** The capability tier this power represents. */
+    capability: AICapability;
+    /** Short user-facing name, e.g. { vi: "Trả lời nhanh", en: "Quick answers" }. */
+    label: LocalizedText;
+    /** One-line description of what this power does — no model/runtime jargon. */
+    description: LocalizedText;
+    /** Emoji/asset for the power chip. */
+    icon: string;
+}
+/** Whether local AI can run right now, and which models / powers are available. */
+interface AIStatus {
+    /** True only when a runtime is reachable AND at least one model is pulled. */
+    ready: boolean;
+    /** Model ids the runtime reports (e.g. "llama3.2", "qwen2.5"); empty when none. */
+    models: string[];
+    /** Set when `ready` is false, so the app can tell the user exactly what to fix. */
+    reason?: AIUnavailableReason;
+    /**
+     * Which capability tiers can run RIGHT NOW given what's installed (every entry resolves to some
+     * model after degradation). Empty/absent when not ready. Lets the UI show available powers without
+     * leaking model ids. Optional → shells that don't populate it still type-check.
+     */
+    capabilities?: AICapability[];
+    /**
+     * Where the ready AI runs. "local" = on-device (Ollama today; nothing leaves the device).
+     * "remote" is RESERVED for a LATER hosted transport — no remote impl ships now. Optional; absent
+     * is treated as "local" by consumers. This is the drop-in seam for the local/remote split.
+     */
+    source?: "local" | "remote";
+}
+/** One text-generation request. The app owns prompt wording + any output parsing. */
+interface AIGenerateRequest {
+    /** The user/content prompt. */
+    prompt: string;
+    /** Optional system instruction (role / format guidance). */
+    system?: string;
+    /** Ask the model to return strict JSON (enables the runtime's JSON mode where supported). */
+    json?: boolean;
+    /** Cooperative cancellation (e.g. the user navigates away mid-generation). */
+    signal?: AbortSignal;
+    /**
+     * What KIND of work this needs. The transport resolves it to a concrete model (tier-aware +
+     * device-aware: degrades to the best smaller installed model, never hard-fails). Omitted →
+     * `DEFAULT_AI_CAPABILITY` ("balanced"). The app NEVER names a model — that's the resolver's job.
+     */
+    capability?: AICapability;
+}
+/** A completed generation. `text` is RAW model output — the app parses/validates it. */
+interface AIGenerateResult {
+    text: string;
+    /** The model that actually answered (for display / a non-PII analytics dimension). */
+    model: string;
+    /** The tier this request resolved against (after any device degradation). Optional, display-only. */
+    capability?: AICapability;
+}
+/**
+ * A model the shell recommends the user download — a curated, transport-owned whitelist (the app
+ * never hardcodes model ids). Small/fast variants come first so first-run generation is quick.
+ */
+interface AIModelOption {
+    /** The runtime's model id to pull, e.g. "llama3.2:3b". */
+    id: string;
+    /** Short display name, e.g. "Llama 3.2". */
+    label: string;
+    /** Human download-size hint, e.g. "~2 GB". */
+    sizeLabel: string;
+    /** The default pick the UI should highlight. */
+    recommended?: boolean;
+    /**
+     * The capability tier(s) this model best serves — lets setup group downloads by power
+     * ("install this to unlock the 'Chất lượng cao' power"). Optional + additive.
+     */
+    capabilities?: AICapability[];
+}
+/** Progress of a model download. `percent` is 0..100 when the runtime reports byte totals. */
+interface AIPullProgress {
+    /** Coarse phase label from the runtime (e.g. "downloading", "verifying"). */
+    status: string;
+    /** 0..100 when known; omitted while the runtime hasn't reported totals yet. */
+    percent?: number;
+}
+/** Options for a model download: progress callback + cooperative cancellation. */
+interface AIPullOptions {
+    onProgress?: (progress: AIPullProgress) => void;
+    signal?: AbortSignal;
+}
+/**
+ * Local-first AI capability ("the brain on the user's own machine"). Present ONLY on a shell that
+ * can host a model runtime — today the Tauri desktop shell talking to a local **Ollama** server, so
+ * NOTHING leaves the device. Web / PWA / Zalo leave this `undefined`; guard at call sites:
+ * `sdk.ai?.generate(...)`. The app MUST degrade gracefully when absent (manual paths stay usable).
+ *
+ * **Transport-agnostic by design:** the implementation (local Ollama today; a hosted/metered
+ * provider is a LATER swap — see Roadmap) lives behind this interface, so the mini-app never
+ * changes. Text-in / text-out on purpose — prompt templates and output parsing belong to the app,
+ * not the seam. See `sot/Mang_Tech_Foundations` §2.4.
+ *
+ * The onboarding members (`recommendedModels` / `pull` / `openInstall`) are OPTIONAL: they let an
+ * app guide a first-run user to install the runtime + download a model in-app, but a future hosted
+ * transport (nothing to install) simply omits them. Guard with optional chaining.
+ */
+interface AIClient {
+    /** Probe the local runtime: is a model reachable right now? Cheap; safe to call on mount. */
+    status(): Promise<AIStatus>;
+    /** Generate text from a prompt. Rejects on failure (no runtime, timeout, model error). */
+    generate(req: AIGenerateRequest): Promise<AIGenerateResult>;
+    /** The curated download whitelist for this runtime (small/fast first). Absent on hosted transports. */
+    recommendedModels?(): AIModelOption[];
+    /**
+     * The user-facing powers ("năng lực AI") this transport can offer — the white-label face of its
+     * capability tiers. The setup UI renders these instead of model ids. Absent on transports that
+     * don't expose a power list. See `sot/Mang_Tech_Foundations` §2.4.
+     */
+    powers?(): AIPower[];
+    /**
+     * Download a model into the local runtime, reporting progress. Resolves when the model is ready;
+     * rejects on failure or cancellation. Present only when the runtime supports in-app downloads.
+     */
+    pull?(model: string, opts?: AIPullOptions): Promise<void>;
+    /** Open the runtime's install page in the OS browser (guided setup when no runtime is found). */
+    openInstall?(): Promise<void>;
+}
+/**
+ * A single usage event. NON-PII by contract: describe WHAT happened (a feature was used), never
+ * WHO did it or sensitive values (no names, no amounts, no free text). `props` carry small
+ * dimensions only — enums / counts / booleans — so the same event is safe to send anywhere a
+ * remote sink lands later.
+ */
+interface AnalyticsEvent {
+    /** Dotted name the emitter owns, e.g. "expense.added", "report.exported". */
+    name: string;
+    /** Non-PII dimensions only: small enums / counts / booleans. */
+    props?: Record<string, string | number | boolean>;
+}
+/**
+ * What the shell's sink receives — an `AnalyticsEvent` plus provenance the emitter shouldn't set
+ * itself. `source` is `"shell"` for host events, or the mini-app id for app events (the SDK tags it).
+ */
+interface TrackedEvent extends AnalyticsEvent {
+    source: string;
+}
+/**
+ * Mini-app-facing analytics capability. Fire-and-forget: `track` never throws and never blocks the
+ * UI. Like the other optional seams, it's present only when the shell supplies a sink — guard with
+ * `sdk.analytics?.track(...)`. The default sink keeps events on-device (local-first); a remote sink
+ * (Cloudflare Workers Analytics Engine via the shell's `_worker.js`, or a vendor) is a LATER swap
+ * that changes zero lines here. See `sot/Mang_Tech_Foundations` §2.2.
+ */
+interface AnalyticsClient {
+    track(event: AnalyticsEvent): void;
+}
+/** The kind of payload a nearby device handed off — mirrors Smart Paste's own input space. */
+type HandoffKind = "text" | "json" | "image";
+/**
+ * One payload handed off from a nearby device on the same network. NON-PII by contract:
+ * `sourceDevice` is a coarse display label ("iPhone"), never an id / IP / account. The envelope
+ * is **versioned** (`v`) so a transport can evolve its shape without breaking older receivers
+ * (cf. the chia-tien-nhom share-link wire v1/v2). This is a ONE-SHOT handoff, NOT live sync.
+ */
+interface HandoffPayload {
+    /** Envelope version. Bump when the shape changes; receivers validate it. */
+    v: 1;
+    kind: HandoffKind;
+    /** `text`/`json`: the raw string. `image`: a `data:image/<mime>;base64,...` data URL. */
+    data: string;
+    /** Short human label for the sender ("iPhone", "Pixel"). Display-only, non-PII. */
+    sourceDevice: string;
+    /** Epoch ms when the receiving shell got it (stamped by the sink). */
+    receivedAt: number;
+}
+/** A subscriber the mini-app registers to receive handed-off payloads. */
+type HandoffListener = (payload: HandoffPayload) => void;
+/**
+ * How a sender connects — rendered by the receiver UI, NOT assumed to be a LAN URL. Today's LAN
+ * transport encodes a `http://<lan-ip>:<port>/h#t=<token>` URL as a QR (`mode: "lan-qr"`); a future
+ * WebRTC transport could instead surface a short pairing `code`. Transport-neutral so the seam
+ * outlives any single mechanism.
+ */
+interface HandoffPairing {
+    /** Open union so new transports add modes additively without a breaking change. */
+    mode: "lan-qr" | string;
+    /** Opaque payload to render as a QR (LAN: the URL + token). */
+    qr?: string;
+    /** Human-readable pairing code (e.g. WebRTC signaling). Reserved — unused by the LAN transport. */
+    code?: string;
+}
+/**
+ * Receive-only inbound channel for device handoff ("paste from a nearby device"). Present ONLY
+ * when the shell can host a transport — today the Tauri desktop shell + a local LAN server.
+ * Web / PWA / Zalo builds leave this `undefined`; guard at call sites: `sdk.handoff?.onPayload(...)`.
+ *
+ * **Transport-agnostic by design:** the implementation (LAN-HTTP today, WebRTC/BLE/relay later)
+ * swaps behind this interface, so the mini-app never changes. This is a ONE-SHOT handoff seam,
+ * NOT live multi-device sync (sync stays parked — see `sot/Mang_Tech_Foundations` §2.3 / Roadmap).
+ */
+interface HandoffInbox {
+    /** Subscribe to incoming payloads. Returns an unsubscribe fn. Fires once per payload. */
+    onPayload(listener: HandoffListener): () => void;
+    /** Current connect-descriptor for the sender to scan/enter, or `null` until the transport is ready. */
+    pairing(): HandoffPairing | null;
+    /**
+     * Subscribe to "a sender device connected" signals (a nearby device opened the sender page) so the
+     * receiver can show a live "📱 connected" state. Carries the coarse, non-PII device label. Optional:
+     * present only when the transport reports sender presence. Returns an unsubscribe fn.
+     */
+    onSenderSeen?(listener: (device: string) => void): () => void;
+}
+/**
+ * How a room is shared. `"private"` = one creator/device's cross-device save (a personal cloud
+ * backup); `"shared"` = many users coordinate on ONE dataset via a room link (the multiplayer case).
+ * The shell injects the owning app id server-side, so a room is always scoped to its app.
+ */
+type DataMode = "private" | "shared";
+/** A room the app is currently joined to. The `roomKey` capability lives in the SHELL, never here. */
+interface DataRoomInfo {
+    /** Public id (safe to put in a share link). */
+    roomId: string;
+    mode: DataMode;
+}
+/**
+ * Whether the data seam can talk to the server right now, and over which transport. `transport`
+ * is informational only — the app behaves identically whether it's near-live polling ("poll") or
+ * a future WebSocket ("ws"). Absent/`ready:false` → the app should fall back to local-only paths.
+ */
+interface DataStatus {
+    ready: boolean;
+    reason?: string;
+    transport?: "poll" | "ws";
+}
+/**
+ * One change observed in the joined room — a key was written (`value` set) or deleted (`value: null`).
+ * `rev` is the room-wide monotonic revision after the change (also the optimistic-concurrency token).
+ */
+interface DataChange<T = unknown> {
+    key: string;
+    value: T | null;
+    rev: number;
+}
+/**
+ * Hosted key/value data with optional live sharing — the SERVER-backed sibling of `ScopedStorage`.
+ * Present ONLY when the shell supplies a data transport (web/desktop with the platform API reachable
+ * + the app holds the `"data"` permission). Web/PWA before this lands, or unsupported surfaces, leave
+ * it `undefined`; guard at call sites: `sdk.data?.set(...)`. The app MUST degrade to local-only when
+ * absent — the seam is additive, never load-bearing for the core experience.
+ *
+ * **A room is a capability, not an account.** `createRoom` returns a `roomId` + an unguessable
+ * `roomKey`; whoever holds the key can read/write/subscribe (the same trust model as today's
+ * `#g1=`/`#tkb=` share links, now server-backed and live). No end-user login, no PII — an anonymous
+ * device id tags writes for presence only. The SHELL stores the `roomKey` and brokers every call;
+ * the app passes only keys + values. The app can only ever touch ITS OWN app's rooms (the host
+ * injects the app id).
+ *
+ * **Transport-agnostic by design:** near-live polling today, WebSocket realtime + presence LATER —
+ * the implementation swaps behind this interface with zero app change. Values are JSON-serializable;
+ * the app owns its own data schema. See `sot/Mang_Tech_Foundations` §2.7.
+ */
+interface DataClient {
+    /** Can the seam reach the server right now? Cheap; safe to call on mount. */
+    status(): Promise<DataStatus>;
+    /**
+     * Create a fresh room and join it. Returns the public `roomId` plus the secret `roomKey` capability
+     * (put both in a share link to invite others). The shell remembers the key for subsequent calls.
+     */
+    createRoom(opts?: {
+        mode?: DataMode;
+    }): Promise<{
+        roomId: string;
+        roomKey: string;
+        mode: DataMode;
+    }>;
+    /** Join an existing room with its `roomKey` (e.g. from an opened share link). */
+    joinRoom(roomId: string, roomKey: string): Promise<DataRoomInfo>;
+    /** The room the app is joined to, or `null` before any create/join. */
+    current(): DataRoomInfo | null;
+    /** Read a key from the joined room. `null` when the key is absent (no room joined → rejects). */
+    get<T>(key: string): Promise<{
+        value: T | null;
+        rev: number;
+    } | null>;
+    /**
+     * Write a key. `expectedRev` enables optimistic concurrency: pass the `rev` you last saw and the
+     * write rejects with a conflict if someone else wrote in between (omit to force-write). Resolves
+     * with the new room-wide `rev`.
+     */
+    set<T>(key: string, val: T, expectedRev?: number): Promise<{
+        rev: number;
+    }>;
+    /** Delete a key (optionally guarded by `expectedRev`). */
+    remove(key: string, expectedRev?: number): Promise<{
+        rev: number;
+    }>;
+    /** List keys in the joined room (optionally by prefix) with each key's current `rev`. */
+    list(prefix?: string): Promise<{
+        key: string;
+        rev: number;
+    }[]>;
+    /**
+     * Revoke the joined room: its capability stops working for everyone and live subscribers are cut. Use
+     * to "stop sharing". The app should drop its local room pointer after this. No-op if no room is joined.
+     */
+    revoke(): Promise<void>;
+    /**
+     * Rotate the joined room's capability (e.g. a shared link leaked): returns a NEW `roomKey` to re-share;
+     * old links stop working and live subscribers are cut. The shell keeps using the room with the new key.
+     */
+    rotateKey(): Promise<{
+        roomKey: string;
+    }>;
+    /**
+     * Subscribe to changes in the joined room. Fires once per observed change. Returns an unsubscribe
+     * fn. Near-live (poll) today; a future transport makes it instantaneous — the callback shape is
+     * identical, so the app never changes.
+     */
+    subscribe<T>(listener: (change: DataChange<T>) => void): () => void;
+}
+/** Everything the shell hands a mini-app at mount time. */
+interface MangCore {
+    storage: ScopedStorage;
+    theme: ThemeTokens;
+    /**
+     * Active UI language, chosen by the shell. Ambient runtime config (always present, like
+     * `theme`) — NOT a gated `Permission`. A mini-app SHOULD localize against it (e.g. via the
+     * `@mangtre/i18n` helper); the shell re-mounts the app when the user switches language.
+     */
+    locale: Locale;
+    /**
+     * The feature the shell wants active for THIS mount (set when opened via a command/deep link).
+     * Ambient like `theme`/`locale`, not a gated `Permission`. The shell re-mounts the app when the
+     * launch command changes, so reading it once on mount is enough.
+     */
+    launch?: LaunchIntent;
+    /**
+     * Local-first AI. Present ONLY on a shell that can host a model runtime — today the Tauri desktop
+     * shell + a local Ollama server (nothing leaves the device). Web / PWA / Zalo leave it `undefined`.
+     * Guard at call sites: `sdk.ai?.generate(...)`; the app degrades to manual paths when absent.
+     */
+    ai?: AIClient;
+    identity?: IdentityClient;
+    context?: TreContext;
+    /**
+     * Usage analytics. Present only when the shell supplies a sink. Local-first today (events buffer
+     * on-device); remote sink is a LATER swap. Guard at call sites: `sdk.analytics?.track(...)`.
+     */
+    analytics?: AnalyticsClient;
+    /**
+     * Inbound device handoff ("paste from a nearby device"). Present ONLY on a shell that can host a
+     * transport — today the Tauri desktop shell (LAN server). Receive-only, one-shot (NOT sync), and
+     * transport-agnostic. Guard at call sites: `sdk.handoff?.onPayload(...)`. See Tech Foundations §2.3.
+     */
+    handoff?: HandoffInbox;
+    /**
+     * Hosted data + live rooms ("Phòng sống") — the server-backed sibling of `storage`. Present ONLY
+     * when the shell supplies a data transport and the app holds the `"data"` permission. Lets a
+     * mini-app keep data on Măng's server and (with a room link) share ONE live dataset across many
+     * users — no backend, no end-user login, capability-based. Guard at call sites: `sdk.data?.set(...)`;
+     * the app degrades to local-only when absent. See Tech Foundations §2.7.
+     */
+    data?: DataClient;
+}
+/** Tear-down handle returned by a mini-app's `mount`. */
+type Unmount = () => void;
+/** The single entry every mini-app exports. */
+type Mount = (root: HTMLElement, sdk: MangCore) => Unmount;
+/**
+ * Optional hook a mini-app exports to seed DEMO state before its main flow is walked. Runs ONCE
+ * (before the first flow step) against the same `sdk.storage` the app reads on mount, so the
+ * subsequent re-mounts show populated screens for screenshots. Reuse the app's existing sample/seed
+ * logic. No-op / absent ⇒ the flow walks against whatever a fresh mount shows. See Tech Foundations §2.8.
+ */
+type PrepareDemo = (sdk: MangCore) => Promise<void>;
+/** Shape of a mini-app module loaded by the runtime. */
+interface MiniAppModule {
+    manifest: MangManifest;
+    mount: Mount;
+    /** Seeds demo state for the flow walker; see {@link PrepareDemo}. */
+    prepareDemo?: PrepareDemo;
+}
+
+/**
+ * Tiny runtime guards for narrowing **untrusted JSON at a boundary** into typed values.
+ *
+ * A mini-app owns its own data schema (Măng stores opaque JSON — see {@link ScopedStorage} and
+ * `DataClient`). But data coming *back in* — a live-room snapshot another device wrote, a decoded
+ * share link, an old value with a since-changed shape — is semi-trusted input. Validate it before
+ * trusting it, or risk corrupting local state (or worse, an injection if the value reaches the DOM).
+ *
+ * These helpers follow the codebase's existing defensive style: **return `undefined` on anything
+ * malformed** (never throw), so a caller drops a bad payload instead of crashing. They are
+ * dependency-free on purpose — mini-app bundles are size-capped and statically scanned, so pulling a
+ * full schema library (zod, etc.) is the wrong trade here. Compose them to validate a whole record:
+ *
+ * ```ts
+ * import { isRecord, asString, asFiniteNumber, asArrayOf } from "@mangtre/core";
+ *
+ * interface Todo { id: string; text: string; done: boolean }
+ *
+ * function parseTodo(v: unknown): Todo | undefined {
+ *   if (!isRecord(v)) return undefined;
+ *   const id = asString(v.id);
+ *   const text = asString(v.text);
+ *   const done = asBoolean(v.done);
+ *   if (id === undefined || text === undefined || done === undefined) return undefined;
+ *   return { id, text, done };
+ * }
+ *
+ * const todos = asArrayOf(incoming, parseTodo); // undefined if ANY item is malformed
+ * ```
+ */
+/** True when `v` is a non-null, non-array object — safe to index its keys as `unknown`. */
+declare function isRecord(v: unknown): v is Record<string, unknown>;
+/** A string, else `undefined`. */
+declare function asString(v: unknown): string | undefined;
+/** A finite number (rejects `NaN` and `±Infinity`), else `undefined`. */
+declare function asFiniteNumber(v: unknown): number | undefined;
+/** A boolean, else `undefined`. */
+declare function asBoolean(v: unknown): boolean | undefined;
+/**
+ * An array whose every item parses with `item`, else `undefined`. Short-circuits: if any item
+ * returns `undefined`, the whole array is rejected (a partially-valid list is still malformed
+ * input). Returns a fresh array; the input is never mutated.
+ */
+declare function asArrayOf<T>(v: unknown, item: (x: unknown) => T | undefined): T[] | undefined;
+
+/**
+ * Thrown when a write fails because the device storage quota is exhausted. Mini-apps
+ * can catch this to show a "storage full" message instead of a generic failure. (Other
+ * write errors propagate as-is.)
+ */
+declare class StorageQuotaError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Monolith implementation of {@link ScopedStorage} over `localStorage`.
+ * Keys are namespaced per app so mini-apps cannot read each other's data.
+ *
+ * This is the "local now" backing. Swapping to a synced backend later means
+ * replacing this factory — mini-apps are unaffected.
+ */
+declare function createScopedLocalStorage(appId: string): ScopedStorage;
+
+interface MonolithSdkOptions {
+    manifest: MangManifest;
+    theme: ThemeTokens;
+    locale: Locale;
+    /** Feature to activate on mount (set when opened via a command/deep link). */
+    launch?: LaunchIntent;
+    /**
+     * Low-level analytics sink supplied by the shell. Absent = the `analytics` seam stays dormant
+     * (no-op via optional chaining). The SDK wraps it into the mini-app's `AnalyticsClient`, tagging
+     * each event's `source` with the app id so the app never sets provenance itself.
+     */
+    track?: (event: TrackedEvent) => void;
+    /**
+     * Inbound device-handoff channel supplied by the shell. Absent = the `handoff` seam stays dormant
+     * (no-op via optional chaining). Receive-only and transport-agnostic; the SDK passes it through
+     * unchanged (no per-app tagging — dev-tools-only this phase). Present only on the desktop shell.
+     */
+    handoff?: HandoffInbox;
+    /**
+     * Local-first AI client supplied by the shell. Absent = the `ai` seam stays dormant (no-op via
+     * optional chaining). Transport-agnostic (local Ollama today); the SDK passes it through unchanged.
+     * Present only on a shell that can host a model runtime — today the Tauri desktop shell.
+     */
+    ai?: AIClient;
+    /**
+     * Hosted-data client supplied by the shell. Absent = the `data` seam stays dormant (no-op via
+     * optional chaining). Transport-agnostic (near-live polling today, WebSocket realtime later); the
+     * SDK passes it through unchanged. The shell builds it per-app (it already knows the app id), so
+     * cross-app isolation is enforced host-side. Present only when the platform API is reachable AND
+     * the app declared the `"data"` permission.
+     */
+    data?: DataClient;
+}
+/**
+ * Build the current (monolith) `MangCore` for a mini-app. Today this wires up
+ * local storage + injected theme. Later, a sandbox bridge produces the same
+ * shape — so mini-apps never change.
+ */
+declare function createMonolithSdk(opts: MonolithSdkOptions): MangCore;
+
+export { type AICapability, type AIClient, type AIGenerateRequest, type AIGenerateResult, type AIModelOption, type AIPower, type AIPullOptions, type AIPullProgress, type AIStatus, type AIUnavailableReason, type AnalyticsClient, type AnalyticsEvent, DEFAULT_AI_CAPABILITY, type DataChange, type DataClient, type DataMode, type DataRoomInfo, type DataStatus, type FlowStep, type HandoffInbox, type HandoffKind, type HandoffListener, type HandoffPairing, type HandoffPayload, type IdentityClient, type LaunchIntent, type Locale, type LocalizedText, type MangAiDeclaration, type MangCommand, type MangCore, type MangDataDeclaration, type MangManifest, type MiniAppModule, type MonolithSdkOptions, type Mount, type Permission, type PrepareDemo, type ScopedStorage, StorageQuotaError, type Surface, type ThemeTokens, type TrackedEvent, type TreContext, type Unmount, asArrayOf, asBoolean, asFiniteNumber, asString, createMonolithSdk, createScopedLocalStorage, isRecord };

package/dist/index.js

@@ -0,0 +1,102 @@
+// src/types.ts
+var DEFAULT_AI_CAPABILITY = "balanced";
+
+// src/guards.ts
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function asString(v) {
+  return typeof v === "string" ? v : void 0;
+}
+function asFiniteNumber(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+function asBoolean(v) {
+  return typeof v === "boolean" ? v : void 0;
+}
+function asArrayOf(v, item) {
+  if (!Array.isArray(v)) return void 0;
+  const out = [];
+  for (const x of v) {
+    const parsed = item(x);
+    if (parsed === void 0) return void 0;
+    out.push(parsed);
+  }
+  return out;
+}
+
+// src/storage.ts
+var StorageQuotaError = class extends Error {
+  constructor(message = "Local storage quota exceeded") {
+    super(message);
+    this.name = "StorageQuotaError";
+  }
+};
+function isQuotaError(e) {
+  return e instanceof DOMException && (e.name === "QuotaExceededError" || e.name === "NS_ERROR_DOM_QUOTA_REACHED" || e.code === 22 || e.code === 1014);
+}
+function createScopedLocalStorage(appId) {
+  const ns = `mang:${appId}:`;
+  return {
+    async get(key) {
+      const raw = localStorage.getItem(ns + key);
+      if (raw === null) return null;
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return null;
+      }
+    },
+    async set(key, val) {
+      try {
+        localStorage.setItem(ns + key, JSON.stringify(val));
+      } catch (e) {
+        if (isQuotaError(e)) throw new StorageQuotaError();
+        throw e;
+      }
+    },
+    async list(prefix = "") {
+      const full = ns + prefix;
+      const keys = [];
+      for (let i = 0; i < localStorage.length; i++) {
+        const k = localStorage.key(i);
+        if (k?.startsWith(full)) {
+          keys.push(k.slice(ns.length));
+        }
+      }
+      return keys;
+    }
+  };
+}
+
+// src/sdk.ts
+function createMonolithSdk(opts) {
+  const track = opts.track;
+  return {
+    storage: createScopedLocalStorage(opts.manifest.id),
+    theme: opts.theme,
+    locale: opts.locale,
+    // `launch` is only set on the property when present, so a plain open leaves it `undefined`.
+    ...opts.launch ? { launch: opts.launch } : {},
+    // `analytics` only when the shell supplied a sink; events are tagged with the app id.
+    ...track ? { analytics: { track: (e) => track({ ...e, source: opts.manifest.id }) } } : {},
+    // `handoff` only when the shell can host a transport (desktop); passed through unchanged.
+    ...opts.handoff ? { handoff: opts.handoff } : {},
+    // `ai` only when the shell can host a model runtime (desktop + local Ollama); passed through unchanged.
+    ...opts.ai ? { ai: opts.ai } : {},
+    // `data` only when the shell supplies a hosted-data transport; built per-app (app-scoped server-side).
+    ...opts.data ? { data: opts.data } : {}
+    // identity / context: reserved seams, not provided yet.
+  };
+}
+export {
+  DEFAULT_AI_CAPABILITY,
+  StorageQuotaError,
+  asArrayOf,
+  asBoolean,
+  asFiniteNumber,
+  asString,
+  createMonolithSdk,
+  createScopedLocalStorage,
+  isRecord
+};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@mangtre/core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}