System Requirements Document for laba-laba

1. Introduction

laba-laba is an AI spider solver for image puzzles. The operator uploads a puzzle image — the first, unsolved picture — and the system genuinely solves it, producing a result that corresponds to the expected solved image (the second picture). The product is not a canned demo: the same pipeline must work when the operator uploads a different puzzle.

The defining experience is watching the work happen. A designed spider and its visual environment perform the solving, and a detailed terminal log records the step-by-step process. The audience is a technically literate operator who wants to observe a real computation — a laboratory readout crossed with an art installation — and who judges the output by comparing the produced solution against the puzzle they submitted.

This document covers the current delivery: the public entry, puzzle intake, the real solve, the spider animation, the terminal log, and the solution result.

2. System Overview

laba-laba is a first-party web application with a custom UI. It consists of a browser-facing surface and a backend that performs the actual puzzle solving.

Actors

• Puzzle Solver Operator (human, the only active persona): uploads puzzle images, starts solves, watches the spider and terminal, and judges the produced solution against the expected solved image.
• Solver backend (system actor): receives the uploaded puzzle, runs the real solving pipeline, emits stage events and log lines, and returns the solved image plus run metadata.
• AI solver model / computer-vision pipeline (system actor): the genuine solving capability — segmentation, fragment matching, placement, and verification — that operates on the uploaded puzzle's own pixels.

Accepted behavior

• A puzzle image is provided before a solve can start.
• The solver genuinely processes each newly uploaded puzzle rather than replaying a fixed simulation.
• The spider and its visual appearance are designed and animated while it performs its solving work.
• A detailed terminal/console log shows the step-by-step solving process.
• The animated spider and terminal log remain available while the solve is in progress.
• The generated result is available for comparison with the original input image.

Ownership and access

All six surfaces are application-owned custom pages with no access requirement: the operator can reach the Landing, Upload Puzzle, Solve, Spider Animation, Terminal Log, and Solution Result surfaces without establishing an account. No identity, sign-in, or account-management capability is part of this product.

Narrow exclusions

• The solver must not be a simulation; it must genuinely solve newly uploaded puzzles rather than replaying a fixed demo.
• No canned or looping demo animation may be presented as a solve; every motion on the solve page must be driven by real solver state.
• No decorative 3D spider that moves independently of the actual solve events.

2a. Product Interpretation and Delivery Boundary

laba-laba is delivered as a first-party web application. The operator works entirely in the browser: they land on a public entry surface, upload a puzzle image, start a solve, watch the spider and the terminal while the backend works, and then compare the produced solution against their original upload.

The solving itself is owned by the application's own backend. The uploaded puzzle's pixels drive the pipeline; the frontend renders the spider's motion and the terminal lines from real solver events emitted during the run, not from a timer or a pre-recorded sequence. This is the boundary that makes the product's core promise true: a different puzzle produces a different run, different log lines, and a different solution image.

Access is open. There is no account, no sign-in, and no per-user state that must be privately owned or resumed across sessions. The current delivery horizon covers the six surfaces above and nothing beyond them. Future ideas are not part of this delivery and are not represented in any page or acceptance criterion.

2c. Page Content and Component Coverage

Landing

• Information/state: the product's purpose — upload a puzzle image, watch the spider genuinely solve it, read the detailed terminal log, and compare the result against the expected solved image. A live status line indicating solver readiness.
• Primary action: proceed to upload a puzzle.
• Supporting action: read how the solver works (an explanation of the real pipeline stages: segment, match, place, verify).
• Domain entities: puzzle image (not yet provided), solver status.
• Component responsibilities: wordmark with spider glyph; one-line live status readout; oversized headline; primary upload call-to-action; secondary explanatory link; full-bleed generative canvas seeded by a sample puzzle.
• States: loading — canvas initializes and the status line reads as not yet ready; empty — no puzzle has been provided, upload is the only forward path; success — status reads ready and the upload action is available; error — if the solver reports itself unavailable, the status line states this plainly and the upload action is disabled with an explanation; recovery — the status line re-polls and the upload action re-enables when the solver reports ready.

Upload Puzzle

