@proto.ui/module-base 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Proto UI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @proto.ui/module-base
+
+Base package for building Proto UI modules.
+
+## Purpose
+
+Provides the base template, shared capabilities, and development utilities for building Proto UI modules.
+
+## Package Role
+
+Module foundation package used to implement adapter-facing modules in a consistent way.
+
+## Install
+
+```bash
+npm install @proto.ui/module-base@0.0.1
+```
+
+## Internal Structure
+
+- `src/caps-vault/`
+- `src/create-module.ts`
+- `src/index.ts`
+- `src/module-base.ts`
+- `src/system-caps.ts`
+
+## Related Internal Packages
+
+- `@proto.ui/core`
+
+## License
+
+MIT

package/dist/caps-vault/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './vault';

package/dist/caps-vault/index.js

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './vault';

package/dist/caps-vault/types.d.ts

@@ -0,0 +1 @@
+export type Unsubscribe = () => void;

package/dist/caps-vault/types.js

@@ -0,0 +1 @@
+export {};

package/dist/caps-vault/vault.d.ts

@@ -0,0 +1,43 @@
+import type { CapEntries, CapToken, CapsVaultView } from '@proto.ui/core';
+import { Unsubscribe } from './types';
+/**
+ * Mutable caps vault for runtime/host wiring.
+ *
+ * Two layers:
+ * - base: runtime-owned built-ins (SYS_CAP etc.), never reset by host wiring
+ * - attached: host/wiring provided caps, resettable
+ *
+ * NOTE:
+ * - module-* should depend on the *view* interface only (CapsVaultView from core),
+ *   but in practice it's fine if they accept this class as long as they
+ *   don't call attach/reset* (keep it a convention).
+ */
+export declare class CapsVault implements CapsVaultView {
+    private base;
+    private attached;
+    private listeners;
+    epoch: number;
+    has(token: CapToken<any>): boolean;
+    get<T>(token: CapToken<T>): T;
+    onChange(cb: (epoch: number) => void): Unsubscribe;
+    /**
+     * runtime-only: inject built-in/system caps (SYS_CAP etc.)
+     * This layer survives host reset/unmount resets.
+     */
+    attachBase(entries: CapEntries): void;
+    /**
+     * wiring-only: host/runtime inject capabilities for this instance.
+     * This layer can be cleared by resetAttached().
+     */
+    attach(entries: CapEntries): void;
+    /**
+     * wiring-only: invalidate ONLY the attached layer.
+     * SYS_CAP (base) remains available.
+     */
+    resetAttached(): void;
+    /**
+     * runtime-only: invalidate everything (rare; prefer resetAttached()).
+     */
+    resetAll(): void;
+    private bump;
+}

package/dist/caps-vault/vault.js

@@ -0,0 +1,101 @@
+import { capUnavailable } from '@proto.ui/core';
+/**
+ * Mutable caps vault for runtime/host wiring.
+ *
+ * Two layers:
+ * - base: runtime-owned built-ins (SYS_CAP etc.), never reset by host wiring
+ * - attached: host/wiring provided caps, resettable
+ *
+ * NOTE:
+ * - module-* should depend on the *view* interface only (CapsVaultView from core),
+ *   but in practice it's fine if they accept this class as long as they
+ *   don't call attach/reset* (keep it a convention).
+ */
+export class CapsVault {
+    base = new Map();
+    attached = new Map();
+    listeners = new Set();
+    epoch = 0;
+    has(token) {
+        const id = token.id;
+        return this.attached.has(id) || this.base.has(id);
+    }
+    get(token) {
+        const id = token.id;
+        if (this.attached.has(id))
+            return this.attached.get(id);
+        if (this.base.has(id))
+            return this.base.get(id);
+        throw capUnavailable(id, { epoch: this.epoch });
+    }
+    onChange(cb) {
+        this.listeners.add(cb);
+        return () => this.listeners.delete(cb);
+    }
+    // -------------------------
+    // wiring APIs (mutable)
+    // -------------------------
+    /**
+     * runtime-only: inject built-in/system caps (SYS_CAP etc.)
+     * This layer survives host reset/unmount resets.
+     */
+    attachBase(entries) {
+        if (!entries || entries.length === 0)
+            return;
+        let changed = false;
+        for (const [token, value] of entries) {
+            const id = token.id;
+            const prev = this.base.get(id);
+            if (!this.base.has(id) || prev !== value) {
+                this.base.set(id, value);
+                changed = true;
+            }
+        }
+        if (changed)
+            this.bump();
+    }
+    /**
+     * wiring-only: host/runtime inject capabilities for this instance.
+     * This layer can be cleared by resetAttached().
+     */
+    attach(entries) {
+        if (!entries || entries.length === 0)
+            return;
+        let changed = false;
+        for (const [token, value] of entries) {
+            const id = token.id;
+            const prev = this.attached.get(id);
+            if (!this.attached.has(id) || prev !== value) {
+                this.attached.set(id, value);
+                changed = true;
+            }
+        }
+        if (changed)
+            this.bump();
+    }
+    /**
+     * wiring-only: invalidate ONLY the attached layer.
+     * SYS_CAP (base) remains available.
+     */
+    resetAttached() {
+        if (this.attached.size === 0)
+            return;
+        this.attached.clear();
+        this.bump();
+    }
+    /**
+     * runtime-only: invalidate everything (rare; prefer resetAttached()).
+     */
+    resetAll() {
+        if (this.attached.size === 0 && this.base.size === 0)
+            return;
+        this.attached.clear();
+        this.base.clear();
+        this.bump();
+    }
+    bump() {
+        this.epoch++;
+        for (const cb of this.listeners)
+            cb(this.epoch);
+    }
+}

