@directive-run/knowledge 0.2.0

package/examples/contact-form.ts

@@ -0,0 +1,176 @@
+// Example: contact-form
+// Source: examples/contact-form/src/main.ts
+// Extracted for AI rules — DOM wiring stripped
+
+/**
+ * Contact Form — DOM Rendering & System Wiring
+ *
+ * Creates the Directive system, subscribes to state changes,
+ * renders the form and event timeline.
+ */
+
+import {
+  type ModuleSchema,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
+import { devtoolsPlugin } from "@directive-run/core/plugins";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const RATE_LIMIT_MS = 10_000; // 10 seconds (shorter for demo)
+
+// ============================================================================
+// Timeline
+// ============================================================================
+
+interface TimelineEntry {
+  time: number;
+  event: string;
+  detail: string;
+  type: string;
+}
+
+const timeline: TimelineEntry[] = [];
+
+function addTimelineEntry(event: string, detail: string, type: string) {
+  timeline.unshift({ time: Date.now(), event, detail, type });
+}
+
+function log(msg: string) {
+  console.log(`[contact-form] ${msg}`);
+
+  // Classify and add to timeline
+  if (msg.startsWith("Sending:")) {
+    addTimelineEntry("submit", msg.replace("Sending: ", ""), "submit");
+  } else if (msg.includes("succeeded")) {
+    addTimelineEntry("success", msg, "submit");
+  } else if (msg.includes("failed")) {
+    addTimelineEntry("error", msg, "error");
+  } else if (msg.startsWith("Status:")) {
+    addTimelineEntry("status", msg.replace("Status: ", ""), "field");
+  } else if (msg.includes("Auto-resetting")) {
+    addTimelineEntry("auto-reset", msg, "reset");
+  } else if (msg === "Form reset") {
+    addTimelineEntry("reset", "Form cleared", "reset");
+  } else if (msg.includes("ready")) {
+    addTimelineEntry("init", msg, "field");
+  }
+}
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+const schema = {
+  facts: {
+    name: t.string(),
+    email: t.string(),
+    subject: t.string(),
+    message: t.string(),
+    touched: t.object<Record<string, boolean>>(),
+    status: t.string<"idle" | "submitting" | "success" | "error">(),
+    errorMessage: t.string(),
+    lastSubmittedAt: t.number(),
+    submissionCount: t.number(),
+  },
+  derivations: {
+    nameError: t.string(),
+    emailError: t.string(),
+    subjectError: t.string(),
+    messageError: t.string(),
+    isValid: t.boolean(),
+    canSubmit: t.boolean(),
+    messageCharCount: t.number(),
+  },
+  events: {
+    updateField: { field: t.string(), value: t.string() },
+    touchField: { field: t.string() },
+    submit: {},
+    reset: {},
+  },
+  requirements: {
+    SEND_MESSAGE: {},
+    RESET_AFTER_DELAY: {},
+  },
+} satisfies ModuleSchema;
+
+// ============================================================================
+// Module
+// ============================================================================
+
+
+// ============================================================================
+// System
+// ============================================================================
+
+const system = createSystem({
+  module: contactForm,
+  debug: { runHistory: true },
+  plugins: [devtoolsPlugin({ name: "contact-form" })],
+});
+system.start();
+
+// ============================================================================
+// DOM References
+// ============================================================================
+
+// Form inputs
+
+// Timeline
+
+// ============================================================================
+// Input Handlers
+// ============================================================================
+
+for (const [el, field] of [
+  [nameInput, "name"],
+  [emailInput, "email"],
+  [subjectInput, "subject"],
+  [messageInput, "message"],
+] as const) {
+}
+
+
+// ============================================================================
+// Render
+// ============================================================================
+
+function escapeHtml(text: string): string {
+
+  return div.innerHTML;
+}
+
+
+// Subscribe to all relevant facts and derivations
+system.subscribe(
+  [
+    "name",
+    "email",
+    "subject",
+    "message",
+    "touched",
+    "status",
+    "errorMessage",
+    "lastSubmittedAt",
+    "submissionCount",
+    "nameError",
+    "emailError",
+    "subjectError",
+    "messageError",
+    "isValid",
+    "canSubmit",
+    "messageCharCount",
+  ],
+  render,
+);
+
+// Initial render
+render();
+log("Contact form ready. Fill in all fields and submit.");
+
+// Signal to tests that initialization is complete

package/examples/counter.ts

@@ -0,0 +1,393 @@
+// Example: counter
+// Source: examples/counter/src/main.ts
+// Extracted for AI rules — DOM wiring stripped
+
+/**
+ * Number Match — DOM Rendering & System Wiring
+ *
+ * Creates the Directive system, subscribes to state changes,
+ * renders the game grid and event timeline.
+ */
+
+import {
+  type ModuleSchema,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
+import { devtoolsPlugin } from "@directive-run/core/plugins";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface Tile {
+  id: string;
+  value: number;
+}
+
+interface TimelineEntry {
+  time: number;
+  event: string;
+  detail: string;
+  type: string;
+}
+
+// Create a pool of numbered tiles (1-9, four of each = 36 tiles)
+function createPool(): Tile[] {
+  const tiles: Tile[] = [];
+  let id = 0;
+  for (let copy = 0; copy < 4; copy++) {
+    for (let value = 1; value <= 9; value++) {
+      tiles.push({ id: `t${id++}`, value });
+    }
+  }
+  // Shuffle
+  for (let i = tiles.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [tiles[i], tiles[j]] = [tiles[j], tiles[i]];
+  }
+
+  return tiles;
+}
+
+// ============================================================================
+// Timeline
+// ============================================================================
+
+const timeline: TimelineEntry[] = [];
+
+function log(msg: string) {
+  console.log(`[NumberMatch] ${msg}`);
+
+  // Classify and add significant events to the timeline
+  let event = "";
+  let detail = "";
+  let type = "info";
+
+  if (msg.startsWith("EVENT selectTile")) {
+    event = "tile selected";
+    const match = msg.match(/selectTile: (t\d+)/);
+    detail = match ? match[1] : "";
+    type = "selection";
+  } else if (msg.includes("pairAddsTen: TRUE")) {
+    event = "match found";
+    const match = msg.match(/\((.+)\)/);
+    detail = match ? match[1] : "";
+    type = "match";
+  } else if (msg === "RESOLVER removeTiles: DONE") {
+    event = "tiles removed";
+    detail = "";
+    type = "match";
+  } else if (msg.includes("refillTable: DONE")) {
+    event = "refill";
+    const match = msg.match(/table now: (\d+)/);
+    detail = match ? `table: ${match[1]} tiles` : "";
+    type = "refill";
+  } else if (msg.startsWith("RESOLVER endGame:")) {
+    event = "game over";
+    detail = msg.replace("RESOLVER endGame: ", "");
+    type = "gameover";
+  } else if (msg.includes("New game") || msg.includes("Game started")) {
+    event = "new game";
+    detail = msg;
+    type = "newgame";
+  } else {
+    // Skip verbose intermediate messages (RESOLVER steps, CONSTRAINT produce)
+    return;
+  }
+
+  timeline.unshift({ time: Date.now(), event, detail, type });
+}
+
+// ============================================================================
+// Schema - same structure as eleven-up
+// ============================================================================
+
+const schema = {
+  facts: {
+    pool: t.object<Tile[]>(),
+    table: t.object<Tile[]>(),
+    removed: t.object<Tile[]>(),
+    selected: t.object<string[]>(),
+    message: t.string(),
+    moveCount: t.number(),
+    gameOver: t.boolean(),
+  },
+  derivations: {
+    poolCount: t.number(),
+    removedCount: t.number(),
+    selectedTiles: t.object<Tile[]>(),
+    hasValidMoves: t.boolean(),
+  },
+  events: {
+    newGame: {},
+    selectTile: { tileId: t.string() },
+    deselectTile: { tileId: t.string() },
+    clearSelection: {},
+  },
+  requirements: {
+    REMOVE_TILES: { tileIds: t.object<string[]>() },
+    REFILL_TABLE: { count: t.number() },
+    END_GAME: { reason: t.string() },
+  },
+} satisfies ModuleSchema;
+
+// ============================================================================
+// Module
+// ============================================================================
+
+const numberMatch = createModule("number-match", {
+  schema,
+
+  init: (facts) => {
+    const pool = createPool();
+    facts.pool = pool.slice(9);
+    facts.table = pool.slice(0, 9);
+    facts.removed = [];
+    facts.selected = [];
+    facts.message = "Select two numbers that add to 10";
+    facts.moveCount = 0;
+    facts.gameOver = false;
+  },
+
+  derive: {
+    poolCount: (facts) => facts.pool.length,
+    removedCount: (facts) => facts.removed.length,
+    selectedTiles: (facts) =>
+      facts.table.filter((tile: Tile) => facts.selected.includes(tile.id)),
+    hasValidMoves: (facts) => {
+      const nums = facts.table.map((t: Tile) => t.value);
+      for (let i = 0; i < nums.length; i++) {
+        for (let j = i + 1; j < nums.length; j++) {
+          if (nums[i] + nums[j] === 10) return true;
+        }
+      }
+      return false;
+    },
+  },
+
+  events: {
+    newGame: (facts) => {
+      const pool = createPool();
+      facts.pool = pool.slice(9);
+      facts.table = pool.slice(0, 9);
+      facts.removed = [];
+      facts.selected = [];
+      facts.message = "New game! Select two numbers that add to 10";
+      facts.moveCount = 0;
+      facts.gameOver = false;
+    },
+    selectTile: (facts, { tileId }) => {
+      if (!facts.selected.includes(tileId) && !facts.gameOver) {
+        facts.selected = [...facts.selected, tileId];
+        log(`EVENT selectTile: ${tileId}, selected now: [${facts.selected}]`);
+      }
+    },
+    deselectTile: (facts, { tileId }) => {
+      facts.selected = facts.selected.filter((id: string) => id !== tileId);
+    },
+    clearSelection: (facts) => {
+      facts.selected = [];
+    },
+  },
+
+  // ============================================================================
+  // Constraints - same pattern as eleven-up
+  // ============================================================================
+  constraints: {
+    // When two selected tiles add to 10 -> remove them
+    pairAddsTen: {
+      priority: 100,
+      when: (facts) => {
+        if (facts.gameOver) return false;
+        const selected = facts.table.filter((tile: Tile) =>
+          facts.selected.includes(tile.id),
+        );
+        if (selected.length !== 2) return false;
+        const result = selected[0].value + selected[1].value === 10;
+        if (result)
+          log(
+            `CONSTRAINT pairAddsTen: TRUE (${selected[0].value} + ${selected[1].value})`,
+          );
+        return result;
+      },
+      require: (facts) => {
+        log("CONSTRAINT pairAddsTen: producing REMOVE_TILES");
+        return {
+          type: "REMOVE_TILES",
+          tileIds: [...facts.selected],
+        };
+      },
+    },
+
+    // Refill table when tiles are removed
+    refillTable: {
+      priority: 50,
+      when: (facts) => {
+        const result =
+          !facts.gameOver && facts.table.length < 9 && facts.pool.length > 0;
+        if (result)
+          log(
+            `CONSTRAINT refillTable: TRUE (table: ${facts.table.length}, pool: ${facts.pool.length})`,
+          );
+        return result;
+      },
+      require: (facts) => {
+        const count = Math.min(9 - facts.table.length, facts.pool.length);
+        log(`CONSTRAINT refillTable: producing REFILL_TABLE count=${count}`);
+        return { type: "REFILL_TABLE", count };
+      },
+    },
+
+    // No moves left -> game over
+    noMovesLeft: {
+      priority: 190,
+      when: (facts) => {
+        if (facts.gameOver) return false;
+        if (facts.table.length === 0) return false;
+        if (facts.pool.length > 0) return false;
+        const nums = facts.table.map((t: Tile) => t.value);
+        for (let i = 0; i < nums.length; i++) {
+          for (let j = i + 1; j < nums.length; j++) {
+            if (nums[i] + nums[j] === 10) return false;
+          }
+        }
+        log("CONSTRAINT noMovesLeft: TRUE");
+        return true;
+      },
+      require: (facts) => ({
+        type: "END_GAME",
+        reason: `Game over! Removed ${facts.removed.length} of 36 tiles.`,
+      }),
+    },
+
+    // Win condition
+    allCleared: {
+      priority: 200,
+      when: (facts) => {
+        const result =
+          !facts.gameOver &&
+          facts.table.length === 0 &&
+          facts.pool.length === 0;
+        if (result) log("CONSTRAINT allCleared: TRUE");
+        return result;
+      },
+      require: (facts) => ({
+        type: "END_GAME",
+        reason: `You win! Cleared all tiles in ${facts.moveCount} moves!`,
+      }),
+    },
+  },
+
+  // ============================================================================
+  // Resolvers - same multi-fact mutation pattern as eleven-up
+  // ============================================================================
+  resolvers: {
+    removeTiles: {
+      requirement: "REMOVE_TILES",
+      resolve: async (req, context) => {
+        log("RESOLVER removeTiles: START");
+        const tilesToRemove = context.facts.table.filter((tile: Tile) =>
+          req.tileIds.includes(tile.id),
+        );
+
+        // Multiple fact mutations
+        log("RESOLVER removeTiles: setting table");
+        context.facts.table = context.facts.table.filter(
+          (tile: Tile) => !req.tileIds.includes(tile.id),
+        );
+        log("RESOLVER removeTiles: setting removed");
+        context.facts.removed = [...context.facts.removed, ...tilesToRemove];
+        log("RESOLVER removeTiles: clearing selected");
+        context.facts.selected = [];
+        log("RESOLVER removeTiles: incrementing moveCount");
+        context.facts.moveCount++;
+        log("RESOLVER removeTiles: setting message");
+        context.facts.message = `Removed ${tilesToRemove[0].value} + ${tilesToRemove[1].value} = 10!`;
+        log("RESOLVER removeTiles: DONE");
+      },
+    },
+
+    refillTable: {
+      requirement: "REFILL_TABLE",
+      resolve: async (req, context) => {
+        log(`RESOLVER refillTable: START (count: ${req.count})`);
+        const newTiles = context.facts.pool.slice(0, req.count);
+        context.facts.pool = context.facts.pool.slice(req.count);
+        context.facts.table = [...context.facts.table, ...newTiles];
+        log(
+          `RESOLVER refillTable: DONE (table now: ${context.facts.table.length})`,
+        );
+      },
+    },
+
+    endGame: {
+      requirement: "END_GAME",
+      resolve: async (req, context) => {
+        log(`RESOLVER endGame: ${req.reason}`);
+        context.facts.gameOver = true;
+        context.facts.message = req.reason;
+      },
+    },
+  },
+});
+
+// ============================================================================
+// System
+// ============================================================================
+
+const system = createSystem({
+  module: numberMatch,
+  plugins: [devtoolsPlugin({ name: "number-match" })],
+  debug: { timeTravel: true, runHistory: true },
+});
+system.start();
+
+// ============================================================================
+// DOM References
+// ============================================================================
+
+// Stats
+
+// Timeline
+
+// ============================================================================
+// Render
+// ============================================================================
+
+function escapeHtml(text: string): string {
+
+  return div.innerHTML;
+}
+
+
+// ============================================================================
+// Subscribe
+// ============================================================================
+
+system.subscribe(
+  [
+    "table",
+    "selected",
+    "pool",
+    "removed",
+    "moveCount",
+    "message",
+    "gameOver",
+    "poolCount",
+    "removedCount",
+    "selectedTiles",
+    "hasValidMoves",
+  ],
+  render,
+);
+
+// Button handlers
+
+
+// Initial render
+render();
+log("Game started. Select two numbers that add to 10.");
+
+// Signal to tests that initialization is complete