• Information/state: the currently selected puzzle image, its filename and dimensions, and whether it is acceptable for solving.
• Primary action: submit the selected puzzle image for solving.
• Supporting actions: choose a different image; remove the current selection.
• Domain entities: puzzle image (the first, unsolved picture), file metadata.
• Component responsibilities: file selection control; preview of the selected puzzle; validation feedback; submit control; navigation back to the entry surface.
• States: loading — the selected file is being read and previewed; empty — no image selected, submit unavailable; success — a valid image is selected and previewed, submit available; error — the file is not a readable image or is otherwise unusable, with a specific reason and the selection retained so the operator can replace it; recovery — selecting a valid replacement clears the error and restores submit.

Solve

• Information/state: the submitted puzzle, the current run's status (queued, running, completed, failed), the current pipeline stage, and elapsed time.
• Primary action: start the solve on the submitted puzzle.
• Supporting actions: cancel an in-progress run; start a new solve after completion or failure.
• Domain entities: solve run, pipeline stage, elapsed time, run outcome.
• Component responsibilities: run control; run status readout; stage indicator; elapsed-time readout; handoff into the spider animation and terminal log for the active run; navigation to the solution result on completion.
• States: loading — the run is being created and the first stage has not yet reported; empty — no puzzle submitted, start unavailable; success — the run completes and the solution result becomes available; error — the run fails, with the failing stage identified and the reason stated; recovery — the operator can start a new run on the same or a different puzzle without losing the previous failure information.

Spider Animation

• Information/state: the designed spider and its web, driven by the active run's real solver events — the spider's legs step in sync with each pipeline stage, threads connect fragment to fragment as matches are found, and the flow's color temperature shifts with confidence.
• Primary action: observe the spider performing the work (no separate invocation; it is the live view of the active run).
• Supporting actions: return to the run controls; proceed to the terminal log or the solution result.
• Domain entities: spider, web threads, puzzle fragments, pipeline stage events, match confidence.
• Component responsibilities: generative canvas seeded by the uploaded puzzle's edge map and dominant colors; spider agent whose motion is bound to real solver events; thread rendering for each placed fragment; stage-synchronized stepping.
• States: loading — the canvas initializes and the web is seeded from the uploaded puzzle before the first event arrives; empty — no active run, the web drifts idly and the spider holds a resting pose; success — the run completes and the spider settles with the fully woven web; error — the run fails and the spider halts at the failing stage with the web left in its partial state; recovery — starting a new run re-seeds the web from the new puzzle and the spider resumes stepping.

Terminal Log

• Information/state: the detailed, timestamped, step-by-step record of the solving process as it is emitted — stage transitions, per-stage counts, match results, elapsed times, and the currently executing line.
• Primary action: read the log as the run proceeds.
• Supporting actions: scroll through earlier lines; return to the run controls or the solution result.
• Domain entities: log line, timestamp, pipeline stage, per-stage count, elapsed time.
• Component responsibilities: monospace log surface; timestamped line rendering; highlight of the currently executing line; auto-scroll that follows new lines without preventing the operator from scrolling back.
• States: loading — the log surface is present and awaiting the first emitted line; empty — no active run, the log states that no run is in progress; success — the run completes and the full log remains readable; error — the run fails and the failing line is present in the log with its reason; recovery — a new run appends a fresh log for that run while the previous run's log remains available for reading.

Solution Result

• Information/state: the generated solved image presented alongside the original uploaded puzzle for comparison, with run metadata (fragment count, match confidence, elapsed time).
• Primary action: compare the produced solution against the original puzzle.
• Supporting actions: start a new solve with a different puzzle; return to the run controls or the terminal log for the completed run.
• Domain entities: original puzzle image, solved image, fragment count, match confidence, elapsed time.
• Component responsibilities: two-up comparison of original and solved image; ruled metadata strip beneath each image; navigation to start a new solve.
• States: loading — the solved image is being retrieved and rendered; empty — no completed run exists, with a path back to upload; success — both images and the metadata strip are shown; error — the solved image cannot be retrieved, with the reason stated and the completed run's log still reachable; recovery — retrying the retrieval restores the comparison, or the operator starts a new solve.

3. Functional Requirements

