@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/templates/condition/types.ts

@@ -0,0 +1,69 @@
+import type { Result } from '../core/types';
+import type { EconomyState } from '../economy/types';
+
+export type ComparisonOperator = '>=' | '>' | '=' | '!=' | '<' | '<=';
+export type ConditionProgressFormat = 'fraction' | 'percent' | 'both' | 'none';
+export type ConditionMetric = 'level' | 'login-days' | 'login-streak' | 'resource' | string;
+
+export interface MetricCondition {
+  type: 'metric';
+  metric: ConditionMetric;
+  operator: ComparisonOperator;
+  target: number;
+  /** For example trackId for level, resourceId for resource, or remote-config parameters for custom metrics. */
+  params?: Record<string, string | number | boolean>;
+  label?: string;
+  description?: string;
+  progressFormat?: ConditionProgressFormat;
+}
+
+export type ConditionNode =
+  | MetricCondition
+  | { type: 'all'; conditions: ConditionNode[]; description?: string }
+  | { type: 'any'; conditions: ConditionNode[]; description?: string }
+  | { type: 'not'; condition: ConditionNode; description?: string };
+
+export interface ConditionDefinition {
+  id: string;
+  root: ConditionNode;
+  title?: string;
+}
+
+/** JSON-safe shape intended to be loaded from local or remote configuration. */
+export interface ConditionConfig {
+  definitions: Record<string, ConditionDefinition>;
+}
+
+export interface ConditionMetricProvider {
+  readonly metric: string;
+  getValue(condition: MetricCondition, state: EconomyState): number;
+}
+
+export interface ConditionProgress {
+  current?: number;
+  target?: number;
+  percent?: number;
+  label?: string;
+  format: ConditionProgressFormat;
+}
+
+export interface ConditionEvaluation {
+  met: boolean;
+  description: string;
+  progress: ConditionProgress;
+  children?: ConditionEvaluation[];
+}
+
+export interface ConditionViewModel extends ConditionEvaluation {
+  id: string;
+  title?: string;
+}
+
+export interface ConditionService {
+  replaceConfig(config: ConditionConfig): void;
+  getDefinition(id: string): ConditionDefinition | undefined;
+  evaluate(id: string): Promise<Result<ConditionEvaluation>>;
+  evaluateNode(node: ConditionNode): Promise<Result<ConditionEvaluation>>;
+  evaluateState(node: ConditionNode, state: EconomyState): ConditionEvaluation;
+  getViewModel(id: string): Promise<Result<ConditionViewModel>>;
+}

package/plugins/phaser-casual-game-factory/templates/core/events.ts

@@ -0,0 +1,71 @@
+import type { Unsubscribe } from './types';
+import type { RewardSummary } from '../economy/types';
+import type { TimeBoundaryPayload, TimeIntervalPayload } from './time';
+
+export interface GameEventMap {
+  'game:started': { sessionId: string };
+  'game:paused': { reason?: string };
+  'game:resumed': undefined;
+  'game:completed': { score: number; durationMs: number };
+  'economy:changed': {
+    currency: string;
+    balance: number;
+    delta: number;
+    reason: string;
+  };
+  'level:up': {
+    previousLevel: number;
+    currentLevel: number;
+    xp: number;
+  };
+  'level-track:changed': {
+    trackId: string;
+    level: number;
+    exp: number;
+    rewards: RewardSummary[];
+  };
+  'level-track:upgraded': {
+    trackId: string;
+    previousLevel: number;
+    currentLevel: number;
+    rewards: RewardSummary[];
+  };
+  'level-track:reset': {
+    trackId: string;
+    defaultLevel: number;
+    refunds: RewardSummary[];
+  };
+  'daily-login:claimed': {
+    dayIndex: number;
+    rewards: Array<{ type: string; amount: number }>;
+  };
+  'daily-login:registered': {
+    dayKey: string;
+    source: string;
+    currentStreak: number;
+    longestStreak: number;
+    registered: boolean;
+  };
+  'time:new-minute': TimeBoundaryPayload;
+  'time:new-hour': TimeBoundaryPayload;
+  'time:new-day': TimeBoundaryPayload;
+  'time:new-week': TimeBoundaryPayload;
+  'time:new-month': TimeBoundaryPayload;
+  'time:interval': TimeIntervalPayload;
+}
+
+export interface EventBus<Events extends object> {
+  emit<Key extends keyof Events>(event: Key, payload: Events[Key]): void;
+
+  on<Key extends keyof Events>(
+    event: Key,
+    listener: (payload: Events[Key]) => void,
+  ): Unsubscribe;
+
+  once<Key extends keyof Events>(
+    event: Key,
+    listener: (payload: Events[Key]) => void,
+  ): Unsubscribe;
+
+  clear(): void;
+}

