ice-web-components 1.2.0 → 1.4.0

package/dist/types/components/ICELabel.d.ts

@@ -8,6 +8,14 @@ export declare class ICELabel extends ICEWidget {
     constructor(props?: any);
     setText(text: string): this;
     getText(): string;
+    /**
+     * 改文字颜色（动态强调 / 置灰用，比如 BIOS 自检行的灰→黄→绿、菜单选中态）。
+     *
+     * 必须走内层 `ICEText`：文字是它画的，构造期 `style` 已经下沉到那一层，
+     * 之后再 `setState({ style })` 只会改到外壳容器，屏幕上的字纹丝不动。
+     * 只覆盖 `fillStyle`，字号 / 字体 / 对齐这些原样保留。
+     */
+    setTextColor(color: string): this;
     /**
      * 让标签自身占据文字的实测尺寸。
      *

package/dist/types/index.d.ts

@@ -112,3 +112,8 @@ export * from './model/ICEChip8Model';
 export * from './model/ICE2048Model';
 export * from './model/ICEHistoryModel';
 export * from './model/ICEPixelModel';
+export * from './model/ICEBiosModel';
+export * from './model/ICETracePlayerModel';
+export * from './model/ICESortModel';
+export * from './model/ICEMazeModel';
+export * from './model/ICEDosModel';

package/dist/types/model/ICEBiosModel.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 掌机 BIOS 的纯逻辑（不碰 canvas、不碰 DOM）。
+ *
+ * 掌机开机先跑一段「自检 → 菜单」的引导，然后才把控制权交给卡带：
+ * 自检**按时序推进**（页面每帧调 `tick(dt)`），菜单是**光标 + 确认**的老式控制台交互。
+ * 页面只负责把 `getSteps()` / `getMenuEntries()` 画成文字，并执行 `confirm()` 返回的动作 ——
+ * 状态机与渲染分开，所以「自检要跑多久、菜单怎么绕、设置存到哪」都能在 node 里单测。
+ *
+ * 约定：
+ * - 自检项由 `steps` 注入（默认 5 项：CPU / RAM / VRAM / SOUND / CART），每项有自己的耗时；
+ * - 相位机：`post`（自检中）→ `menu`（启动菜单）或 `boot`（直接启动，快速启动开着时）；
+ *   `settings`（设置页）从菜单进、`back()` 回菜单；
+ * - 菜单光标上下**循环**（到头绕回去，老式 BIOS 都这样），进设置前记下位置、回来还停在那儿；
+ * - 设置（快速启动 / 默认卡带）落到注入的存储里；坏数据、写盘失败一律降级，绝不抛。
+ */
+export declare type ICEBiosPhase = 'post' | 'menu' | 'settings' | 'boot';
+export interface ICEBiosStep {
+    /** 稳定 key（页面拿它做节点 id / 维护增量更新） */
+    key: string;
+    label: string;
+    detail: string;
+    /** 这一项「检测」要花多久（毫秒） */
+    duration: number;
+}
+export interface ICEBiosStepState extends ICEBiosStep {
+    state: 'pending' | 'running' | 'ok';
+    /** 当前项的进度 0..1；非当前项是 0 或 1 */
+    progress: number;
+}
+export interface ICEBiosCartridge {
+    key: string;
+    label: string;
+}
+export interface ICEBiosMenuEntry {
+    key: string;
+    label: string;
+    type: 'cartridge' | 'settings' | 'boot';
+}
+export interface ICEBiosSettings {
+    /** 开着就跳过菜单直接启动默认卡带（开机自检还是要跑） */
+    quickBoot: boolean;
+    defaultCartridge: string;
+}
+export declare type ICEBiosAction = {
+    type: 'boot';
+    cartridge: string;
+} | {
+    type: 'settings';
+} | {
+    type: 'menu';
+} | {
+    type: 'none';
+};
+export interface ICEBiosStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+export interface ICEBiosOptions {
+    cartridges: ICEBiosCartridge[];
+    /** 自检项，默认 `ICE_BIOS_DEFAULT_STEPS` */
+    steps?: ICEBiosStep[];
+    /** 初始设置（优先级低于存储里的值） */
+    settings?: Partial<ICEBiosSettings>;
+    /** 存储实现；传 null 表示只放内存；不传则用 globalThis.localStorage（没有就退化成内存） */
+    storage?: ICEBiosStorage | null;
+    /** 存储键前缀，默认 `ice-arcade-bios-` */
+    prefix?: string;
+}
+export declare type ICEBiosListener = (model: ICEBiosModel) => void;
+/** 默认自检项：每一项都是一句「老式 BIOS 会印在屏幕上的话」。 */
+export declare const ICE_BIOS_DEFAULT_STEPS: ICEBiosStep[];
+export declare class ICEBiosModel {
+    private steps;
+    private cartridges;
+    private storage;
+    private storageKey;
+    private listeners;
+    private phase;
+    private elapsed;
+    private cursor;
+    private cursorBeforeSettings;
+    private settings;
+    constructor(options: ICEBiosOptions);
+    getPhase(): ICEBiosPhase;
+    getCartridges(): ICEBiosCartridge[];
+    getPostElapsed(): number;
+    /** 自检总时长（毫秒）。 */
+    getPostDuration(): number;
+    /** 自检进度 0..1（按时间算，页面拿它画进度条）。 */
+    getPostProgress(): number;
+    /** 自检项与它们此刻的状态（当前项 running、前面的 ok）。 */
+    getSteps(): ICEBiosStepState[];
+    /** 菜单项：卡带列表 + 设置 + 退出并启动。 */
+    getMenuEntries(): ICEBiosMenuEntry[];
+    getCursor(): number;
+    getSelectedEntry(): ICEBiosMenuEntry | null;
+    getSettings(): ICEBiosSettings;
+    isQuickBoot(): boolean;
+    getDefaultCartridge(): string;
+    /** 推进自检（页面每帧调用），返回是否发生了变化。 */
+    tick(delta: number): boolean;
+    moveCursor(delta: number): void;
+    setCursor(index: number): void;
+    /** 确认当前项：只返回动作，执行动作是页面的事（好测）。 */
+    confirm(): ICEBiosAction;
+    /** 返回上一层（设置 → 菜单）。 */
+    back(): void;
+    /** 从游戏里回到 BIOS 菜单（掌机的「复位」）。 */
+    openMenu(): void;
+    /** 重新跑一遍自检（再开一次机）。 */
+    restart(): void;
+    toggleQuickBoot(): boolean;
+    setDefaultCartridge(key: string): void;
+    addChangeListener(listener: ICEBiosListener): () => void;
+    private __alignCursorToDefault;
+    /** 卡带 key 必须真的存在，否则回退到第一个卡带。 */
+    private __normalizeCartridge;
+    private __load;
+    private __readStorage;
+    private __save;
+    private __defaultStorage;
+    private notify;
+}
+export default ICEBiosModel;

package/dist/types/model/ICEDosModel.d.ts

@@ -0,0 +1,84 @@
+/**
+ * DOS 终端（虚拟文件系统 + 命令解释器，纯逻辑，不碰 DOM）。
+ *
+ * 页面只做三件事：把 `run()` 返回的行画成文字、把键盘输入交给模型、按 `effect` 做副作用
+ * （`cls` 清屏 / `exit` 退出）。所以「命令怎么解析、路径怎么算、文件怎么改」全都能在 node 里断言。
+ *
+ * 约定：
+ * - 路径分隔符 `\` 与 `/` 等价；支持绝对（`\GAMES`）、相对（`GAMES`）、`.`、`..`；
+ * - 命令大小写不敏感（`DIR` = `dir`），参数里的文件名也大小写不敏感；
+ * - `run()` 从不抛：任何坏输入都变成一行 `error`，终端不会因为打错字崩掉；
+ * - `echo x > a.txt` / `echo x >> a.txt` 也是模型的一部分（重定向在解析层处理掉）；
+ * - 历史和 Tab 补全归模型管（真终端也有这两个），页面只管按键。
+ */
+export declare type ICEDosLineType = 'output' | 'error';
+export interface ICEDosLine {
+    text: string;
+    type: ICEDosLineType;
+}
+export interface ICEDosEffect {
+    clear?: boolean;
+    exit?: boolean;
+}
+export interface ICEDosResult {
+    lines: ICEDosLine[];
+    effect?: ICEDosEffect;
+}
+export interface ICEDosOptions {
+    /** 时间源（`date` / `time` 用），测试可注入固定时间 */
+    now?: () => Date;
+}
+export declare class ICEDosModel {
+    private root;
+    private cwd;
+    private history;
+    private historyIndex;
+    private now;
+    constructor(options?: ICEDosOptions);
+    getCwd(): string;
+    getPrompt(): string;
+    getBanner(): string[];
+    getHistory(): string[];
+    /** 执行一行命令。永不抛：坏输入变成一行 error。 */
+    run(input: string): ICEDosResult;
+    historyPrev(): string;
+    historyNext(): string;
+    /**
+     * Tab 补全：命令名补到唯一前缀（带空格），路径按当前目录补（目录名不带空格，方便继续往下打）。
+     * 没有匹配 / 多个匹配时原样返回（真 DOS 会再按一次列出候选，这里从简）。
+     */
+    complete(input: string): string;
+    private __dir;
+    private __cd;
+    private __mkdir;
+    private __rmdir;
+    private __type;
+    private __echo;
+    private __copy;
+    private __rename;
+    private __del;
+    private __tree;
+    private __current;
+    private __resolve;
+    private __resolveParent;
+    private __parentOf;
+    /** 目标节点在树里的路径（从根目录起算，不含 C:）。 */
+    private __pathOf;
+    /** 相对路径 → 分段（处理 `.` / `..` / 绝对路径）。 */
+    private __segments;
+    private __baseName;
+    private __removeChild;
+    private __completePath;
+    private __sortedChildren;
+    private __fileSize;
+    private __fileRow;
+    private __nodeDate;
+    private __volumeLabel;
+    private __formatDate;
+    private __formatTime;
+    private __lines;
+    private __error;
+    /** 出厂文件系统：一个像样的小 DOS 盘（命令都能玩起来）。 */
+    private __createSeed;
+}
+export default ICEDosModel;

package/dist/types/model/ICEMazeModel.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 迷宫寻路轨迹（纯逻辑，不碰 canvas）。
+ *
+ * 和排序那边同一套路：**先算完整段过程录成一串帧**，回放交给 `ICETracePlayerModel`，
+ * 画面由页面用一张 ICETileMap 画（每格一个状态）。
+ *
+ * 网格是「行优先的一维数组」，每格一个状态（空 / 墙 / 起点 / 终点 / 已访问 / 边界 / 路径）。
+ * 四种算法在无权网格上每步代价都是 1，区别只在**怎么挑下一个格子**：
+ * - BFS：队列 → 层序扩展，首次到达即最短；
+ * - DFS：栈 → 一条道走到黑，找得到但不保证最短；
+ * - Dijkstra：按代价取最小（无权网格里等价于 BFS，保留它是为了「代价」这条语义）；
+ * - A*：代价 + 曼哈顿距离启发 → 同样最短，但访问的格子更少。
+ */
+export declare const ICE_MAZE_CELL: {
+    readonly EMPTY: 0;
+    readonly WALL: 1;
+    readonly START: 2;
+    readonly GOAL: 3;
+    readonly VISITED: 4;
+    readonly FRONTIER: 5;
+    readonly PATH: 6;
+};
+export interface ICEMazeAlgorithm {
+    key: string;
+    label: string;
+    note: string;
+}
+export interface ICEMazeFrame {
+    /** 本帧的网格快照（可视化直接照着画） */
+    cells: number[];
+    /** 当前正在处理的格子（-1 表示没有） */
+    current: number;
+    /** 待探索的边界 */
+    frontier: number[];
+    /** 已经处理过的格子 */
+    visited: number[];
+    /** 找到路径之后才有（按起点 → 终点排序） */
+    path: number[];
+    reached: boolean;
+    note: string;
+    /** 访问过多少格（代价指标） */
+    visitedCount: number;
+}
+export interface ICEMazeOptions {
+    rows?: number;
+    cols?: number;
+    random?: () => number;
+}
+export declare const ICE_MAZE_ALGORITHMS: ICEMazeAlgorithm[];
+export declare class ICEMazeModel {
+    private rows;
+    private cols;
+    private random;
+    private walls;
+    private start;
+    private goal;
+    constructor(options?: ICEMazeOptions);
+    getRows(): number;
+    getCols(): number;
+    getStart(): [number, number];
+    getGoal(): [number, number];
+    getAlgorithms(): ICEMazeAlgorithm[];
+    /** 可视化用的网格状态（起点/终点/墙）。 */
+    getCells(): number[];
+    getCell(row: number, col: number): number;
+    isWall(row: number, col: number): boolean;
+    setWall(row: number, col: number, wall: boolean): boolean;
+    toggleWall(row: number, col: number): boolean;
+    clearWalls(): void;
+    /** 按密度随机撒墙（起点终点永远不盖）。 */
+    randomWalls(density?: number): void;
+    setStart(row: number, col: number): boolean;
+    setGoal(row: number, col: number): boolean;
+    solve(algorithm: string): ICEMazeFrame[];
+    private __inside;
+    private __index;
+}
+export default ICEMazeModel;

package/dist/types/model/ICESortModel.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 排序轨迹（纯逻辑，不碰 canvas）。
+ *
+ * 它只做一件事：**把排序算法跑一遍，把过程录成一串帧**。回放交给 `ICETracePlayerModel`，
+ * 画柱子交给页面（`examples/algorithm-sandbox.html` 里用一张 ICETileMap 画）。
+ *
+ * 一帧里带四样东西，正好对应可视化要画的四样：
+ * - `values`：当前数组（柱子高度）；
+ * - `compare`：正在比较的下标（黄色）；
+ * - `swap`：刚刚交换 / 写入的下标（红色）；
+ * - `sortedFrom`：从这里往后已经就位（绿色）。
+ * 再带上 `comparisons` / `swaps` 两个计数 —— 页面上当「代价」展示，也是算法的客观指标。
+ *
+ * 为什么「先录轨迹、再回放」而不是「一边算一边画」：
+ * 1. 算法本身能被单测（最终升序、每帧只是重排、比较次数上界）；
+ * 2. 回放可以随便暂停、单步、倒带、变速，算法不用知道「现在第几帧」；
+ * 3. 同一段轨迹可以换任意渲染方式（柱子 / 数字 / 音效），互不影响。
+ */
+export interface ICESortAlgorithm {
+    key: string;
+    label: string;
+    complexity: string;
+}
+export interface ICESortFrame {
+    values: number[];
+    compare: number[];
+    swap: number[];
+    /** 从这里往后的元素已经就位；排完是 0 */
+    sortedFrom: number;
+    note: string;
+    comparisons: number;
+    swaps: number;
+}
+export interface ICESortOptions {
+    /** 元素个数，默认 24 */
+    size?: number;
+    /** 最大值（柱子最高多少），默认 32 */
+    max?: number;
+    /** 随机源，测试可注入 */
+    random?: () => number;
+}
+export declare const ICE_SORT_ALGORITHMS: ICESortAlgorithm[];
+export declare class ICESortModel {
+    private size;
+    private max;
+    private random;
+    private values;
+    constructor(options?: ICESortOptions);
+    getSize(): number;
+    getMax(): number;
+    getArray(): number[];
+    getAlgorithms(): ICESortAlgorithm[];
+    /** 直接给一组数据（会取整、夹到 1..max）。 */
+    setArray(values: number[]): void;
+    /** 换一批新数据（1..max 的随机数）。 */
+    randomize(): void;
+    /** 洗牌：把**当前这批数字**重新打乱（同一批数据换个顺序，方便对比不同算法）。 */
+    shuffle(): void;
+    /** 跑一遍算法，返回整段轨迹。 */
+    run(algorithm: string): ICESortFrame[];
+    private __normalize;
+}
+export default ICESortModel;

package/dist/types/model/ICETracePlayerModel.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 「轨迹播放器」：把一串预先算好的帧按时间回放（纯逻辑，不碰 canvas）。
+ *
+ * 算法可视化（排序、寻路、正则匹配、Diff…）都是同一个套路：**先把整段过程算成一串帧，
+ * 再按时间回放**。播放 / 暂停 / 单步 / 调速 / 进度 / 到头停住这套逻辑跟具体算法无关，
+ * 所以单独抽出来 —— 算法只负责产帧（`ICESortModel` / `ICEMazeModel`），播放器只管「第几帧、要不要走」。
+ *
+ * 约定：
+ * - `load(frames)` 从头开始（游标 0、暂停）；帧是只读的，播放器不复制、不改写；
+ * - `tick(dt)` 只在播放态推进，按 `stepsPerSecond` 换算（一帧 = 1000 / speed 毫秒）：
+ *   攒够几帧就走几帧（页面每帧调一次，所以正常就是每帧一帧；卡顿后不会「欠着时间」）；
+ * - 走到最后一帧自动停（`isFinished()`），此时再 `play()` 会从头重放；
+ * - 速度夹在 1..60 步/秒，非法值忽略（NaN / 0 / 负数都当没调用）。
+ */
+export declare type ICETraceListener = (model: ICETracePlayerModel<any>) => void;
+export interface ICETracePlayerOptions {
+    /** 初始速度（步/秒），默认 6 */
+    speed?: number;
+}
+export declare class ICETracePlayerModel<T> {
+    private frames;
+    private index;
+    private playing;
+    private speed;
+    private accumulator;
+    private listeners;
+    constructor(options?: ICETracePlayerOptions);
+    getFrameCount(): number;
+    getIndex(): number;
+    getFrame(): T | null;
+    getFrames(): T[];
+    isPlaying(): boolean;
+    getSpeed(): number;
+    getProgress(): number;
+    /** 已经走到（或停在）最后一帧。 */
+    isFinished(): boolean;
+    load(frames: T[]): void;
+    play(): void;
+    pause(): void;
+    togglePlay(): void;
+    stepForward(): boolean;
+    stepBackward(): boolean;
+    seek(index: number): boolean;
+    reset(): void;
+    setSpeed(stepsPerSecond: number): void;
+    /** 播放中按真实时间推进（页面每帧调用）。 */
+    tick(delta: number): boolean;
+    addChangeListener(listener: ICETraceListener): () => void;
+    /** 夹到 1..60；非法值返回 null（调用方据此忽略）。 */
+    private __clampSpeed;
+    private notify;
+}
+export default ICETracePlayerModel;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ice-web-components",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Swing-style Canvas UI components built on ice-render.",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -23,6 +23,8 @@
     "qa:xp": "node scripts/qa-xp.mjs",
     "qa:arcade": "node scripts/qa-arcade.mjs",
     "qa:pixel": "node scripts/qa-pixel.mjs",
+    "qa:algo": "node scripts/qa-algo.mjs",
+    "qa:dos": "node scripts/qa-dos.mjs",
     "docs:api": "node scripts/gen-docs.mjs",
     "docs:check": "node scripts/check-docs.mjs",
     "docs": "npm run docs:api && npm run docs:check",