@rohal12/spindle 0.1.0

package/dist/pkg/types/index.d.ts

@@ -0,0 +1,158 @@
+// Format metadata (used by twee-ts)
+export declare const name: string;
+export declare const version: string;
+export declare const source: string;
+export declare const proofing: boolean;
+
+// --- Format-specific API types (used by story authors) ---
+
+/**
+ * A moment in the story history, capturing the state at a specific navigation point.
+ * @see {@link ../../src/store.ts} for the implementation.
+ */
+export interface HistoryMoment {
+  passage: string;
+  variables: Record<string, unknown>;
+  timestamp: number;
+}
+
+/**
+ * Payload stored in a save slot.
+ * @see {@link ../../src/saves/types.ts} for the implementation.
+ */
+export interface SavePayload {
+  passage: string;
+  variables: Record<string, unknown>;
+  history: HistoryMoment[];
+  historyIndex: number;
+  visitCounts?: Record<string, number>;
+  renderCounts?: Record<string, number>;
+}
+
+/**
+ * Configuration for a toggle (boolean) setting.
+ * @see {@link ../../src/settings.ts} for the implementation.
+ */
+export interface ToggleConfig {
+  label: string;
+  default: boolean;
+}
+
+/**
+ * Configuration for a list (dropdown) setting.
+ * @see {@link ../../src/settings.ts} for the implementation.
+ */
+export interface ListConfig {
+  label: string;
+  options: string[];
+  default: string;
+}
+
+/**
+ * Configuration for a range (slider) setting.
+ * @see {@link ../../src/settings.ts} for the implementation.
+ */
+export interface RangeConfig {
+  label: string;
+  min: number;
+  max: number;
+  step: number;
+  default: number;
+}
+
+/**
+ * Discriminated union of setting definitions.
+ * @see {@link ../../src/settings.ts} for the implementation.
+ */
+export type SettingDef =
+  | { type: 'toggle'; config: ToggleConfig }
+  | { type: 'list'; config: ListConfig }
+  | { type: 'range'; config: RangeConfig };
+
+/**
+ * The settings API for registering and managing story settings.
+ * Settings appear in the built-in settings dialog.
+ * @see {@link ../../src/settings.ts} for the implementation.
+ */
+export interface SettingsAPI {
+  addToggle(name: string, config: ToggleConfig): void;
+  addList(name: string, config: ListConfig): void;
+  addRange(name: string, config: RangeConfig): void;
+  get(name: string): unknown;
+  set(name: string, value: unknown): void;
+  getAll(): Record<string, unknown>;
+  getDefinitions(): Map<string, SettingDef>;
+  hasAny(): boolean;
+}
+
+/**
+ * The main Story API available as `window.Story` at runtime.
+ * Provides access to variables, navigation, save/load, and visit tracking.
+ * @see {@link ../../src/story-api.ts} for the implementation.
+ */
+export interface StoryAPI {
+  /** Get the value of a story variable. */
+  get(name: string): unknown;
+
+  /** Set a single story variable. */
+  set(name: string, value: unknown): void;
+  /** Set multiple story variables at once. */
+  set(vars: Record<string, unknown>): void;
+
+  /** Navigate to a passage by name. */
+  goto(passageName: string): void;
+
+  /** Go back one step in history. */
+  back(): void;
+
+  /** Go forward one step in history. */
+  forward(): void;
+
+  /** Restart the story from the beginning. */
+  restart(): void;
+
+  /** Save the current state (quick save). */
+  save(slot?: string): void;
+
+  /** Load a saved state (quick load). */
+  load(slot?: string): void;
+
+  /** Check whether a save exists. */
+  hasSave(slot?: string): boolean;
+
+  /** Return the number of times a passage has been visited. */
+  visited(name: string): number;
+
+  /** Check if a passage has been visited at least once. */
+  hasVisited(name: string): boolean;
+
+  /** Check if any of the given passages have been visited. */
+  hasVisitedAny(...names: string[]): boolean;
+
+  /** Check if all of the given passages have been visited. */
+  hasVisitedAll(...names: string[]): boolean;
+
+  /** Return the number of times a passage has been rendered. */
+  rendered(name: string): number;
+
+  /** Check if a passage has been rendered at least once. */
+  hasRendered(name: string): boolean;
+
+  /** Check if any of the given passages have been rendered. */
+  hasRenderedAny(...names: string[]): boolean;
+
+  /** Check if all of the given passages have been rendered. */
+  hasRenderedAll(...names: string[]): boolean;
+
+  /** The story title. */
+  readonly title: string;
+
+  /** The settings API. */
+  readonly settings: SettingsAPI;
+
+  /** Save system configuration. */
+  readonly saves: {
+    /** Set a custom function to generate save titles. */
+    setTitleGenerator(fn: (payload: SavePayload) => string): void;
+  };
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@rohal12/spindle",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A Preact-based story format for Twine 2.",
+  "license": "Unlicense",
+  "author": "Rohal12",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rohal12/spindle.git"
+  },
+  "homepage": "https://rohal12.github.io/spindle/",
+  "bugs": "https://github.com/rohal12/spindle/issues",
+  "keywords": [
+    "twine-story-format",
+    "twine",
+    "interactive-fiction",
+    "story-format",
+    "preact"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/pkg/types/index.d.ts",
+      "import": "./dist/pkg/index.js"
+    }
+  },
+  "files": [
+    "dist/pkg/index.js",
+    "dist/pkg/format.js",
+    "dist/pkg/types",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build && bun run scripts/build-format.ts",
+    "compile": "bun run scripts/compile-story.ts",
+    "preview": "bun run build && bun run compile",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "prepublishOnly": "bun run test && bun run build"
+  },
+  "dependencies": {
+    "immer": "^10.1.0",
+    "micromark": "^4.0.2",
+    "micromark-extension-gfm-strikethrough": "^2.1.0",
+    "micromark-extension-gfm-table": "^2.1.1",
+    "preact": "^10.25.0",
+    "zustand": "^5.0.0"
+  },
+  "devDependencies": {
+    "@preact/preset-vite": "^2.9.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "happy-dom": "^20.7.0",
+    "playwright": "^1.58.2",
+    "prettier": "^3.8.1",
+    "tweenode": "^0.3.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0",
+    "vite-plugin-singlefile": "^2.0.0",
+    "vitepress": "^1.6.4",
+    "vitest": "^4.0.18"
+  }
+}