package/plugins/phaser-casual-game-factory/templates/core/gameplay.ts

@@ -0,0 +1,15 @@
+export interface GameplayModule<TState> {
+  create(initialState?: Partial<TState>): TState;
+  start(state: TState): void;
+  update(state: TState, deltaMs: number): void;
+  pause(state: TState): void;
+  resume(state: TState): void;
+  isCompleted(state: TState): boolean;
+  getResult(state: TState): GameResult;
+}
+
+export interface GameResult {
+  success: boolean;
+  score: number;
+  rewards?: Array<{ type: string; amount: number }>;
+}

package/plugins/phaser-casual-game-factory/templates/core/index.ts

@@ -0,0 +1,9 @@
+export * from './types';
+export * from './events';
+export * from './storage';
+export * from './time';
+export * from './loading';
+export * from './layout';
+export * from './services';
+export * from './gameplay';
+export * from './service-registry';

package/plugins/phaser-casual-game-factory/templates/core/layout.ts

@@ -0,0 +1,25 @@
+export interface Viewport {
+  width: number;
+  height: number;
+  orientation: 'portrait' | 'landscape';
+}
+
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface LayoutRegions {
+  topBar: Rect;
+  playArea: Rect;
+  bottomActions: Rect;
+  modal: Rect;
+}
+
+export interface LayoutService {
+  getViewport(): Viewport;
+  getRegions(): LayoutRegions;
+  refresh(viewport: Viewport): LayoutRegions;
+}

package/plugins/phaser-casual-game-factory/templates/core/loading.ts

@@ -0,0 +1,33 @@
+/**
+ * Non-visual scheduling contract for background/adaptive work.
+ * Blocking scene transitions use `templates/loading-view/LoadingViewModel`.
+ */
+export interface LoadingTask {
+  id: string;
+  label?: string;
+  weight?: number;
+  run(): Promise<void>;
+}
+
+export interface LoadingProgress {
+  completed: number;
+  total: number;
+  ratio: number;
+  currentTask?: string;
+}
+
+export interface LoadingManager {
+  show(options?: {
+    message?: string;
+    minimumDurationMs?: number;
+  }): void;
+
+  run(
+    tasks: LoadingTask[],
+    onProgress?: (progress: LoadingProgress) => void,
+  ): Promise<void>;
+
+  hide(): Promise<void>;
+
+  showError(error: unknown, retry: () => Promise<void>): void;
+}

package/plugins/phaser-casual-game-factory/templates/core/service-registry.ts

@@ -0,0 +1,28 @@
+import type { EventBus, GameEventMap } from './events';
+import type { LayoutService } from './layout';
+import type { LoadingManager } from './loading';
+import type { EconomyService, ConditionService } from './services';
+import type { StorageService } from './storage';
+import type { ManagedTimeService } from './time';
+import type { GameConfig } from './types';
+import type { ItemService } from '../economy/item-service';
+import type { LevelingService } from '../leveling/types';
+import type { DailyLoginService } from '../daily-login/types';
+
+export interface GameServices {
+  events: EventBus<GameEventMap>;
+  storage: StorageService;
+  time: ManagedTimeService;
+  economy: EconomyService;
+  items: ItemService;
+  leveling: LevelingService;
+  dailyLogin: DailyLoginService;
+  conditions: ConditionService;
+  loading: LoadingManager;
+  layout: LayoutService;
+}
+
+export interface GameContext {
+  config: GameConfig;
+  services: GameServices;
+}

