ice-web-components 1.3.0 → 1.4.0

package/dist/types/index.d.ts

@@ -113,3 +113,7 @@ 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/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.3.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",