FR-1 — Provide a puzzle image before solving (explicit; required_inference for the intake step) As a Puzzle Solver Operator, I should provide a puzzle image before starting a solve, so that the solver has the first, unsolved picture to work on.

• Trigger/input: the operator selects an image file on the Upload Puzzle surface.
• Observable result: the selected puzzle is previewed with its filename and dimensions, and the submit action becomes available.
• Access state: no access requirement; reachable without an account.
• Failure/recovery: if the file is not a readable image, a specific reason is shown and the selection is retained so the operator can replace it.
• Continuation: the operator submits the puzzle to the Solve surface.

FR-2 — Start a real solve on the submitted puzzle (explicit) As a Puzzle Solver Operator, I should start the AI spider solver on my submitted puzzle, so that a solved result is produced from my image.

• Trigger/input: the operator starts the solve on the Solve surface with a puzzle submitted.
• Observable result: a run is created, its status moves from queued to running, and the current pipeline stage and elapsed time are shown.
• Access state: no access requirement.
• Failure/recovery: if the run fails, the failing stage is identified with its reason, and the operator can start a new run without losing the failure information.
• Continuation: the operator watches the Spider Animation and reads the Terminal Log while the run proceeds.

FR-3 — Genuinely solve each newly uploaded puzzle, not a simulation (explicit; hard constraint) As a Puzzle Solver Operator, I should get a genuine solve of whatever puzzle I upload, so that the result reflects my image rather than a fixed demo.

• Trigger/input: any newly uploaded puzzle submitted to the solver.
• Observable result: the pipeline processes the uploaded puzzle's own pixels — segmenting, matching, placing, and verifying fragments — and the run's log lines, stage counts, and solution image differ according to the puzzle supplied.
• Access state: no access requirement.
• Failure/recovery: if the pipeline cannot produce a solution for a given puzzle, the run fails with the failing stage and reason stated rather than falling back to a canned result.
• Continuation: the operator compares the produced solution against the original upload, or uploads a different puzzle.

FR-4 — Watch the designed spider perform the solving work (explicit) As a Puzzle Solver Operator, I should watch the designed spider and its visual environment perform the solving work, so that I can see the process happening rather than only its outcome.

• Trigger/input: an active solve run.
• Observable result: the spider steps along the web in sync with real pipeline stages, threads connect fragment to fragment as matches are found, and the flow's color temperature shifts with confidence.
• Access state: no access requirement.
• Failure/recovery: if the run fails, the spider halts at the failing stage with the web left in its partial state rather than continuing to animate.
• Continuation: the operator reads the terminal log or proceeds to the solution result.

FR-5 — Read a detailed terminal log of the solving process (explicit) As a Puzzle Solver Operator, I should read a detailed terminal/console log showing the step-by-step solving process, so that I can follow exactly what the solver did.

• Trigger/input: an active or completed solve run.
• Observable result: timestamped lines are emitted as the solver produces them — stage transitions, per-stage counts, match results, and elapsed times — with the currently executing line highlighted.
• Access state: no access requirement.
• Failure/recovery: if the run fails, the failing line is present in the log with its reason, and the log remains readable.
• Continuation: the operator scrolls back through earlier lines, or proceeds to the solution result.

FR-6 — Keep the spider animation and terminal log available during the solve (required_inference) As a Puzzle Solver Operator, I should keep the spider animation and the terminal log available while the solve is in progress, so that I can observe the work continuously from start to finish.

• Trigger/input: a running solve.
• Observable result: both the spider view and the log remain present and updating for the duration of the run, and neither replaces the other.
• Access state: no access requirement.
• Failure/recovery: if the run fails, both remain present showing the halted state and the failing log line.
• Continuation: the operator proceeds to the solution result on completion, or starts a new run.

FR-7 — Compare the generated result with the original input image (required_inference) As a Puzzle Solver Operator, I should see the generated solved image alongside the original uploaded puzzle, so that I can judge whether the solution matches the expected solved result.

• Trigger/input: a completed solve run.
• Observable result: the original puzzle and the solved image are presented together with run metadata — fragment count, match confidence, and elapsed time.
• Access state: no access requirement.
• Failure/recovery: if the solved image cannot be retrieved, the reason is stated and the completed run's log remains reachable.
• Continuation: the operator starts a new solve with a different puzzle.