package/plugins/phaser-casual-game-factory/templates/core/services.ts

@@ -0,0 +1,19 @@
+import type { Result } from './types';
+import type {
+  EconomyOperationRequest,
+  TransactionReceipt,
+} from '../economy/types';
+import type { ConditionService } from '../condition/types';
+
+export type { EconomyOperationRequest, TransactionReceipt } from '../economy/types';
+
+export interface EconomyService {
+  getBalance(resourceId: string): Promise<number>;
+  execute(
+    request: EconomyOperationRequest,
+  ): Promise<Result<TransactionReceipt>>;
+}
+
+export type { LevelingService } from '../leveling/types';
+
+export type { ConditionService } from '../condition/types';

package/plugins/phaser-casual-game-factory/templates/core/storage.ts

@@ -0,0 +1,7 @@
+export interface StorageService {
+  has<T>(key: string): boolean;
+  get<T>(key: string): T | null;
+  set<T>(key: string, value: T): void;
+  remove(key: string): void;
+  clear(): void;
+}

package/plugins/phaser-casual-game-factory/templates/core/time.ts

@@ -0,0 +1,70 @@
+import type { Unsubscribe } from './types';
+
+export interface Clock {
+  now(): number;
+}
+
+export interface TimeSource extends Clock {
+  readonly kind: 'local' | 'server';
+}
+
+export interface ServerTimeResponse {
+  unixMs: number;
+}
+
+export type ServerTimeFetcher = () => Promise<ServerTimeResponse>;
+
+export interface TimeServiceConfig {
+  /** IANA timezone, for example `Asia/Ho_Chi_Minh`. Defaults to `UTC`. */
+  timeZone?: string;
+  /** JavaScript weekday: 0 Sunday through 6 Saturday. Defaults to Monday (1). */
+  weekStartsOn?: number;
+  /** Polling is optional; Phaser games can instead call tick() from their lifecycle. */
+  pollIntervalMs?: number;
+}
+
+export interface CalendarSnapshot {
+  timestamp: number;
+  minuteKey: string;
+  hourKey: string;
+  dayKey: string;
+  weekKey: string;
+  monthKey: string;
+}
+
+export interface TimeBoundaryPayload {
+  previous: CalendarSnapshot;
+  current: CalendarSnapshot;
+}
+
+export interface TimeIntervalPayload {
+  intervalMinutes: number;
+  previousBucket: number;
+  currentBucket: number;
+  timestamp: number;
+}
+
+export type TimeBoundaryEvent =
+  | 'new-minute'
+  | 'new-hour'
+  | 'new-day'
+  | 'new-week'
+  | 'new-month';
+
+export interface TimeService {
+  now(): number;
+  todayKey(): string;
+  diffMs(from: number, to: number): number;
+  diffDays(from: number, to: number): number;
+}
+
+/** The application-level clock contract. Scenes should only subscribe, never own this service. */
+export interface ManagedTimeService extends TimeService {
+  snapshot(timestamp?: number): CalendarSnapshot;
+  tick(): CalendarSnapshot;
+  on(event: TimeBoundaryEvent, listener: (payload: TimeBoundaryPayload) => void): Unsubscribe;
+  onEveryMinutes(intervalMinutes: number, listener: (payload: TimeIntervalPayload) => void): Unsubscribe;
+  startPolling(intervalMs?: number): void;
+  stopPolling(): void;
+  dispose(): void;
+}

package/plugins/phaser-casual-game-factory/templates/core/types.ts

@@ -0,0 +1,21 @@
+export type Unsubscribe = () => void;
+
+export type Result<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: Error };
+
+export interface Disposable {
+  dispose(): void;
+}
+
+export interface GameState {
+  phase: 'boot' | 'menu' | 'playing' | 'paused' | 'result';
+  sessionId: string;
+}
+
+export interface GameConfig {
+  debug?: boolean;
+  locale?: string;
+  designWidth: number;
+  designHeight: number;
+}