package/dist/create-module.d.ts

@@ -0,0 +1,72 @@
+import type { ModuleFacade, ModuleHooks, ModuleInstance, ModuleInit, ModuleScope, CapsVaultView } from '@proto.ui/core';
+export type ModuleDeps = {
+    /**
+     * Require a declared dependency's facade.
+     * Throws if the dependency is undeclared or missing.
+     */
+    requireFacade<T extends ModuleFacade>(name: string): T;
+    /**
+     * Require a declared dependency's port.
+     * Throws if the dependency is undeclared or missing.
+     */
+    requirePort<T>(name: string): T;
+    /**
+     * Try a declared dependency's facade.
+     * Returns undefined if missing, but still throws if undeclared.
+     */
+    tryFacade<T extends ModuleFacade>(name: string): T | undefined;
+    /**
+     * Try a declared dependency's port.
+     * Returns undefined if missing, but still throws if undeclared.
+     */
+    tryPort<T>(name: string): T | undefined;
+};
+export type ModuleFactoryArgs = {
+    init: ModuleInit;
+    caps: CapsVaultView;
+    deps: ModuleDeps;
+};
+/**
+ * Module definition for the orchestrator.
+ * Use this for explicit deps declaration and consistent module metadata.
+ */
+export type ModuleDef<Name extends string = string> = {
+    name: Name;
+    /**
+     * Hard dependencies: must exist and be initialized first.
+     */
+    deps?: string[];
+    /**
+     * Optional dependencies: used if present, ignored if missing.
+     */
+    optionalDeps?: string[];
+    /**
+     * Module factory. Prefer small, deterministic construction.
+     */
+    create: (ctx: ModuleFactoryArgs) => ModuleInstance<ModuleFacade> & {
+        name: Name;
+        scope: ModuleScope;
+        port?: unknown;
+    };
+};
+/**
+ * Define a module with explicit deps.
+ * This is the preferred entrypoint for module registration.
+ */
+export declare function defineModule<Name extends string>(def: ModuleDef<Name>): ModuleDef<Name>;
+export declare function createModule<Name extends string, Scope extends ModuleScope, Facade extends ModuleFacade, Port = undefined>(args: {
+    name: Name;
+    scope: Scope;
+    init: ModuleInit;
+    caps: CapsVaultView;
+    deps: ModuleDeps;
+    build: (ctx: ModuleFactoryArgs) => {
+        facade: Facade;
+        hooks?: ModuleHooks;
+        port?: Port;
+    };
+}): ModuleInstance<Facade> & {
+    name: Name;
+    scope: Scope;
+    port?: Port;
+};

package/dist/create-module.js

