wwizark.github.io

Imported from wwizark/wwizark.github.io (AGENTS.md). Install upstream with npx skills add wwizark/wwizark.github.io. Copyright stays with the author.

AGENTS.md — working guide for this repository

This file is the source of truth for how this website is built and the vocabulary we use to talk about it. Any agent (or person) making changes MUST:

1. Read this file first and follow its conventions.
2. Keep it updated — whenever we introduce a new concept, rename something, change a convention, or add a canvas/section, update the glossary and conventions here in the same change.

If something in the code contradicts this file, treat it as a bug in one of them and raise it rather than silently diverging.

Glossary

The front page (index.html) is a looping 1-D canvas ring. Learn these terms — the code and our conversations use them precisely.

Architecture rules

• Every canvas behaves identically. Tapping a neighbour's peeking marker/label pans to it. Tapping the centred canvas's own marker collapses/expands its logo (if scrolled, the first tap returns it to the top). Tapping the orbit ring collapses the current page too. Back and Escape go Home. Don't give one canvas a bespoke interaction — behaviour belongs to the engine.
• Scroll PACES collapse/expand. Beyond tapping, scroll drives expansion directly (applyTransitionScroll, not a fixed tween): in the bird-eye view scrolling down expands into the detail view; in the detail view at the top scrolling up collapses into the bird-eye view. The title reaches the dock in sync with the logo shrinking (see navDock). On idle / touch-end it snaps to the nearer end (snapExpansion). Content only scrolls in the full detail view (overflowY auto at expansion ≥ .999), so the transition owns the wheel/touch elsewhere. Works with wheel and touch. Detail scrolling: detail content owns native scrolling at all times: its position is never counteracted by a buffer transform after entry. The logo/title start docking from the first detail scroll and travel with that same scroll, preserving clearance without holding or consuming reading input. Clicking the logo/ring enters at scrollTop = 0. Only the true top (scrollTop ≤ 1) permits an upward gesture to begin collapsing; returning through the final pixels of detail content must fully enlarge the logo/title first. Collapsing resets scrollTop to 0.
• A locked canvas does not scroll. When a canvas's overflowY is hidden (e.g. the compact/shrunk Home logo), neither native scroll nor the marker wheel/touch forwarding may move it.
• Canvas scrollbars are hidden. The interactive Home, Photography, Work, and Notes scroll containers retain native wheel, trackpad, touch, and keyboard scrolling but do not display a scrollbar. A scrollbar appearing only on detail entry consumes viewport width on some systems and shifts all centred canvas geometry. Standalone Photography pages keep normal browser scrollbars.
• Detail-entry settle buffer. Scroll-paced expansion caps individual deltaY steps, keeps the content anchor stable while the title docks, waits through a transition settle buffer, commits meaningful partial entry to detail on idle, and announces when the detail view is ready.
• The engine is data-driven. All layout, panning, docking, visibility, and wiring is written once against CANVASES in app.js. Adding a canvas must not require new geometry maths.
• To add a canvas: (1) add a row to CANVASES with a kind; (2) insert its id into ORDER at the ring position you want; (3) add its <section> of content in index.html; (4) add its marker + title-entry elements; (5) append its selectors to the shared .work-* rules in styles.css; (6) add a link in nav.js's page map. No layout maths change.
• Keep pans smooth. Click navigation goes: scroll the current canvas to the top → shrink/fade it fully into the bird-eye view → pan → the destination arrives collapsed and stays in the nav view (finish() does not auto-expand; tap the logo/ring or scroll down to enter). Mid-pan the dock titles pan across with the markers, then settle under the new logo. The single continuous wallpaper translates via translate3d from live pos; canvas sections stay transparent and only their content opacity changes. Detail content has its own opacity track and stays hidden during pans. Never animate section left/width.
• Cursor pass-through. Markers AND titles forward wheel/touch to the active canvas (forwardScroll), so hovering either still scrolls the page.
• Scroll transform stability. Detail content keeps one stable compositor transform; native scroll events only schedule the shared renderer. Do not alternate transform functions or write a redundant transform in the scroll handler: frequent mobile scroll events make text visibly stutter.
• Touch direction locking. A shared viewport touch gesture uses an intentionally asymmetric axis lock: slightly dominant vertical movement locks quickly after TOUCH_VERTICAL_INTENT, while horizontal navigation requires the longer TOUCH_HORIZONTAL_INTENT and clear dominance set by TOUCH_HORIZONTAL_AXIS_RATIO. This keeps diagonal scrolling vertical unless the user makes an unmistakable left/right swipe. A deliberate horizontal swipe drives the continuous ring preview and may cross multiple ORDER slots. Touch uses its own, slightly longer TOUCH_SWIPE_DRAG_FRACTION so small diagonal corrections do not pull toward a neighbouring canvas; desktop sensitivity remains independent. Horizontal gestures are ignored while a return-to-top, expansion, or pan is active; uncertain gestures do not navigate. Locked horizontal gestures complete on a capture-phase touchend or touchcancel at the window boundary, preserve the final changed-touch coordinate, and apply a short capped velocity projection so releasing at or just beyond a screen edge retains natural follow-through.
• Mobile vertical collapse. A downward finger pull at the true top of a fully expanded canvas is owned by the transition engine and collapses the detail view continuously into the bird-eye view. This takes priority over native pull-to-refresh inside the canvas viewport. The centred marker and orbit ring remain alternative collapse controls, and desktop upward wheel input retains the same scroll-paced collapse.
• Desktop/mobile parity. Desktop horizontal wheel/trackpad input and mobile horizontal touch input use the same continuous ring preview, handoff, dock, and settle behavior. The detail-to-dock handoff is distance-driven by the live gesture, so the rendered state stays attached to the finger without waiting for a timer or replaying queued input. A gesture begins from the current rendered logo/title positions and must finish that handoff before ring panning starts. Detail text has its own opacity track as well as the canvas fade, following continuous expansion on entry and exit rather than appearing in a final frame. Its visibility may switch only at a near-zero opacity threshold, never at the expanded endpoint. Incomplete gestures reverse the same visual path: the marker/title return from the dock, the saved reading position restores, and detail content fades back in proportion to the returning expansion; it remains unavailable to interaction until fully restored. Vertical content scrolling preserves the current reading position; it does not reset to the top merely because a touch gesture begins.
• Desktop horizontal navigation. Horizontal trackpad/wheel input (deltaX, or Shift+wheel) drives the same live swipe preview as touch and settles after wheel input pauses. Ordinary vertical wheel input keeps scrolling and Ctrl+wheel remains available for browser zoom.
• Continuous desktop navigation. Horizontal wheel input drives one continuous ring preview across as many ring slots as the gesture covers. When wheel input pauses, the nearest canvas slot is selected and the page settles there; input is not queued for later pans.
• Swipe handoff and reading position. A horizontal swipe progressively fades and collapses the outgoing detail view during the drag, then advances the ring toward its destination in the latter part of the same gesture. Release/idle keeps the 30/70 behavior: a gesture reaching 70% commits, while a short/cancelled gesture rolls back. Continuous travel may span any number of complete loops; all destination offsets use positive modulo normalization so large negative offsets never resolve to an invalid slot and roll back. The engine remembers a canvas's scroll position when leaving by swipe and restores it only when that canvas is expanded again; a fresh canvas enters at the true top (scrollTop = 0).
• Input-driven swipe handoff. Ring travel begins with the first locked horizontal movement. The outgoing detail view collapses concurrently and reaches the dock by SWIPE_HANDOFF_FRACTION; there is no dead zone, time-based handoff, or replay queue. Touch movement is coalesced to the latest sample once per animation frame, viewport metrics stay cached outside the gesture hot path, and expensive backdrop filters / watermark animation pause during the swipe.
• Collapsed content is unavailable. A canvas content region is inert and aria-hidden="true" unless its canvas is current, settled, and fully expanded. This keeps hidden cards and links out of keyboard focus and assistive-technology navigation during bird-eye view and pans.
• It's a loop. Panning always takes the shortest way around the ring, so Notes → Photography wraps. Each canvas is placed by ringRel (its signed distance from pos): centre = the full open page, ±1 neighbours peek as logos, far side hidden. Content is hidden during a pan and only the centred canvas's content becomes available in the settled detail view.