package/plugins/phaser-casual-game-factory/templates/daily-login/daily-login-service.ts

@@ -0,0 +1,136 @@
+import type { EventBus, GameEventMap } from '../core/events';
+import type { ManagedTimeService } from '../core/time';
+import type { Result, Unsubscribe } from '../core/types';
+import type { DailyLoginState, TransactionReceipt } from '../economy/types';
+import type { EconomyRepository } from '../economy/repository';
+import type {
+  AutoRegistrationOptions,
+  DailyLoginRegistration,
+  DailyLoginRegistrationRequest,
+  DailyLoginService,
+} from './types';
+
+const DAY_KEY = /^\d{4}-\d{2}-\d{2}$/;
+
+export class DefaultDailyLoginService implements DailyLoginService {
+  private stopNewDayListener?: Unsubscribe;
+
+  constructor(
+    private readonly repository: EconomyRepository,
+    private readonly time: ManagedTimeService,
+    private readonly events?: EventBus<GameEventMap>,
+  ) {}
+
+  async getState(): Promise<DailyLoginState> {
+    return (await this.repository.getSnapshot()).dailyLogin;
+  }
+
+  async hasLoggedIn(dayKey: string): Promise<boolean> {
+    assertDayKey(dayKey);
+    return Boolean((await this.getState()).days[dayKey]);
+  }
+
+  async getConsecutiveLoginDays(): Promise<number> {
+    return (await this.getState()).currentStreak;
+  }
+
+  async registerLogin(request: DailyLoginRegistrationRequest = {}): Promise<Result<DailyLoginRegistration>> {
+    const dayKey = request.dayKey ?? this.time.todayKey();
+    const source = request.source ?? 'game';
+    try {
+      assertDayKey(dayKey);
+      if (dayKey > this.time.todayKey()) throw new Error(`Cannot register a future login day: ${dayKey}`);
+      const transactionId = request.transactionId ?? `daily-login:${dayKey}`;
+      const execution = await this.repository.runAtomic(transactionId, async (state) => {
+        const wasRegistered = Boolean(state.dailyLogin.days[dayKey]);
+        if (!wasRegistered) {
+          state.dailyLogin.days[dayKey] = { registeredAt: this.time.now(), source };
+          state.dailyLogin = summarize(state.dailyLogin);
+        }
+        const receipt: TransactionReceipt = {
+          transactionId,
+          operationType: 'daily-login-register',
+          applied: true,
+          changes: [],
+          metadata: { dayKey, source, registered: String(!wasRegistered) },
+        };
+        return { state, receipt, value: { registered: !wasRegistered, state: state.dailyLogin } };
+      });
+      const state = execution.duplicate
+        ? await this.getState()
+        : execution.value!.state;
+      const registered = execution.duplicate ? false : execution.value!.registered;
+      const result: DailyLoginRegistration = { registered, dayKey, source, state, receipt: execution.receipt };
+      this.events?.emit('daily-login:registered', {
+        dayKey,
+        source,
+        currentStreak: state.currentStreak,
+        longestStreak: state.longestStreak,
+        registered,
+      });
+      return { ok: true, value: result };
+    } catch (error) {
+      return { ok: false, error: asError(error) };
+    }
+  }
+
+  async startAutoRegistration(options: AutoRegistrationOptions = {}): Promise<Result<DailyLoginRegistration>> {
+    this.stopAutoRegistration();
+    const source = options.source ?? 'game';
+    const transactionIdForDay = options.transactionIdForDay ?? ((dayKey) => `daily-login:${dayKey}`);
+    const initial = await this.registerLogin({
+      source,
+      transactionId: transactionIdForDay(this.time.todayKey()),
+    });
+    this.stopNewDayListener = this.time.on('new-day', ({ current }) => {
+      void this.registerLogin({ source, dayKey: current.dayKey, transactionId: transactionIdForDay(current.dayKey) })
+        .then((result) => { if (!result.ok) options.onError?.(result.error); })
+        .catch((error) => options.onError?.(asError(error)));
+    });
+    return initial;
+  }
+
+  stopAutoRegistration(): void {
+    this.stopNewDayListener?.();
+    this.stopNewDayListener = undefined;
+  }
+
+  dispose(): void { this.stopAutoRegistration(); }
+}
+
+function summarize(input: DailyLoginState): DailyLoginState {
+  const days = Object.keys(input.days).sort();
+  const lastLoginDay = days.at(-1);
+  let currentStreak = 0;
+  if (lastLoginDay) {
+    let cursor = lastLoginDay;
+    while (input.days[cursor]) {
+      currentStreak += 1;
+      cursor = previousDay(cursor);
+    }
+  }
+  let longestStreak = 0;
+  let running = 0;
+  let previous: string | undefined;
+  for (const day of days) {
+    running = previous && previousDay(day) === previous ? running + 1 : 1;
+    longestStreak = Math.max(longestStreak, running);
+    previous = day;
+  }
+  return { ...input, lastLoginDay, currentStreak, longestStreak };
+}
+
+function previousDay(dayKey: string): string {
+  const [year, month, day] = dayKey.split('-').map(Number);
+  return new Date(Date.UTC(year, month - 1, day - 1)).toISOString().slice(0, 10);
+}
+
+function assertDayKey(dayKey: string): void {
+  if (!DAY_KEY.test(dayKey) || new Date(`${dayKey}T00:00:00.000Z`).toISOString().slice(0, 10) !== dayKey) {
+    throw new Error(`Invalid day key: ${dayKey}`);
+  }
+}
+
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}