4. User Personas

Puzzle Solver Operator

Product context. The operator is technically literate and treats laba-laba as an instrument rather than a service. They arrive with a puzzle image of their own — a jigsaw reconstruction, a scrambled-tile puzzle, or a sliding puzzle — and an expectation of what the solved picture should look like. They are not looking for a friendly assistant; they are looking for a real computation they can watch and audit.

Primary goal. To upload their own puzzle and obtain a genuine solved image that they can compare against the expected solved result, while observing the process that produced it.

Distinct accepted responsibilities.

• Providing the puzzle image that the solve will operate on.
• Starting the solve and deciding when to cancel or restart it.
• Watching the spider perform the work and reading the terminal log to follow the actual pipeline stages.
• Judging the produced solution against the original upload and the expected solved image.
• Repeatedly uploading new puzzles, because the product's value depends on it working for puzzles other than the first one.

Relevant inputs and decisions. The puzzle image file; the decision to submit, cancel, or restart a run; the decision of whether the produced solution is acceptable; the decision to try a different puzzle.

Interactions with other accepted participants. The operator's only counterpart is the solver backend and its computer-vision pipeline, which is a system actor rather than a persona. The operator initiates every run and receives every result; there is no other human participant in this product.

Observable success. The operator sees a solved image that corresponds to the expected solved picture, produced from their own upload, with a terminal log whose lines reflect the actual stages and counts of that run — and the same holds when they upload a different puzzle.

What makes this role distinct. The operator is simultaneously the input provider, the observer, and the judge. Their work is not to configure or administer anything; it is to supply a puzzle, watch a real process unfold, and evaluate its output. That combination — supplying the data, watching the computation, and adjudicating the result — is the whole of the role.

5. Core User Flows

Flow 1 — Solve an uploaded puzzle and judge the result

1. The Puzzle Solver Operator arrives at Landing. The generative web drifts on the near-black canvas, the wordmark and live status line are visible, and the headline reads "Upload a puzzle. Watch the spider solve it."
2. The operator selects the primary upload action and moves to Upload Puzzle.
3. On Upload Puzzle, the operator chooses a puzzle image file. The image is read and previewed with its filename and dimensions, and the submit action becomes available.
4. The operator submits the puzzle and arrives at Solve. A run is created; its status moves from queued to running, and the current pipeline stage and elapsed time are shown.
5. While the run proceeds, the operator watches Spider Animation: the web is seeded from the uploaded puzzle's edge map and dominant colors, and the spider steps along it in sync with each real pipeline stage — segment, match, place, verify — with threads connecting fragment to fragment as matches are found.
6. Simultaneously, the operator reads Terminal Log: timestamped lines are emitted as the solver produces them, with per-stage counts and elapsed times, and the currently executing line is highlighted. The operator can scroll back through earlier lines without losing the live tail.
7. When the run completes, the operator proceeds to Solution Result. The original puzzle and the generated solved image are presented together, with a metadata strip beneath each showing fragment count, match confidence, and elapsed time.
8. The operator compares the solved image against the expected solved picture and judges the result.

Failure and recovery. If the run fails at any stage, the failing stage is identified on Solve, the spider halts at that stage with the web left in its partial state, and the failing line with its reason appears in Terminal Log. The operator can start a new run on the same puzzle or a different one without losing the failure information.

Continuation. The operator either accepts the result or starts a new solve.

Flow 2 — Solve a different puzzle to confirm the solver is real

1. From Solution Result, the operator starts a new solve.
2. The operator returns to Upload Puzzle and selects a different puzzle image — a different puzzle type or a different picture entirely.
3. The operator submits the new puzzle and arrives at Solve.
4. On Spider Animation, the web is re-seeded from the new puzzle's own edge map and dominant colors, so the scene is visibly different from the previous run, and the spider steps through the new run's stages.
5. On Terminal Log, the new run's lines reflect the new puzzle's actual stage counts, match results, and elapsed times, while the previous run's log remains available for reading.
6. On completion, the operator proceeds to Solution Result and compares the new solved image against the new original upload.

Failure and recovery. If the new puzzle cannot be solved, the run fails with the failing stage and reason stated, and the operator can try yet another puzzle.

