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.

Source edits now stay in a clearly marked draft without erasing labels, checks or focus. Apply validates the draft and asks before resetting existing review work; Discard restores the applied source and keeps that work. Export is disabled while a source draft is unresolved. 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 v0.1.3-rc1 update extends stale-import protection to source drafts and discard actions. Native picker cancellation that emits no change event is outside this handler; automated confirmation stubs do not establish native dialog behavior.

Accomplishments

The v0.1.6-rc1 release adds a noneditable split-point slider and quoted before/after preview, so learners can choose a boundary without counting UTF-16 offsets. Numeric offsets remain available; exact source, pending drafts, normal native Undo/Redo and unresolved navigation are preserved. Independent review and local checks passed 71 application/model tests, six helper tests, five selector and five navigation Chrome groups, plus deterministic packaging, extracted tests/manifests and loopback HTTP/CSP. Hosted verification did not start because of the account billing lock. The full general/exit suites and native file operations were not rerun; CRLF browser coverage uses a synthetic startup sample. Physical-touch and screen-reader validation remain unverified. There is no autosave or app Undo stack.

Historical v0.1.5-rc1 verification: the release adds direct routes to unreviewed and unclear instructions, a per-piece Next piece needing review loop, and Read piece from start for long text. Navigation preserves exact source, manual labels, checks, action focus and pending drafts. An all-labeled state still does not mean assignment completion. Independent scoped implementation, keyboard/mobile experience and final metadata/package review passed. Fresh November 7 local checks passed 68 application tests, six helper tests, and five Chrome groups: three responsive reduced-motion groups at 1280/390/320 CSS pixels plus two default-motion long-piece groups at 390/320. Deterministic packaging, extracted tests/manifests and loopback HTTP/CSP checks passed. The full general and exit-warning browser suites were not rerun in this pass; their earlier results below remain historical. Hosted CI did not start due to the account billing lock. Native picker, physical-device, screen-reader, learning-gain and accessibility-conformance claims remain outside this verification.

The earlier v0.1.4-rc1 release adds a best-effort browser page-exit warning for unapplied drafts or review state that differs from the sample, empty workspace or latest confirmed imported file. Export never clears protection. There is no autosave, and browsers may skip prompts on mobile closure, crashes or process termination. Fresh local validation on November 7, 2026 passed 62 Node tests, six dialog-helper tests, deterministic packaging, extracted-package tests, manifests and loopback HTTP/CSP checks. The unchanged runtime passed 11 dedicated headed Chrome groups and ten existing browser groups on November 5. Those automated synthetic browser checks include an actual JSON download, reload and re-import with exact Unicode/CRLF recovery and byte-identical re-export. This supersedes the earlier export-verification limitation recorded elsewhere in this story; the native operating-system file chooser remains unverified. Independent implementation and final release-metadata review passed. Hosted GitHub verification did not start because of an account billing lock and is not claimed passed. No all-browser, physical-device, screen-reader or accessibility-conformance claim is made.

The earlier v0.1.3-rc1 release includes a working local prototype, a reproducible packaging script, a source manifest, synthetic fixtures and 54 passing Node tests. Nine automated HTTP Chromium test groups cover rejected and successful boundary edits, Unicode/CRLF, the 500-piece limit, source draft apply/discard/cancel, imported CRLF preservation, navigation, and Clear workspace confirmation cancellation and acceptance. The rejected-edit fix preserves the focused action and its checkbox and return-to-source controls when a split is refused. Independent source review and actual rendered desktop/narrow-browser review also passed. The native Apply confirmation was canceled with Escape; keyboard Discard restored the source and focus without losing a checked action. Keyboard split/back controls and 320/390-pixel layouts with reduced-motion preference enabled were checked in isolated synthetic Chromium; this is not all-browser or physical-device verification.

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 checks, native file-picker cancellation, manual screen-reader navigation, full keyboard traversal, zoom and physical-device testing, then conduct a permission-based usability study with synthetic assignments. Clear workspace confirmation cancel/accept and reduced-motion layouts have been checked only in isolated synthetic Chromium; broader browser and assistive-technology behavior remains unverified. 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.6-rc1 and download/extract SourceSteps-0.1.6-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/73e689a62f2d8be6da1d9eb8d4fc87f863abdde2/DEMO.md

Built With

Share this project:

Updates

Submission history