package/plugins/phaser-casual-game-factory/templates/daily-login/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './daily-login-service';
+export * from './reward-service';

package/plugins/phaser-casual-game-factory/templates/daily-login/reward-service.ts

@@ -0,0 +1,108 @@
+import type { ConditionNode } from '../condition/types';
+import { DefaultConditionService } from '../condition/condition-service';
+import type { ManagedTimeService } from '../core/time';
+import type { Result } from '../core/types';
+import type { EconomyConfig, ResourceStack, RewardSummary, TransactionReceipt } from '../economy/types';
+import type { EconomyRepository } from '../economy/repository';
+import { applyInput, applyRewards, resourceRewardsFromChanges } from '../economy/state-utils';
+
+export interface DailyRewardEntry { day: number; rewards: ResourceStack[]; requirements?: ConditionNode[]; }
+export interface DailyRewardProgram {
+  id: string;
+  /** Normal program, or only available while its package entitlement is active. */
+  packageId?: string;
+  track: 'login-days' | 'streak';
+  entries: DailyRewardEntry[];
+  repeat?: 'none' | 'cycle';
+  allowCatchUp?: boolean;
+  catchUpCost?: ResourceStack[];
+  /** Typical for VIP programs: claim every previously logged but unclaimed day in one transaction. */
+  allowClaimAllUnclaimed?: boolean;
+  /** Defaults false: VIP backfill commonly grants old logged days without charging catch-up cost. */
+  claimAllPaysCatchUpCost?: boolean;
+}
+export interface DailyLoginRewardsConfig { programs: Record<string, DailyRewardProgram>; }
+export interface DailyRewardClaim { programId: string; dayKey: string; rewardDay: number; rewards: RewardSummary[]; receipt: TransactionReceipt; }
+
+/** Claims are atomic with resource cost and rewards. Ads/IAP belong to Commerce, not this service. */
+export class DefaultDailyLoginRewardService {
+  private readonly conditions: DefaultConditionService;
+  constructor(
+    private readonly repository: EconomyRepository,
+    private readonly economyConfig: EconomyConfig,
+    private readonly time: ManagedTimeService,
+    private readonly config: DailyLoginRewardsConfig,
+  ) { this.conditions = new DefaultConditionService(repository); }
+
+  async canClaim(programId: string, dayKey = this.time.todayKey()): Promise<Result<{ canClaim: boolean; reason?: string; rewardDay?: number }>> {
+    try {
+      const state = await this.repository.getSnapshot();
+      const program = this.program(programId);
+      const check = this.check(program, dayKey, state.dailyLogin, state, dayKey !== this.time.todayKey());
+      return { ok: true, value: check.can ? { canClaim: true, rewardDay: check.rewardDay } : { canClaim: false, reason: check.reason } };
+    } catch (error) { return { ok: false, error: asError(error) }; }
+  }
+
+  async claim(programId: string, transactionId: string, dayKey = this.time.todayKey()): Promise<Result<DailyRewardClaim>> {
+    try {
+      const program = this.program(programId);
+      const result = await this.repository.runAtomic(transactionId, async (state) => {
+        const check = this.check(program, dayKey, state.dailyLogin, state, dayKey !== this.time.todayKey());
+        if (!check.can || check.rewardDay === undefined) throw new Error(check.reason ?? 'Cannot claim daily reward');
+        const entry = entryFor(program, check.rewardDay);
+        const changes: TransactionReceipt['changes'] = [];
+        if (dayKey !== this.time.todayKey() && program.catchUpCost?.length) applyInput(state, this.economyConfig, program.catchUpCost, 'spendable', changes);
+        applyRewards(state, this.economyConfig, entry.rewards, changes);
+        (state.dailyLogin.claims[program.id] ??= {})[dayKey] = true;
+        const rewards = resourceRewardsFromChanges(changes);
+        const receipt: TransactionReceipt = { transactionId, operationType: 'daily-login-claim', applied: true, changes, rewards, metadata: { programId, dayKey, rewardDay: String(check.rewardDay) } };
+        return { state, receipt, value: { rewardDay: check.rewardDay, rewards } };
+      });
+      const rewardDay = result.receipt.metadata?.rewardDay ? Number(result.receipt.metadata.rewardDay) : 0;
+      return { ok: true, value: { programId, dayKey, rewardDay, rewards: result.receipt.rewards ?? [], receipt: result.receipt } };
+    } catch (error) { return { ok: false, error: asError(error) }; }
+  }
+
+  async claimAllUnclaimed(programId: string, transactionId: string): Promise<Result<{ claims: DailyRewardClaim[]; receipt: TransactionReceipt }>> {
+    try {
+      const program = this.program(programId);
+      if (!program.allowClaimAllUnclaimed) throw new Error(`Claim-all is disabled: ${programId}`);
+      const result = await this.repository.runAtomic(transactionId, async (state) => {
+        const changes: TransactionReceipt['changes'] = [];
+        const claims: Array<{ dayKey: string; rewardDay: number }> = [];
+        for (const dayKey of Object.keys(state.dailyLogin.days).sort()) {
+          if (state.dailyLogin.claims?.[program.id]?.[dayKey]) continue;
+          const check = this.check(program, dayKey, state.dailyLogin, state, dayKey !== this.time.todayKey());
+          if (!check.can || check.rewardDay === undefined) continue;
+          if (program.claimAllPaysCatchUpCost && dayKey !== this.time.todayKey() && program.catchUpCost?.length) applyInput(state, this.economyConfig, program.catchUpCost, 'spendable', changes);
+          applyRewards(state, this.economyConfig, entryFor(program, check.rewardDay)!.rewards, changes);
+          (state.dailyLogin.claims[program.id] ??= {})[dayKey] = true;
+          claims.push({ dayKey, rewardDay: check.rewardDay });
+        }
+        const receipt: TransactionReceipt = { transactionId, operationType: 'daily-login-claim', applied: true, changes, rewards: resourceRewardsFromChanges(changes), metadata: { programId, claimCount: String(claims.length), batch: 'true' } };
+        return { state, receipt, value: claims };
+      });
+      return { ok: true, value: { claims: (result.value ?? []).map((claim) => ({ programId, ...claim, rewards: [], receipt: result.receipt })), receipt: result.receipt } };
+    } catch (error) { return { ok: false, error: asError(error) }; }
+  }
+
+  private check(program: DailyRewardProgram, dayKey: string, login: { days: Record<string, unknown>; claims: Record<string, Record<string, true>> }, state: any, isCatchUp: boolean): { can: boolean; reason?: string; rewardDay?: number } {
+    if (!login.days[dayKey]) return { can: false, reason: 'Login day is not registered' };
+    if (login.claims?.[program.id]?.[dayKey]) return { can: false, reason: 'Reward already claimed' };
+    if (isCatchUp && !program.allowCatchUp) return { can: false, reason: 'Catch-up claim is disabled' };
+    const packageState = program.packageId ? state.activePackages[program.packageId] : undefined;
+    if (program.packageId && (!packageState || (!packageState.permanent && packageState.expiresAt !== undefined && packageState.expiresAt <= this.time.now()))) return { can: false, reason: `Package is not active: ${program.packageId}` };
+    const rewardDay = program.track === 'login-days' ? Object.keys(login.days).sort().indexOf(dayKey) + 1 : streakAt(dayKey, login.days);
+    const entry = entryFor(program, rewardDay);
+    if (!entry) return { can: false, reason: 'No reward configured for this login day' };
+    for (const requirement of entry.requirements ?? []) {
+      const evaluated = this.conditions.evaluateState(requirement, state);
+      if (!evaluated.met) return { can: false, reason: evaluated.description };
+    }
+    return { can: true, rewardDay };
+  }
+  private program(id: string): DailyRewardProgram { const program = this.config.programs[id]; if (!program) throw new Error(`Unknown daily reward program: ${id}`); return program; }
+}
+function entryFor(program: DailyRewardProgram, day: number): DailyRewardEntry | undefined { const max = Math.max(...program.entries.map((entry) => entry.day)); const target = program.repeat === 'cycle' && max ? ((day - 1) % max) + 1 : day; return program.entries.find((entry) => entry.day === target); }
+function streakAt(dayKey: string, days: Record<string, unknown>): number { let count = 0; let cursor = dayKey; while (days[cursor]) { count++; const [y,m,d] = cursor.split('-').map(Number); cursor = new Date(Date.UTC(y,m-1,d-1)).toISOString().slice(0,10); } return count; }
+function asError(error: unknown): Error { return error instanceof Error ? error : new Error(String(error)); }