Continuation. The operator repeats this flow for as many puzzles as they wish to test.

Flow 3 — Cancel an in-progress solve

1. On Solve, with a run in progress, the operator decides the current puzzle is not the one they want to solve.
2. The operator cancels the run.
3. The run stops; Spider Animation halts at the stage reached and Terminal Log retains the lines emitted up to that point.
4. The operator returns to Upload Puzzle and selects a different puzzle, or starts a new run on the same one.

Continuation. The operator proceeds with a new run.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. The muse is Refik Anadol: data made physical, a spider that weaves the solution out of the puzzle's own pixels. The headline register is a live instrument performing computation — between a laboratory readout and an art installation.

Palette (dark mode)

The generative web is drawn in a luminous multi-hue flow from teal through violet to warm amber, derived from the uploaded puzzle's own dominant colors, so the hero's palette changes per puzzle. #7BE0C8 is the fixed primary for interactive elements. #FF7A45 is the single hot accent, reserved for the active solve state — progress, the running cursor, the one live number. Body-size text never sits on the luminous flow; muted #6B7280 is for timestamps, inactive labels, and hairline rules only.

Typography

• Headings: Space Grotesk, 500–600 weight, tight tracking (−0.02em). Sentence case for display headlines; uppercase 11px/0.18em micro-labels for every section and terminal header.
• Body: IBM Plex Sans.
• Numerals in the terminal and status readouts: IBM Plex Mono, for a tabular, instrument-like cadence.
• Scale (1.25 modular): display 56px mobile → 96px desktop (clamp); h1 40/64; h2 28/40; h3 20/24; body 16/17; micro-label 11/12 uppercase; terminal 13/14 mono.
• Line-height: 1.05 for display, 1.6 for body, 1.5 for terminal.

Shape language. Full-bleed generative canvas with soft organic curves; the web is drawn as continuous bezier threads, never segmented. Panels are rectangular with 2px corners and 1px hairline borders at low opacity — the UI is a thin instrument overlay on the flow, not a set of rounded cards. Controls are pill-shaped only where they are primary actions; everything else is a sharp rectangle. No drop shadows, no glassmorphism blur on main panels; depth comes from layered opacity and the web's own parallax.

Layout. Single-column, museum-like: a full-viewport generative hero at the top with a minimal overlay (wordmark left, one-line status right, primary CTA bottom-left), then generous vertical spacing before the workflow sections. The solve page is a split: the spider canvas occupies ~62% on desktop and the terminal log ~38%, stacked on mobile with the canvas first and the terminal scrollable beneath. The result page is a two-up comparison (original puzzle left, solved image right) on desktop, stacked on mobile, with a thin ruled metadata strip beneath each image. All content sits inside a 1280px max-width container with 24px gutters at 375px and 48px at 1280px.

Imagery. No stock photography, no 3D product renders, no clip art. The only imagery is generative and derived from the operator's own uploaded puzzle: the web is a particle-and-thread field seeded by the puzzle's edge map and color histogram, and the solved output is the operator's actual reconstructed image. Decorative elements are the flow itself plus thin topographic contour lines and faint grid ticks in the background. The logo is a typographic wordmark "laba-laba" set in Space Grotesk with a small drawn spider glyph built from the same bezier thread language as the web.

