SourceSteps

Review assignment instructions piece by piece, then focus on one action without losing the original wording.

Comment

Inspiration

An assignment can mix actions, constraints, references and alternatives in one block of text. Keeping track of what to do next while repeatedly finding the relevant instruction is a concrete interaction barrier. A generated summary can also change or omit a qualification that matters.

SourceSteps explores a smaller approach: keep the source text, let the learner label its pieces, and show one chosen action with nearby source context. It is designed to support instruction review, not to write answers, diagnose learners or certify that an assignment has been understood. This is a synthetic-data feasibility prototype, not a demonstrated learning intervention.

What It Does

Paste plain-text instructions or load the fictional garden assignment. Every piece begins Unreviewed. Label each piece Action, Reference or Unclear; adjust adjacent boundaries when a line contains more than one kind of information. The app keeps source order and exact source-position mappings, so repeated wording remains distinguishable and the original text stays available.

An Action can be brought into a one-action focus area, with nearby context and a route back to its source piece. A check records the learner's own choice. Separate counts show labeled text, unreviewed pieces, unclear pieces and checked actions. They deliberately do not turn a completed checklist into a claim that all requirements were understood. References can still contain important constraints.

Changing the source clears the old labels, checks and focus links rather than silently attaching them to different instructions. Split and merge operations reset the affected pieces for review. Local JSON import validates complete source coverage and treats imported text as data, not executable markup. The app offers local JSON export, but a real browser export/download/re-import cycle remains unverified; do not rely on it as a proven backup workflow. There is no autosave: reload or close loses the session unless a usable export has been saved.

Concrete before-and-after example

The intended user is a student reviewing a multi-part written assignment. In the fictional garden sample, the student starts with six mixed instructions and repeatedly scans the full text to locate the observation task. After manually labeling “Record three observations about how plants receive light.” as Action, the student can bring that exact instruction into focus, see nearby context and return to the original piece. The 150–200-word requirement, two-quotation constraint and no-travel alternative remain in the source for review; they are not silently summarized away. This demonstrates an interaction change, not a measured reduction in effort or improved learning.

How It Was Built

The original prototype was created on October 20, 2026 during the AccessED build window, from an empty workspace rather than an existing application foundation. It uses HTML, CSS and JavaScript, with a small Node.js loopback server and Node's built-in test runner. There are no third-party runtime packages, accounts, runtime AI calls or telemetry. After obtaining the archive and the required tools, the app runs locally without an internet connection.

The data model uses contiguous UTF-16 source ranges. Validation checks that all source text belongs to exactly one piece and rejects gaps, overlaps, invalid labels and invalid action-check states. It also prevents boundaries from splitting a Unicode surrogate pair or CRLF line ending. This is textual coverage, not proof of semantic completeness.

Challenges

The key challenge was being precise about what a progress indicator can truthfully mean. Labeled text is not the same as understood text, and a reference can contain a constraint that matters. The interface keeps those distinctions visible rather than reporting an overall assignment-complete score.

Another challenge was keeping edited or imported text aligned with its review state. Tests exposed an inconsistency: imported ranges could split a Unicode pair or CRLF even though the manual split operation refused that boundary. The validation rules now share that boundary protection, with regression coverage.

The server-based v0.1.1-rc1 maintenance fix also prevents an older pending local-file read from prompting, applying data or overwriting status after a newer import selection. Seven handler regressions cover both read completion orders, failures, an invalid newer file, canceled replacement confirmation and an empty selection event. The existing source-edit invalidation remains. Native picker cancellation that emits no change event is outside this handler; automated confirmation stubs do not establish native dialog behavior.

Accomplishments

The published release includes a working local prototype, a reproducible packaging script, a source manifest, synthetic fixtures and 34 passing automated tests recorded in the release verification. Those tests cover mapping, malformed and oversized imports, repeated text, source changes, split/merge behavior, limits and handler-level reset/cancellation/interruption flows.

Previously recorded browser checks covered labeling, focus, checking, returning to source, keyboard split/merge, source-change invalidation, invalid local import, hostile-looking text as literal text, and long-source coverage. Desktop and narrow 390/320-pixel layouts were checked for horizontal overflow. These checks are bounded evidence, not an accessibility certification or a substitute for learner testing.

What We Learned

Preserving the original instructions is valuable only if the interface also makes uncertainty and outstanding review visible. Data integrity and honest progress language are part of the user experience. We also learned to separate automated handler tests from real browser interaction: passing a simulated cancellation test does not prove native dialog focus restoration works.

What Is Next

The next priority is evaluation rather than more features: complete the real export/re-import and native-dialog checks, test screen-reader navigation, full keyboard traversal, zoom and reduced-motion settings, then conduct a permission-based usability study with synthetic assignments. Measure whether people can find original constraints and explain what remains uncertain. No improved learning outcomes or clinical benefits are claimed today.

Built with

HTML; CSS; JavaScript; Node.js 22; Node built-in test runner; Python 3 standard-library release tooling; OpenAI Codex (development assistance only).

AI, dependencies and data disclosure

OpenAI Codex assisted with design, code, documentation and tests. SourceSteps does not call an AI service at runtime, generate assignment answers or automatically classify instructions. The original files are MIT licensed. It uses system fonts and no external images, datasets or npm runtime dependencies. Node.js built-in HTTP/filesystem/VM/test tools and Python standard-library ZIP/hash tools support development and packaging; the runtimes are not redistributed. Demo content is fictional. No real learner records, grades, private assignments or identifiable learner data are included. One-action focus is an established interaction pattern, not a claim of global novelty. Attribution: https://github.com/sharonbasovich/sourcesteps/blob/cafc5bdc9ef267756e0b0a8ed674aa0a37c543ed/ATTRIBUTION.md

Try the downloadable build

  1. Open https://github.com/sharonbasovich/sourcesteps/releases/tag/v0.1.1-rc1 and download/extract SourceSteps-0.1.1-rc1.zip. There is no hosted demo and no installation wizard.
  2. Use a machine with Node.js 22 already available. Open a terminal in the extracted project folder.
  3. Run npm test. Run npm start.
  4. Open http://127.0.0.1:4173 in a browser. The server binds to the local machine, not a public network interface. Direct file:// loading is unsupported.
  5. Stop the server with Ctrl+C when finished. No npm install, account, API key or paid service is needed.
  6. Reloading or closing the browser loses the current session. The export control is not yet end-to-end verified; use the synthetic sample for judging. Full walkthrough: https://github.com/sharonbasovich/sourcesteps/blob/cafc5bdc9ef267756e0b0a8ed674aa0a37c543ed/DEMO.md

Built With

Share this project:

Updates

Submission history