package/src/components/App.tsx

@@ -0,0 +1,53 @@
+import { useEffect } from 'preact/hooks';
+import { useStoryStore } from '../store';
+import { Passage } from './Passage';
+import { StoryInterface } from './StoryInterface';
+
+export function App() {
+  const currentPassage = useStoryStore((s) => s.currentPassage);
+  const storyData = useStoryStore((s) => s.storyData);
+
+  useEffect(() => {
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'F6') {
+        e.preventDefault();
+        useStoryStore.getState().save();
+      } else if (e.key === 'F9') {
+        e.preventDefault();
+        useStoryStore.getState().load();
+      }
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, []);
+
+  if (!storyData || !currentPassage) {
+    return <div class="loading">Loading...</div>;
+  }
+
+  const passage = storyData.passages.get(currentPassage);
+  if (!passage) {
+    return (
+      <div class="error">
+        Error: Passage &ldquo;{currentPassage}&rdquo; not found.
+      </div>
+    );
+  }
+
+  return (
+    <>
+      <header class="story-menubar">
+        <StoryInterface />
+      </header>
+      <div
+        id="story"
+        class="story"
+      >
+        <Passage
+          passage={passage}
+          key={currentPassage}
+        />
+      </div>
+    </>
+  );
+}

package/src/components/Passage.tsx

@@ -0,0 +1,36 @@
+import { useMemo } from 'preact/hooks';
+import { tokenize } from '../markup/tokenizer';
+import { buildAST } from '../markup/ast';
+import { renderNodes } from '../markup/render';
+import type { Passage as PassageData } from '../parser';
+
+interface PassageProps {
+  passage: PassageData;
+}
+
+export function Passage({ passage }: PassageProps) {
+  const content = useMemo(() => {
+    try {
+      const tokens = tokenize(passage.content);
+      const ast = buildAST(tokens);
+      return renderNodes(ast);
+    } catch (err) {
+      return (
+        <div class="error">
+          Error parsing passage &ldquo;{passage.name}&rdquo;:{' '}
+          {(err as Error).message}
+        </div>
+      );
+    }
+  }, [passage.content, passage.name]);
+
+  return (
+    <div
+      class="passage"
+      data-passage={passage.name}
+      data-tags={passage.tags.join(' ')}
+    >
+      {content}
+    </div>
+  );
+}

package/src/components/PassageLink.tsx

@@ -0,0 +1,35 @@
+import { useStoryStore } from '../store';
+
+interface PassageLinkProps {
+  target: string;
+  className?: string;
+  id?: string;
+  children: preact.ComponentChildren;
+}
+
+export function PassageLink({
+  target,
+  className,
+  id,
+  children,
+}: PassageLinkProps) {
+  const navigate = useStoryStore((s) => s.navigate);
+
+  const handleClick = (e: MouseEvent) => {
+    e.preventDefault();
+    navigate(target);
+  };
+
+  const cls = className ? `passage-link ${className}` : 'passage-link';
+
+  return (
+    <a
+      href="#"
+      id={id}
+      class={cls}
+      onClick={handleClick}
+    >
+      {children}
+    </a>
+  );
+}