Code conventions

• Site identity: The portfolio is branded wizark's Portfolio; Photography remains a section within it.
• No commits or pushes unless the user explicitly asks.
• Cache-busting: every HTML file loads CSS/JS with ?v=N. When you edit styles.css, app.js, or nav.js, bump N in all HTML files that load it (root index.html + everything in photography/).
• Colours: the current UI palette is a web approximation of Pantone 2026 Cloud Dancer / Powdered Pastels, with darker derived UI accents for accessible contrast. One continuous tie-dye wallpaper has a dominant field for each canvas: Photography = gray, Home = blue, Work = yellow, Notes = green. Each field has its own vertical centre, and the wallpaper translates with pos. The orbit dot for each canvas uses the same family in a darker contrast-safe value. Use the variables in :root (--ink, --paper, --muted, --line, --accent, --logo-line, --powder-*, --tone-*, --dot-*). Do not hard-code new hex values; add a variable if you need a new colour.
• Fonts: use the font CSS variables (--font-serif, --font-sans). Do not introduce new font-family literals. See "Typography" below.
• CSS structure: styles.css is grouped by /* ===== Section ===== */ headers. Some selectors are declared in layered "refinements"; those are commented — keep the ordering, don't merge across media queries.
• JavaScript style: one statement per line; name magic numbers as constants at the top of the IIFE; keep related interaction state in a named object; keep the hot path (placeView) allocation-light. Shared render helpers own content availability (opacity, visibility, scrolling, pointer events, inert, and aria-hidden), and repeated style/attribute writes are cached. Touch and desktop gestures may normalize input differently, but both feed the same swipe-travel renderer and settle logic.