Avoid. No blue/indigo primary or accent (#2563EB, #4F46E5, #6366F1 and neighbours). No Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins, or system-ui for headings or body. No gradient-blob hero and no grid of identical hover-lift cards. No glassmorphism panels with heavy backdrop blur over the flow. No canned or looping demo animation presented as a solve. No decorative 3D spider that moves independently of the actual solve events. No photography of people, no stock imagery, no clip art. No centered headline + subtext + button stack in the hero.

7. Signature Design Concept

The web is the puzzle. On the public entry, a full-bleed near-black canvas fills the first viewport. Dominating it is a slowly drifting generative web of luminous particles and bezier threads, seeded by a sample puzzle image and flowing in teal → violet → amber. A single oversized headline in Space Grotesk — 56px at 375px, 96px at 1280px — sits flush-left and low in the frame, spanning up to 9 columns, reading "Upload a puzzle. Watch the spider solve it." The primary CTA "Upload puzzle" is a solid teal pill pinned directly beneath the headline's baseline; a secondary text link "How the solver works" sits to its right. In the top-left corner, the laba-laba wordmark with its spider glyph; top-right, a live status line in IBM Plex Mono reading solver: idle · model: ready. No centered stack, no gradient blob, no subheadline paragraph — the web is the subject.

The concept carries through the whole product as one continuous generative surface. The same web that fills the hero contracts into a horizontal band behind each section heading on scroll, so the page reads as a single surface rather than a sequence of cards. On the solve page, the web is re-seeded from the operator's own uploaded puzzle — its edge map and dominant colors determine the thread paths and the flow's hue range — so every puzzle produces a visibly different hero and solve scene. The spider is not a mascot sprite but a live agent: it steps along the web in sync with real solver pipeline events (segment, match, place, verify), and each placed fragment sends a visible thread from the fragment to its solved position. The terminal log is a real instrument readout — monospace, timestamped, with the currently-executing line highlighted in #FF7A45 — typing out lines as the solver actually emits them, including real elapsed times and real per-stage counts. The result page is a two-up comparison with a thin ruled metadata strip beneath each image (fragment count, match confidence, elapsed ms), styled like a museum label rather than a dashboard card.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: cinematic Hero Dimensionality: webgl

Landing Hero Motion Brief

• Focal subject: a slowly drifting generative web of luminous particles and bezier threads, seeded by a sample puzzle image, flowing in teal → violet → amber across a near-black canvas.
• Input → transformation → outcome thesis: the puzzle's own pixels are the input; the web's thread paths and hue range are derived from that image's edge map and dominant colors; the outcome is a living field that visibly belongs to the puzzle rather than to a template. When the operator uploads their own puzzle, the same derivation re-seeds the web from their image, so the hero they see on the solve page is made of their puzzle.
• Motion vocabulary: continuous slow generative flow as the base layer at all times — the web drifts, threads re-draw, particle density breathes. During a real solve, motion is driven by actual solver events: the spider's legs step along the web in sync with each pipeline stage, threads connect fragment to fragment as matches are found, and the flow's color temperature shifts with confidence. The terminal types out real log lines as they are emitted, not on a timer. Scroll-linked morphing between hero and workflow sections.
• Composed first frame: near-black canvas; the web already drifting at rest; the wordmark and spider glyph top-left; the live status line top-right in IBM Plex Mono; the oversized headline flush-left and low, spanning up to 9 columns; the teal pill CTA directly beneath the headline's baseline with the secondary text link to its right.
• Reduced-motion state: the flow freezes to a static rendered frame, the spider holds a pose, and the terminal prints lines without the typing animation. All readable text and controls remain whole and fully visible.

Landing Hero 3D Scene Brief — DIRECTION-DERIVED

A real-time WebGL scene renders the web as a compact three-dimensional field: a particle-and-thread structure whose vertices are seeded from the sample puzzle's edge map and whose thread colors are sampled from its dominant-color histogram. The scene shows the product's defining state — a puzzle's own data rendered as a physical, luminous web that a spider agent traverses. Depth is expressed through layered opacity and parallax rather than heavy post-processing; the UI overlay stays a thin opaque instrument layer above the flow, never blurred into it. The scene is the hero subject, not decoration: when a real solve is running, the same scene is driven by actual solver events rather than an independent loop.

9. Non-Functional Requirements

NFR-1 — Real solving, not simulation (explicit; hard constraint) The solver must genuinely process each newly uploaded puzzle. It must not replay a fixed demo, and no canned or looping animation may be presented as a solve. Every motion on the solve page must be driven by real solver state. Rationale: the operator's stated requirement is that the product works when they upload other puzzles.

NFR-2 — Event-driven animation and logging (explicit) The spider's motion and the terminal's lines must be bound to real solver events — pipeline stages, match results, per-stage counts, and elapsed times — rather than to a timer or a pre-recorded sequence. Rationale: the operator must be able to watch and read a real process.

NFR-3 — Detailed, timestamped log (explicit) The terminal log must be detailed and step-by-step, with timestamps, stage transitions, per-stage counts, and elapsed times, and must remain readable after the run completes. Rationale: the operator explicitly requested a detailed terminal log of the work.

NFR-4 — Continuous availability of the observation surfaces during a run (required_inference) The spider animation and the terminal log must both remain available and updating for the duration of a run, and neither may replace the other. Rationale: the operator must be able to observe the work continuously from start to finish.

NFR-5 — Result comparison (required_inference) The generated solved image must be presented alongside the original uploaded puzzle so the operator can judge the result against the expected solved image. Rationale: the operator's stated goal is to obtain a result corresponding to the second, solved picture.

NFR-6 — Readable text and controls at every viewport (explicit direction constraint) Headlines, wordmarks, labels, numbers, card text, and controls must stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit, and no other element may cover any part of them. Imagery, decoration, and motion may be cropped, bled off an edge, rotated, overlapped, or cut as the direction asks, provided they cover no readable text or control. With prefers-reduced-motion, a usable static arrangement must be provided.

NFR-7 — Reduced-motion support (explicit direction constraint) Under prefers-reduced-motion, the flow freezes to a static rendered frame, the spider holds a pose, and the terminal prints lines without the typing animation, while all content remains usable.

10. Tech Stack

• Frontend: React, with a real-time WebGL/R3F hero and solve scene as required by the creative direction's webgl hero dimensionality.
• Backend: Python with FastAPI, hosting the puzzle-solving API and the computer-vision pipeline that performs segmentation, fragment matching, placement, and verification on the uploaded puzzle.
• Real-time transport: a streaming channel from the backend to the browser so that solver stage events and log lines reach the spider animation and terminal log as they are emitted.
• Storage: object/file storage for uploaded puzzle images and generated solved images, plus a record of each run's stage events and log lines so a completed run's log and result remain readable.
• Containerization: Docker and docker-compose for the frontend, backend, and storage services.

11. Assumptions and Constraints

Assumptions

• The operator supplies a puzzle image in a standard browser-readable image format.
• The puzzle is an image puzzle — a jigsaw reconstruction, scrambled-tile puzzle, or sliding puzzle — whose solved form is a single reconstructed image.
• The operator has a modern browser capable of WebGL.
• The backend has sufficient compute to run the computer-vision pipeline for a single uploaded puzzle at a time.

Constraints

• The solver must not be a simulation; it must genuinely solve newly uploaded puzzles rather than replaying a fixed demo. (explicit, binding)
• No canned or looping demo animation may be presented as a solve; every motion on the solve page must be driven by real solver state. (explicit, binding)
• No decorative 3D spider that moves independently of the actual solve events. (explicit, binding)
• No blue/indigo primary or accent (#2563EB, #4F46E5, #6366F1 and neighbours); the palette is teal, violet, and amber on near-black. (explicit, binding)
• No Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins, or system-ui for headings or body. (explicit, binding)
• No gradient-blob hero, no grid of identical hover-lift cards, no glassmorphism panels with heavy backdrop blur over the flow, no photography of people, no stock imagery, no clip art, and no centered headline + subtext + button stack in the hero. (explicit, binding)
• The generic indigo/blue-on-white SaaS template is forbidden for this project. (explicit, binding)
• The reference animation video was not supplied; it informs the spider's behavior and visual appearance as inspiration only and contributes no product names, copy, facts, or capabilities. (source boundary)

12. Glossary

• Puzzle image — the first, unsolved picture the operator uploads; the input to the solver.
• Solved image — the reconstructed picture the solver produces, corresponding to the expected second picture.
• Solve run — one execution of the solver on one submitted puzzle, with its own stages, log lines, elapsed time, and outcome.
• Pipeline stage — one step of the real solving process: segment, match, place, verify.
• Fragment — a piece of the puzzle identified and placed by the solver.
• Match confidence — the solver's confidence that a fragment has been matched to its correct position.
• Spider — the designed agent that traverses the generative web in sync with real solver events.
• Web — the generative particle-and-thread field seeded from the uploaded puzzle's edge map and dominant colors.
• Terminal log — the timestamped, monospace, step-by-step record of the solving process as emitted by the solver.
• Puzzle Solver Operator — the sole active human persona; the person who uploads puzzles, starts solves, observes the work, and judges the result.