This file explains how to work on Compactor with the same product judgment, communication style, and engineering standards established during the workspace upgrade. Read it before making a broad UI, export, processing, or documentation change.
Compactor is a private, browser-first file workspace. It should feel like a focused native editor: upload files, configure a clear operation, watch an honest local process, review the result, and export a file that is actually usable.
The product should never pretend to support a format, processing mode, file size, preview, or quality guarantee that the browser implementation cannot deliver.
The user often writes quickly, informally, and iteratively. Interpret the intent, not the spelling.
- “Optimize,” “make it stronger,” or “polish” means improve the whole interaction surface around the named issue: hierarchy, spacing, overflow, responsive behavior, states, accessibility, labels, and the real processing path.
- “Check all features” means inspect the control-to-export path, not only whether the control renders. Look for misleading options, unsupported formats, state mismatches, incorrect filenames/MIME types, and preview/export divergence.
- “Like Premiere Pro” means a professional editor hierarchy: preview gets primary space; timeline/controls are compact and spatially stable; panels use the remaining viewport intelligently; dense actions remain discoverable.
- “Same as [another workspace]” means reuse the established component geometry and interaction patterns rather than making a visually similar new version.
- Screenshots are bug reports and design specifications. Match the concrete issue shown, then account for the larger state it implies (long queues, portrait media, processing, results, mobile, and errors).
- Do not over-question straightforward product requests. Make a safe, scoped interpretation, implement it, and clearly state the assumption only if it materially changes behavior.
-
Reliability beats feature count.
- Remove, disable, or honestly label an option when the browser cannot produce a correct result.
- A downloadable file is not proof of a successful operation. Verify its MIME type, bytes, readability, size, and representative visual output where relevant.
-
Keep processing local where it is credible.
- Explain browser memory and codec limits instead of masking failures behind blank processing screens.
- Use browser-safe limits for heavyweight media. Reject impossible inputs before beginning a job.
- Do not add browser-only features such as a video merger unless the memory/codec/error path is designed and tested first.
-
The loaded file is the main object.
- Empty states can be calm and centered.
- Loaded states should become a workspace: persistent identity, contextual tools, large preview, honest progress, and results in context.
- Do not trap the preview in a decorative card that crops it or gives it less space than unused background.
-
Every state needs honest language.
- Never show a per-file percentage when the underlying API only reports completion.
- Prefer
Encodingplus a real batch percentage over a permanent fake0%. - A disabled action must say why it is unavailable.
-
Use progressive disclosure.
- Common actions first; advanced controls are available without overwhelming the initial view.
- Remove duplicate controls, explanatory cards, and modes once their purpose is already represented in the active workspace.
- Use the shared tool header and workspace shell when a file session is active.
- Preserve the project’s viewport-frame geometry. Check final CSS overrides before changing layout; later overrides in
src/index.cssandsrc/styles/workbench.csscan defeat an apparently correct selector. - Desktop workspaces fill the available application surface. Mobile must deliberately stack rather than accidentally inherit desktop dimensions.
- Protect every grid/flex child that can shrink with
min-width: 0andmin-height: 0. - Keep scroll ownership explicit. One region should own each axis; avoid nested raw scrollbars and accidental page scrolling.
- The right queue rail is intentionally separate from the file identity bar. The header bar identifies the active file; the rail manages the queue.
- Keep the add-image tile at the top, the same size as a thumbnail, outside the scrolling thumbnail list. The thumbnails alone scroll vertically on desktop.
- Start image previews at 80% zoom so the image and queue rail fit together. The checkerboard must span the complete preview viewport with no unexplained gap at the queue boundary.
- A long queue must not create a bottom dead zone, horizontal scrollbar, or hidden add action.
- Image canvas processing supports JPEG, PNG, and WebP outputs. Do not expose GIF output/input in Image Optimizer: canvas cannot faithfully recreate animated GIFs.
- Normalize historical
originalsettings topreserve; both must resolve to the input MIME type before the supported-output fallback is applied. - The metadata switch must not imply that EXIF can be preserved through a canvas re-encode. Canvas output strips metadata as a consequence of processing.
- Compression presets are product-facing promises. Their quality values and any target-size/resolution behavior must be traceable to the encoder options.
- Preview filters may use CSS for responsiveness, but exported filters use canvas algorithms. Do not claim pixel-perfect preview parity without rendered output comparison.
- The user-facing product name is Video Studio, not merely “Compressor,” because it now contains compression, format conversion, audio extraction, trimming, and GIF output.
- Default into the Compress settings. Never leave Audio extraction selected when opening a normal video workflow.
- Audio extraction belongs inside the video workflow as an explicit toggle. When enabled, visually dim or disable incompatible video controls and say that only audio will download.
- GIF is an output format inside Format, not a separate top-level application mode.
- Use FFmpeg WASM for exports. Do not revive the MediaRecorder/captureStream “Native” path: it caused dropped frames, torn/distorted audio, and timestamp issues during real-time recording.
- The preview must preserve the full video edges with
object-fit: contain; account for portrait video and dynamically reduce preview height when the timeline opens. - Place the trimmer below the preview. Allow the panel to grow for multi-segment controls without covering the preview or causing arbitrary gaps.
- Validate FFmpeg output before presenting results: delete stale output, reject non-zero exit codes, and reject missing/empty output bytes.
- Use browser-device-aware media limits before
fetchFile. A large file that cannot be read by WASM must produce a clear in-workspace error, never a blank page.
- The preview must use the real visual operation, especially Classic Halftone Dot Art—not a CSS approximation.
- PDF accuracy is a higher bar than successful generation. Preview and export should eventually use a canonical processed master image/coordinate system.
- Check portrait and landscape, crop marks, tile order, page count, seams, print margins, and style-specific output. A build passing does not prove printable parity.
- Prefer small, reusable components with readable class names. Do not turn a local layout correction into an abstract framework.
- Keep processing engines in
src/utils; keep UI state and user messaging in the page/components. - Derive simple values during render instead of duplicating them in state. Example: derive
batchProgressfrom current index and completed work once, then use it in all processing surfaces. - Use functional state updates when updates depend on prior state.
- Revoke every object URL when a file/result is removed, reset, or unmounted.
- Use direct imports rather than broad barrel imports where practical.
- Do not put expensive synchronous image/video work directly in high-frequency React render paths.
- Do not advertise input formats or output extensions that are only superficially accepted. The output data signature, filename extension, and UI label must agree.
- Avoid forceful
!importantadditions unless working within the existing workspace override layer and there is a documented selector conflict. Prefer a precise final selector. - Preserve user changes in a dirty worktree. Do not reset, checkout, or mass-format unrelated files.
Before calling an export feature reliable, trace this exact chain:
- The UI exposes the setting.
- The setting reaches the processing function.
- The processing function supports it for this input type.
- The generated bytes are non-empty and use the claimed format.
- The filename extension matches the actual output.
- The downloaded result re-opens correctly.
- Dimensions, transparency, duration, audio, trim range, visual effect, and size align with the selected settings.
Use representative samples, not only one easy file:
- JPEG photo, transparent PNG, WebP, large/detailed image, portrait image.
- Image resize, crop, rotation, mirror, grayscale, contrast, B&W, halftone, watermark positions, all presets, and target size mode.
- Video landscape/portrait, short/long duration, audio/no audio, trim/split, normal video, audio-only, and GIF output.
- Poster light/dark/color/monochrome/halftone, portrait/landscape, multi-page layouts.
When browser automation is unavailable, do not claim visual or end-to-end verification. State exactly what was checked by lint/tests/build and what requires a manual exported-file comparison.
Use Windows PowerShell and npm.cmd (not npm, because PowerShell may block npm.ps1).
npm.cmd run lint
npm.cmd test
npm.cmd run build
git diff --check- Use focused tests while iterating, then run the complete test suite for a broad feature pass.
git diff --checkcan reveal pre-existing whitespace in a dirty tree. Do not rewrite unrelated user files just to silence it; report the scope clearly.- jsdom may log canvas
getContextlimitations while tests pass. This is not visual-output proof. - Browser automation should be used for actual interaction/visual checks when available. If the local automation CLI is unavailable, say so plainly.
- Keep
plans/README.mdand the relevant guide indocs/current after meaningful changes. - Record: what changed, current constraints, non-ideal shortcuts, known issues, and the difference between automated validation and visual/output-fidelity evidence.
- Use plain, human-readable language. The roadmap is a product ledger, not just a technical changelog.
- Do not call a capability “perfect,” “native,” “lossless,” or “accurate” unless the implementation and validation meet that claim.
- Start with the outcome, not a list of internal steps.
- While working, send short commentary updates that explain the active assumption or finding.
- In the final response, be concise and concrete: what changed, what was verified, and the remaining real limitation if any.
- Match the user’s direct, collaborative tone. Be decisive when evidence supports a fix; do not use empty praise or vague assurances.
- Use local file links when handing off important edits.
- Never make destructive repository changes without explicit authorization.
- Do not publish, commit, push, install dependencies, or change external services unless requested.
- Do not invent cloud/server processing to bypass a browser limitation. Explain the needed authority, infrastructure, or user choice first.
- Keep new work within the user’s request, but take adjacent low-risk fixes when they are necessary for the requested experience to work correctly.
- Browser image canvas export cannot faithfully output animated GIFs.
- Browser FFmpeg/WASM has finite memory and codec limits; large uploads must be rejected before processing instead of failing blankly.
- Rasterbator preview/PDF visual parity needs real rendered-output comparison, especially at tile seams.
- CSS filter previews and canvas export filters are not automatically pixel-identical.
- Automated lint, tests, and builds establish code health; they do not replace manual visual/export verification.