Typography

• Family: self-hosted Montebello (WOFF files in assets/fonts/, declared via @font-face at the top of styles.css). Montebello Sans (--font-sans) carries body copy, captions, controls, and metadata. Montebello Rounded (--font-rounded; --font-serif points at it) is the display face for canvas labels, logos, major headings, watermarks, and photography titles. This soft heading / clear copy pairing belongs to the Cloud Dancer powdered-pastel design. Use the variables — never a raw font-family literal.
• The zip also shipped Montebello Script and Script-Textured; those were removed (unused).
• Fonts are WOFF only (no WOFF2 supplied) and load with font-display:swap. Montebello Sans is a display face — if body text / small captions read poorly, that's the signal to pick a text face for --font-sans.

Accessibility & resilience

• Markers are real <button>s with aria-labels that update on state change.
• prefers-reduced-motion is honoured (animations become instant snaps).
• A <noscript> fallback links to the Photography section for JS-off visitors.
• Keep inert on inactive canvases so assistive tech only sees the active one.

Assets & image pipeline

• Originals live in assets/<section>/originals/ locally only — they are gitignored (not committed/served). Keep them on your machine as the source for ./scripts/build-images.sh, which regenerates the derivatives that ship.
• Photography stills → assets/photography/; camera/home art → assets/camera/.
• <img> uses <picture> with an AVIF <source> + JPEG fallback, srcset (two widths) + sizes, and decoding="async".

Folder map

index.html            front page (the canvas engine)
styles.css  app.js  nav.js
photography/           the photography site (index + photo-01..04)
assets/camera/ assets/photography/   (+ originals/ subfolders)
scripts/build-images.sh