package/plugins/phaser-casual-game-factory/templates/daily-login/types.ts

@@ -0,0 +1,39 @@
+import type { DailyLoginState, TransactionReceipt } from '../economy/types';
+import type { Result, Unsubscribe } from '../core/types';
+
+export type LoginSource = 'game' | 'portal' | 'third-party' | string;
+
+export interface DailyLoginRegistrationRequest {
+  /** Defaults to the current day from TimeService. A portal may provide its verified day key. */
+  dayKey?: string;
+  source?: LoginSource;
+  /** Must be stable for a retry of the same external login callback. */
+  transactionId?: string;
+}
+
+export interface DailyLoginRegistration {
+  registered: boolean;
+  dayKey: string;
+  source: LoginSource;
+  state: DailyLoginState;
+  receipt: TransactionReceipt;
+}
+
+export interface AutoRegistrationOptions {
+  source?: LoginSource;
+  transactionIdForDay?: (dayKey: string) => string;
+  onError?: (error: Error) => void;
+}
+
+export interface DailyLoginService {
+  getState(): Promise<DailyLoginState>;
+  hasLoggedIn(dayKey: string): Promise<boolean>;
+  getConsecutiveLoginDays(): Promise<number>;
+  registerLogin(request?: DailyLoginRegistrationRequest): Promise<Result<DailyLoginRegistration>>;
+  /** Registers the current day immediately, then registers automatically after each new-day event. */
+  startAutoRegistration(options?: AutoRegistrationOptions): Promise<Result<DailyLoginRegistration>>;
+  stopAutoRegistration(): void;
+  dispose(): void;
+}
+
+export type DailyLoginUnsubscribe = Unsubscribe;