@@ -0,0 +1,21 @@
+/**
+ * Define a module with explicit deps.
+ * This is the preferred entrypoint for module registration.
+ */
+export function defineModule(def) {
+    return def;
+}
+export function createModule(args) {
+    const { facade, hooks, port } = args.build({
+        init: args.init,
+        caps: args.caps,
+        deps: args.deps,
+    });
+    return {
+        name: args.name,
+        scope: args.scope,
+        facade,
+        hooks: hooks ?? {},
+        port,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './caps-vault';
+export * from './module-base';
+export * from './create-module';
+export * from './system-caps';

package/dist/index.js

@@ -0,0 +1,5 @@
+// packages/modules/base/src/index.ts
+export * from './caps-vault';
+export * from './module-base';
+export * from './create-module';
+export * from './system-caps';

package/dist/module-base.d.ts

@@ -0,0 +1,13 @@
+import type { ProtoPhase } from '@proto.ui/core';
+import type { CapsVaultView } from '@proto.ui/core';
+export declare abstract class ModuleBase {
+    protected protoPhase: ProtoPhase;
+    protected readonly caps: CapsVaultView;
+    private pending;
+    constructor(caps: CapsVaultView);
+    protected get sys(): import("./system-caps").SystemCaps;
+    onProtoPhase(phase: ProtoPhase): void;
+    protected onCapsEpoch(_epoch: number): void;
+    protected defer(fn: () => void): void;
+    protected flushPending(): void;
+}

package/dist/module-base.js

@@ -0,0 +1,31 @@
+import { SYS_CAP } from './system-caps';
+export class ModuleBase {
+    protoPhase = 'setup';
+    caps;
+    pending = [];
+    constructor(caps) {
+        this.caps = caps;
+        this.caps.onChange((epoch) => {
+            this.onCapsEpoch(epoch);
+            this.flushPending();
+        });
+    }
+    get sys() {
+        return this.caps.get(SYS_CAP);
+    }
+    onProtoPhase(phase) {
+        this.protoPhase = phase;
+    }
+    onCapsEpoch(_epoch) { }
+    defer(fn) {
+        this.pending.push(fn);
+    }
+    flushPending() {
+        if (this.pending.length === 0)
+            return;
+        const tasks = this.pending;
+        this.pending = [];
+        for (const t of tasks)
+            t();
+    }
+}

package/dist/system-caps.d.ts

@@ -0,0 +1,32 @@
+import { type ProtoPhase } from '@proto.ui/core';
+export type ExecPhase = 'setup' | 'render' | 'callback' | 'unknown';
+export type GuardDomain = 'setup' | 'runtime';
+export interface SystemCaps {
+    /** exec-phase (more precise than domain) */
+    execPhase(): ExecPhase;
+    /** derived: setup vs runtime (kept for compatibility) */
+    domain(): GuardDomain;
+    /** proto lifecycle phase */
+    protoPhase(): ProtoPhase;
+    /** disposal state */
+    isDisposed(): boolean;
+    ensureNotDisposed(op: string): void;
+    ensureExecPhase(op: string, expected: ExecPhase | ExecPhase[]): void;
+    /** convenience */
+    ensureSetup(op: string): void;
+    ensureRuntime(op: string): void;
+    /**
+     * callback-only: recommended for "runtime mutation" APIs (state.set etc.)
+     * This prevents render-phase mutations.
+     */
+    ensureCallback(op: string): void;
+    /**
+     * Runtime callback context (opaque).
+     *
+     * - In engine-driven execution, this will typically be `run`.
+     * - Outside callback phase, it should return `undefined`.
+     * - State/event modules MUST treat it as unknown and not depend on its shape.
+     */
+    getCallbackCtx(): unknown;
+}
+export declare const SYS_CAP: import("@proto.ui/core").CapToken<SystemCaps>;

package/dist/system-caps.js

@@ -0,0 +1,2 @@
+import { cap } from '@proto.ui/core';
+export const SYS_CAP = cap('@proto.ui/__sys');

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@proto.ui/module-base",
+  "version": "0.0.1",
+  "type": "module",
+  "dependencies": {
+    "@proto.ui/core": "0.0.1"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "description": "Base package for building Proto UI modules.",
+  "license": "MIT",
+  "homepage": "https://github.com/guangliang2019/Prototype-UI/tree/main/packages/modules/base",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/guangliang2019/Prototype-UI.git",
+    "directory": "packages/modules/base"
+  },
+  "bugs": {
+    "url": "https://github.com/guangliang2019/Prototype-UI/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "proto-ui",
+    "proto",
+    "ui",
+    "module",
+    "base"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}