signatur 0.1.0 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,307 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+*
+
+### Changed
+
+*
+
+### Fixed
+
+*
+
+## [1.0.0] - 2026-05-21
+
+### Added
+
+* Optional `sku` field on the profile schema that, when present, is rendered as quiet monospaced metadata between the product name and the dimension pill on every welcome catalog card so operators can identify the matching stock keeping unit at a glance; the field is validated as an optional string in `lib/util/profile.js` and documented in [docs/profile-spec.md](docs/profile-spec.md) ([#30](https://github.com/hivesolutions/signatur/issues/30))
+* `button-tiny` size variant on the `.button` component mirroring the existing `button-small` shape at a smaller 28×28 scale with a 9px label, so very small affordances like the `Instructions` link on the viewport options panel can use the established button language instead of a one off styled link
+* iOS Safari touch responsiveness pass: `touch-action: manipulation` is applied at the body level and reinforced on every interactive surface (`.button`, `.option-chip`, `.option-chip-toggle`, `.slider-preset`, `.settings-tab`, `.emojis-tab`, keyboard `.char`, `.catalog-card`, `.fonts-container > .font`) so the first tap registers immediately without the legacy hover stall; the viewport meta is locked at `maximum-scale=1, user-scalable=no` so neither double tap nor pinch can zoom the page; the body also sets `-webkit-tap-highlight-color` to transparent so taps no longer flash the iOS gray overlay
+* Container level fallback caret click handler on the viewer container that resolves taps landing outside any character span to the nearest character, working around iOS Safari's touch hit-test that occasionally promotes the click target to the closest interactive ancestor when the tap falls in the few pixel gap before or after a span
+* Entrance animation for the viewport preview that fades the engraving surface in with a subtle three pixel translate up using a `cubic-bezier(0.22, 1.2, 0.36, 1)` ease so the moment a profile becomes active feels deliberate rather than abrupt; runs once per `.profile-active` activation
+* New slider control on the viewport options panel that replaces the legacy native range plus number input plus auto checkbox triplet with a preset chip row above a visually enlarged slider; the chips share the existing option chip language (`S` / `M` / `L` / `XL` / `Auto` for the font size, `1x` / `2x` / `3x` for the zoom) and turn the slider into a quick destination picker without losing the fine grained scrubbing affordance, while a tooltip bubble floats above the thumb showing the live value with the profile unit only while the user is actively dragging so the panel stays uncluttered when idle; the visual layer lives under a shared `.slider-field` / `.slider-presets` / `.slider-preset` / `.slider-track` / `.slider-range` / `.slider-bubble` / `.slider-dragging` class set so both the font size and the zoom containers compose the same look through class composition (`viewport-options-field slider-field font-size-container`), the bubble positioning is owned by a single `refreshSliderBubble(range, bubble, formatter)` helper that each container wraps with its own unit suffix, and the existing `font-size-input` / `font-size-mode` hidden form controls are kept verbatim so the URL persistence, the modal specs and every downstream consumer keep working without any change to their code; the legacy `.zoom-value` static label is removed in favor of the live bubble
+* Separate Colony Print configuration for the engraving job and the receipt printing so a single Signatur install can drive an engraver and a receipt printer that live on different nodes without any name collision; the colony print base URL and the secret key remain shared between both scenarios, while `engrave_node` / `engrave_printer` (with legacy `node` / `printer` fallback) and `receipt_node` / `receipt_printer` (same legacy fallback) are read independently by the engrave and the receipt code paths
+* `ENGRAVE_NODE` and `ENGRAVE_PRINTER` server side environment variables that feed the `data-node` / `data-printer` attributes rendered onto the viewport `Engrave` button so deployments that do not configure the browser side `localStorage` still pick up a sensible default; both fall back to `PRINT_NODE` / `PRINT_PRINTER` so existing single printer installs keep working
+* Tabbed `/settings` screen with a `General` tab for the existing preferences (theme, locale, fullscreen, home, show options, viewport mode, version) and a dedicated `Printing` tab that exposes the Colony Print configuration; each printing entry renders as a card with the label on top and two pill-shaped sub lines underneath, a disabled `Base` pill showing the server side `lib.conf` value and an editable `Effective` input prefilled with the resolved value so operators can override any entry inline; the form submit handler persists each input to its matching `localStorage` key (or removes it when blank so the base takes over again)
+* Localized data attributes on the confirmation modal so each viewport locale template owns its own label set (`Texto`, `Letra`, `Perfil`, `Área`, `Tam. Letra`, `Margens`, `Espaç. Extra`, `Área Final`, `Nó`, `Suporte` for `pt_pt`); the modal also renders a friendly subtitle (`Ready to engrave on …` / `Pronto para gravar em …`), pill chips for each multifont text segment, an amber/lavender empty hint that blocks the primary action with the `Engrave` button greyed out when no text was entered, and a `Dry run` / `Simulação` chip toggle that replaces the legacy checkbox; the secondary `Cancel` / `Cancelar` button adopts the ghost variant so the engrave action stays visually dominant
+* `data-message-no-printer` / `data-message-pantograph` data attributes on the viewport body so the engrave guard error messages are owned by each locale template instead of being hardcoded; the missing printer message now points the user to `/settings` and is required whenever any of `url`, `node`, `printer` or `key` is unset
+* `Settings` / `Definições` link on both gateway action bars so the configuration screen is reachable from the gateway in either locale (the EN gateway previously exposed a `Configure` button that opened the legacy modal, while the PT gateway had no entry point at all)
+* QWERTY layout on the on screen text keyboard with `<br>` row separators that respect the existing `.keyboard-container > .char` styling, an iOS style utility row at the bottom (`123` mode toggle, spacebar, return) and a dedicated `Shift`/`Backspace` placement at the edges of the Z row; a letters/symbols toggle mirrors the existing `.lowercase` casing toggle pattern by adding a `.symbols` class on the container that swaps a 3 row symbols layout (10/10/5) in place of the letters rows, with a separate backspace inside the symbols section so it remains reachable when the Z row is hidden
+* Themed tabs above each emoji keyboard that split the large flat key list into 5 categories (`Symbols`/`Símbolos`, `Nature`/`Natureza`, `People`/`Pessoas`, `Pop`, `Phrases`/`Frases`) for the Cool Emojis font and 4 categories (`Symbols`, `Nature`, `People`, `Pop`) for the Cool Emojis Pantograph font; tabs are wired through the existing keyboard plugin via a `data-active` attribute on the container plus `data-category` on each `.char`, the visibility rules live in plugin CSS so the active category is the only one rendered, and the container width is constrained to 10 emojis per row with the utility keys (`⌫`, `⎵`, `↵`) placed on a dedicated row via a `<br>` separator so they never mingle with the glyph grid
+* Mobile viewport block under 430px wide that overlays every page with a centered notice telling the user that Signatur is not designed for mobile devices, fully inert so the underlying UI cannot be interacted with; implemented as a CSS-only `body::before` pseudo-element driven by the existing `<html lang="…">` attribute so the English and Portuguese copies switch automatically with no per-page markup edits, with `ldj` theme tints picked up from the body class
+* `Version` field on `/settings` rendered as a soft-fill pill that replaces the legacy per-page `welcome-version` footer (removed from welcome, profile manager and gateway views) so the application version lives in a single, predictable place
+* Preview mode on `/viewport` triggered by a new header icon button (Ionicons `expand-outline`) and reversible via the Esc key or a floating exit hint: layers a layered fade-out of the chrome (header, profile info, inspirations panel, viewport options, font row, keyboards) with `cubic-bezier(0.16, 1, 0.3, 1)` easing while compounding the current zoom by 1.5x for a cinematic centered preview; the underlying toggle states are snapshotted on enter and restored on exit through their existing change handlers, with the `restoring` flag (wrapped in `try`/`finally`) suppressing URL writes so the temporary off state never persists
+* `cookie-session` based session middleware that replaces the in-memory `express-session` store with a signed cookie payload, so UI preferences (theme, locale, last text, profile, viewport mode) survive Node restarts without any server side storage; the secret is hardcoded because the session only carries non sensitive UI state
+* Modernized native keyboards with a soft entry/exit motion: `keyboard-enter` keyframe (0.5s out-expo) plays automatically when a keyboard becomes visible, `keyboard-leaving` class (0.25s in-quint) plays the reverse before `display: none` so font switches go through a sequenced leave-then-enter handoff instead of snapping
+* Profile JSON / Inspirations JSON dropdown selector on `/profiles/manager` that swaps the two textareas in place to reclaim vertical space, and auto routes the user to the failing editor when validation or save errors come back with `profile:` / `inspirations:` prefixes
+* Profile manager screen at `/profiles/manager` with inline JSON editors for the profile and inspirations payloads, validated server side via the existing profile and inspirations schemas before being written to `static/profiles/` under the validated profile id
+* Optional `Load from file` picker next to each JSON editor that reads the selected file as text into the editor textarea so the editor remains the source of truth on submit
+* Reference panel on the upload screen with a profile dropdown that previews the picked profile (image, name, key metadata) and a `Use as starting point` button that loads its profile JSON (and matching inspirations when present) into the editor
+* `Validate` button on the upload screen that posts the current editor contents to a new `/profiles/validate` endpoint and surfaces the server returned errors inline
+* `Preview` tab on the upload reference pane that renders a live summary of the editor payload (image, name, key metadata) using the freshly picked background image as the preview surface, debounced on every input
+* `Edit this profile` action on the upload reference pane that opens the selected profile in the editor and flips the form into edit mode so the next save overwrites the existing files via `POST /profiles` with an `edit_target` field, including support for renaming the profile id during edit (the old assets are removed after the new ones are written)
+* Mode aware validation that lets create mode reject duplicate ids while edit mode accepts in place updates and renames, refusing only when the edited profile no longer exists on disk or when a rename would clobber another profile, with the same rules applied by `POST /profiles/validate` so the `Validate` button surfaces every error that would block a save
+* AJAX save flow on the profile manager that posts the form via `fetch`, returns JSON from `POST /profiles` instead of a redirect, refreshes the reference dropdown in place, surfaces success through the existing toast plugin, and switches the form into edit mode pointing at the freshly saved id so the user never loses the editor context
+* Dedicated background asset manager on the profile manager (new `Backgrounds` tab) backed by `GET /profiles/assets`, `POST /profiles/assets`, and `POST /profiles/assets/:filename/delete`, listing every PNG file under `static/profiles/` and offering inline upload and delete with confirmation modal so multiple variants can share the same asset
+* Per-asset download button on each background card that points at the public `/static/profiles/<filename>` URL with the native browser `download` attribute so individual PNG assets can be saved locally without leaving the manager
+* Profiles bundle export and restore on the profile manager (new `Export / Import` tab) backed by `GET /profiles/bundle` (streams a zip of every profile JSON, inspirations JSON, and PNG asset plus a `manifest.json` entry) and `POST /profiles/bundle` (wipes the profiles directory before unpacking the uploaded archive), with a confirmation modal guarding the destructive full replace semantics
+* Decoupled the PNG asset lifecycle from the profile lifecycle: the background picker has been removed from the profile editor, the profile JSON `background` and `variant.background` fields remain plain filename references, profile renames no longer rewrite or delete PNG files, and profile deletes leave PNG assets untouched
+* `Editing profile "<id>"` banner at the top of the upload form pane shown only while in edit mode, with an `Exit edit mode` link that reverts the hero, save button, and hidden target field back to the create state without reloading
+* `Delete` action on the upload reference pane that opens a confirmation modal and removes the profile assets via `POST /profiles/:id/delete` after the user confirms
+* `?edit=<id>` query parameter on `/profiles/manager` that pre-loads the profile and inspirations payloads into the editor on render
+* Portuguese (`pt_pt`) translation of the profile manager screen mirroring the existing `manager.ejs` layout
+* `Profile Manager` link on the welcome action bar pointing to `/profiles/manager`
+* Profile manager jQuery plugin (`plugins/profilemanager.js`, `css/plugins/profilemanager.css`) that encapsulates the manager screen behavior previously inlined in `main.js`, initialized via a single `.form-manager.profilemanager()` call
+* JSON syntax highlight jQuery plugin (`plugins/jsonhighlight.js`, `css/plugins/jsonhighlight.css`) that overlays a tokenized colored preview on top of the profile and inspirations textareas, applied automatically by the profile manager so keys, strings, numbers, booleans, null, and punctuation are colored while the native textarea behavior is preserved
+* Support for toggling the visual keyboard by clicking the same font again
+* Support for multiple lines with Enter key and visual keyboard `↵` button
+* Enforcement of `max_lines` profile constraint when inserting newlines
+* Display of max lines in the profile info panel
+* Dry run checkbox in the engraving confirmation modal
+* Raw profile JSON viewer with show/hide toggle in the profile info panel
+* Newline rendering in report views (EN and PT)
+* Horizontal and vertical rulers adjacent to the viewport preview
+* Arrow key navigation (left, right, up, down) for caret movement
+* Delete key support for forward character deletion
+* Floating viewport options panel with profile selection, font size controls, and rulers toggle
+* Margin override controls in viewport options panel with real-time preview
+* Margins included in the engraving confirmation report
+* Application icon (SVG, PNG 512/180/32) with monospaced S on blue gradient
+* Favicon and Apple touch icon references in HTML head
+* Icon generation script (`npm run icons`) using sharp
+* Circular profile shape support with `shape: "circle"` field
+* New "small-medal" circular profile (20x20mm)
+* Circle boundary rendering in viewport preview for circular profiles
+* Zoom slider in viewport options panel with per-profile default zoom and layout compensation
+* Collapsible viewport options and profile info panels with animated toggle
+* Dynamic profile info panel title showing the selected profile name
+* Crosshair lines on viewport hover with toggleable visibility checkbox
+* Position readout in viewport options panel showing X/Y coordinates in mm
+* Show Keyboard toggle checkbox in viewport options panel to hide/show the visual keyboard
+* Selected class tracking on the active keyboard container for font-based key validation
+* Single-line constraint when no profile is selected (max 1 line)
+* Emoji validation script (`scripts/emoji_validation.py`) for visual glyph-to-F3S mapping verification
+* Missing emoji keyboard keys for all Cool Emojis TTF glyphs (`0`, `@`, `$`, `%`, `&`, `(`, `)`, `` ` ``, `[`, `{`, `|`, `}`)
+* Optional background image support for viewport profiles (`background` field)
+* Show Guidelines toggle checkbox in viewport options panel to hide/show SVG bounds and safe area
+* Show Caret toggle checkbox in viewport options panel to hide/show the blinking caret
+* URL persistence for rulers, crosshair, keyboard, guidelines, and caret visibility toggles
+* Font metrics rendering script (`scripts/font_metrics.py`) for visual glyph metric inspection
+* Inspiration presets system with per-profile pre-built configurations
+* Collapsible inspiration panel on the right side showing 3 thumbnail previews
+* Full-screen inspiration modal with 4-column grid, search, and click-to-apply
+* Inspiration plugin (`plugins/inspiration.js`) with event-driven architecture
+* Dedicated inspiration CSS file (`css/inspiration.css`) for panel and modal styles
+* Hover zoom and active press animations on inspiration preview thumbnails
+* Sample inspirations for small-medal profile including emoji presets
+* Modal `hide` action for programmatic dismiss with animation
+* Collapsible panel jQuery plugin (`plugins/collapsible.js`, `css/collapsible.css`) extracted from inline logic
+* Font size number input alongside range slider with per-profile step granularity
+* Shared `.options-input` CSS class for consistent number input styling across controls
+* Per-profile jig instructions modal with images, accessible via "Instructions" link in options panel
+* Profile variants support with dropdown selector for sub-type overrides (padding, background, font size)
+* Viewport preview jQuery plugin (`plugins/viewportpreview.js`) for SVG rendering, rulers, and zoom
+* `AGENTS.md` with project conventions for building, testing, plugins, and commit messages
+* Plugin CSS files moved to `static/css/plugins/` mirroring the `static/js/plugins/` structure
+* JSDoc-style `/** */` docstrings on jQuery plugin definitions with actions and events
+* Profile selector jQuery plugin (`plugins/profileselector.js`) for profile and variant dropdown management
+* Welcome screen at `/welcome` with a visual template catalog of the available profiles (image, name, dimensions)
+* Welcome jQuery plugin (`plugins/welcome.js`, `css/welcome.css`) with `load` and `value` actions
+* Forwarding of `profile` and `variant` query parameters from the gateway POST to the editor for template pre-selection
+* Session-tracked entry point so the back arrow in the viewport, signature, and report views returns to the welcome screen or classic gateway depending on where the user came from
+* Restoration of the previously selected template card on the welcome catalog when navigating back from the editor
+* Portuguese (`pt_pt`) translation of the welcome screen mirroring the existing `welcome.ejs` layout
+* Documentation of the supported HTTP query parameters in `README.md`, grouped per route with type, default, and description columns
+* White background on the welcome screen version footer so it visually matches the action bar above it
+* Settings page at `/settings` for selecting the session-persisted `theme`, `locale`, and `fullscreen` values, with a Portuguese translation and a link from the welcome screen action bar
+* Session-persisted `home` preference selecting whether the bare `/` URL redirects to the classic gateway or to the welcome screen, defaulting to gateway
+* Session-persisted `show_options` preference toggling whether the technology, elements, and location selectors are rendered on the welcome screen and classic gateway, defaulting to on; when off the previously selected values are submitted via hidden inputs so the form still routes correctly
+* `docs/profile-spec.md` documenting the profile and inspirations JSON schema sourced from the `lib/util/profile.js` validator, with a pointer from `README.md`
+* Optional top-level `default_font` field on the profile schema that auto-selects the matching font (and its keyboard) on initial profile load when no font is already active and no URL `font` parameter is supplied
+* Session-persisted `viewport_mode` setting (`technical` default, `store`) on `/settings` that, when set to `store`, applies a `store-mode` body class on `/viewport` whose dedicated `static/css/store-mode.css` hides the profile info panel, the profile and variant selectors, the rulers/crosshair/keyboard/guidelines/caret toggles, the zoom slider, the margin override fields, and the position readout; rulers, crosshair and guidelines visuals are forced off through the existing checkbox change handlers while the keyboard and caret stay active
+
+### Changed
+
+* The viewport preview reclaims about 52px of vertical space when the rulers are toggled off: the body now carries a `rulers-off` class that collapses the preview's top reservation from 48px to 8px and the bottom gap from 16px to 4px, so the chrome-free vertical room recovered from the hidden ruler labels feeds straight back to the editing surface instead of sitting empty; the class is flipped through the existing rulers change handler and seeded on initial render from the URL restored value so there is no flash on first paint
+* Special character keys on the on screen keyboard (`Backspace`, `Shift`, `Space`, `Return`) now render the official Lucide `delete`, `arrow-big-up`, `space`, and `corner-down-left` SVG icons inline so they look identical across every platform regardless of the system font's rendering of the matching Unicode codepoints; the keyboard plugin reads the dispatched value from the `data-value` attribute first and falls back to the element text so the existing downstream `keyHandler` switch keeps working unchanged, and the inline SVGs share a consistent `viewBox`, stroke weight and round line caps so they read as a single visual family
+* The confirmation modal preview now sits on a soft tinted card with the spec list rendered as a clean rounded table (`label : value` rows, monospaced segment chips) instead of the previous inline `bold key: value` debug style, the spec rows are tightened (font size, padding, column width) so the contents fit comfortably inside the modal without overflowing
+* `/settings` printing tab now uses a stable scrollbar gutter on the surrounding catalog rail (`scrollbar-gutter: stable`) so the card position does not shift when a long tab causes a scrollbar to appear, the printing inputs use `flex: 1 1 0` plus `min-width: 0` so their intrinsic content width (long URLs in the disabled `Base` pill) cannot push the row past the card boundary, and the card itself no longer caps at `max-height: 560px` so the printing tab can grow vertically to fit all entries
+* `/viewport` `updateUrl` is now an action scoped serializer that takes the change source as an argument (`text`, `profile`, `font`, `font_size`, `zoom`, `margins`, `toggle`, `restore`) and only rewrites the matching URL fragment while preserving the rest of the query string verbatim, so callers no longer recompute the full URL from possibly stale DOM state; the function also bails out early when the viewport editor is not mounted on the current page (`viewer-container` absent) so non viewport pages never accumulate viewport only query parameters in their address bar, with `theme` dropped from the URL writes entirely since it lives in the cookie session
+* `fullscreen` flag is now persisted on the cookie session alongside the other UI preferences, so it survives the next request without having to be forwarded through redirect query strings; every page route reads `req.query.fullscreen` first as an override and falls back to `req.session.fullscreen`, the `/settings` POST stores it on the session and redirects without appending the flag to the target URL, and the front end `updateUrl` no longer writes it back into the address bar
+* Modernized the classic `/gateway` form so it now reuses the same page chrome as welcome / settings / profile manager: the page wrapper changed from `.gateway` to `.welcome`, the form is wrapped by the standard hero (logo, `Gateway` / `Entrada` eyebrow, hairline divider), the form fields moved into a white `.gateway-container` card on the new tinted body (lavender bordered and tinted-shadow in `ldj`), the text inputs and labels now follow the `settings-group` / `settings-group-label` pattern, the Order No. + Size pair lives in a flex `.gateway-row`, the Technology / Elements / Location radio buttons became `option-chips` matching the welcome screen chip language, and the Submit / Configure buttons now sit on a centered `welcome-action-bar` with Submit as the primary `button-start` and Configure as a `button-ghost` secondary
+* Stopped persisting the viewport-only visual toggles (`rulers`, `crosshair`, `keyboard`, `guidelines`, `caret`, `zoom`, `margins`, `font_size`, `font_size_mode`, `font`, `theme`) into the address bar from `updateUrl`, so the address bar on `/viewport` now only carries semantic state (`text`, `profile`, `variant`, `fullscreen`) and these UI level flags can no longer leak into shareable links or downstream pages
+* Removed the welcome screen default template pre-selection so the catalog renders with nothing highlighted and the Start button stays disabled until the user explicitly picks a card; the hidden `profile` input is cleared on each render so a previously chosen template never restores itself
+* Modernized the `/report` view with a tinted page surface, a 2-column grid of soft-fill spec tiles (date, order, size, technology, elements, location, font), a softer card shadow with the new layered palette, and a full-width engraving preview row that spans both columns; LDJ theme picks up the lavender chip / border / shadow tints to keep visual continuity with the rest of the studio
+* Replaced the `Report` text button with an icon-only soft-surface pill in the `/viewport` header (Ionicons `document-text-outline`) to recover header space; the icon button inherits the same theme-aware tint as the other header secondaries (neutral grey default, lavender in `ldj`)
+* Modernized the profile manager dropdown style on `/profiles/manager` with a custom inline-SVG chevron, white resting state with a soft `#e6e8ee` border that deepens on hover and on focus (lavender `#ece4f5` → `#c9b6e5` → `rgba(151, 120, 211, 0.55)` in `ldj`), 12px radius, 40px height, smooth color/border transitions, and a reusable `.manager-select` class shared by both the reference dropdown and the new editor dropdown
+* Modernized the side panel components on `/viewport` (profile info, viewport options, inspirations panel) with the new layered shadow language: borderless 14px radius cards with `0 8px 20px rgba(31, 35, 48, 0.06) + 0 1px 2px rgba(31, 35, 48, 0.04)`, soft pill selects with chevron SVG, soft-fill numeric inputs with theme-aware focus borders, smaller muted eyebrow titles, and a chip-style author badge on the inspirations modal cards
+* Replaced the in-process `express-session` MemoryStore with `cookie-session` so UI preferences survive Node restarts without any server-side storage; the cookie carries non-sensitive UI state only and uses a hardcoded secret to keep dev installs working out of the box
+* Theme aware tinted page canvas plus a frosted glass header (`backdrop-filter: saturate(160%) blur(12px)`) replace the flat white chrome on `/viewport` and the welcome screen, with the lavender body wash and hairline picked up in the `ldj` theme so the floating panels read as real white surfaces on a soft tinted page
+* Smoothed the keyboard show/hide flow on `/viewport`: switching fonts now waits for the leaving keyboard to fade out before the next one fades in (sequential cross fade), the `font` event handler picks the previously visible keyboard once and chains the show onto its leave callback, and `pointer-events: none` on the leaving keyboard prevents accidental clicks during the transition
+* Compacted and modernized the font selector row above the visual keyboards (`.fonts-container`): tiles are now full-pill chips with a soft white fill, no hard border, a subtle resting shadow, lift-on-hover, and a dark filled selected state matching the Engrave button language; in-tile font preview (each label rendered in its own typeface) is preserved, and tile height drops from 46px to 36px (with tighter row margin) so the row reclaims ~20px of vertical real estate
+* Refreshed the visual keyboards (`.keyboard-container`, `.emojis-container`, `.emojisp-container`) with a frosted glass aesthetic: translucent white keys with `backdrop-filter: blur(8px)` and a soft inner highlight, 10px rounded corners, hover deepens the shadow and lifts 1px, active presses in with an inset shadow; the keyboard surface itself now sits in a soft tinted card with a 16px radius and a subtle gradient backdrop so the frosted keys read as floating tiles
+* Introduced a `utility` class on the special keys (`⌫`, `⎵`, `↵`, `⇧`) that gives them a translucent grey fill and slightly smaller glyph so they visually separate from the letter rows, and widened the Space bar from 96px to 220px so it reads like a real keyboard space; the Shift active state picks up a lavender tint that matches the rest of the engraving studio palette
+* Refreshed the welcome catalog template cards to a refined glass card aesthetic for consumer-facing jewelry store users: borderless cards with soft layered shadows that deepen and lift on hover, 16px outer radius with a nested 12px inner image panel carrying an inset highlight, taller 150px image area so the necklace photography breathes, name aligned left next to a soft chip-style dimension badge, and a confident 2px selected ring that replaces the previous thin border (matching purple ring in the `ldj` theme)
+* Refreshed the site-wide button visual language to a softer, rounder feel: full pill `border-radius`, taller comfortable 38px height, breathable horizontal padding, smooth color and press transitions; viewport header `Back`, `Clear` and `Report` buttons now read as soft-surface secondaries (light grey fill) while `Engrave` keeps the dark filled primary treatment, restoring visual hierarchy on the action bar
+* Aligned the surrounding surface chrome with the new rounder language by bumping `.input` and the floating profile info / inspiration panel border radii from 6px to 12px, and re-anchoring the panels under the slightly taller header (78px → 84px / 220px → 226px) so the breathing room above each panel is preserved
+* Welcome action bar `button-ghost` variant now uses the same soft-surface fill instead of a 1px outlined pill so it matches the new system
+* Corrected Cool Emojis character-to-F3S font mapping using visual glyph recognition
+* Sorted `coolemojis.mapping.json` by font number for better structure
+* Line height in viewport preview now scales proportionally to font size (1.2x)
+* Moved profile and font size controls from inline layout to fixed options panel
+
+### Fixed
+
+* Avoids a split second flash of the legacy dashed text box on the viewport while the profile selector is being restored: the body now carries a `profiles-loading` class at server render time that hides the no profile viewer container, and the class is cleared in a `finally` block once `loadProfiles` resolves so the legacy box only appears after the initial profile state has been settled
+* Hide the floating viewport options panel on `/viewport` in store mode when no profile is selected since every visible field inside it requires an active profile, so the panel no longer renders as an empty chrome card; the rule lives in `static/css/store-mode.css` and relies on the existing `.profile-active` signal so the panel reappears immediately when a profile is picked
+* Stop applying the zoom compensating `margin-bottom` and `margin-right` on the viewport preview when no profile is active, so the extra bottom and right space no longer appears under the empty engraving surface or when entering preview mode without a selected template; detection uses the existing `.profile-active` class on the preview element so every caller of the `zoom` action benefits without per call site changes
+* `text.max_lines` profile constraint now also enforced on programmatic text loads (inspirations, deep-link `?text=…`, session restore) and when the active profile changes, trimming any overflow newlines and emitting a `change` event so the URL state and button state stay in sync
+* Script 4L font glyphs with positive LSB shifted to start at x=0 with adjusted advance widths
+* `/profiles` endpoint now handles async errors through Express error middleware
+* Invalid CSS `background-position` value corrected to valid 2-value syntax
+* Restored text click handler now binds to all non-caret children including newline elements
+* Malformed HTML `style` attribute on space bar keyboard keys (extra double quote)
+* Small-medal profile description now matches actual 20x20mm dimensions
+* Font deselection handler now clears stored font state and updates URL
+* Backspace at caret start position no longer corrupts text state
+* Server-side validation for `preview.zoom` field in profile schema
+* `lang` attribute on Portuguese views (`welcome-pt_pt.ejs`, `gateway-pt_pt.ejs`, `report-pt_pt.ejs`) corrected from `en` to `pt`
+* Welcome catalog `background-image` URLs now pass profile filenames through `encodeURI` to guard against malformed CSS
+
+### Removed
+
+* `Printer Configuration` modal (`.modal-overlay-config`) from `/viewport` and `/gateway`, along with the matching `Configure` header button on `/gateway` and the `Configure` button inside the error modal that used to open it; the same configuration is now fully owned by the `Printing` tab on `/settings`, the gateway entry point becomes a plain `<a href="/settings">Settings</a>` link, the error modal `Configure` action becomes a plain `<a href="/settings">` link, and the now unused `buttonConfigure` / `buttonSave` plumbing on `main.js` and `plugins/modal.js` (~80 lines) is removed
+
+## [0.7.2] - 2024-05-18
+
+### Changed
+
+* Bumped pstoedit version to 4.01
+
+## [0.7.1] - 2024-05-18
+
+### Changed
+
+* Bumped base nodejs version in `Dockerfile` to 18
+
+## [0.7.0] - 2024-05-18
+
+### Added
+
+* Support for escaping of characters in the key selection
+
+### Changed
+
+* Added new characters to the `coolemojis.ttf` font
+
+### Fixed
+
+* Keyboard backspace and space keys issue - [[#4](https://github.com/hivesolutions/signatur/issues/4)]
+
+## [0.6.1] - 2022-11-12
+
+### Fixed
+
+* Keyboard backspace and space keys issue - [[#4](https://github.com/hivesolutions/signatur/issues/4)]
+
+## [0.6.0] - 2022-11-08
+
+### Added
+
+* Support for physical keyboard typing
+
+### Fixed
+
+* CI/CD integrations to make them compliant with new node versions
+
+## [0.5.5] - 2022-11-08
+
+### Fixed
+
+* Small tilde character in emoji font
+
+## [0.5.4] - 2022-11-08
+
+### Fixed
+
+* Added the new characters to cool emojis fonts
+
+## [0.5.3] - 2022-11-08
+
+### Changed
+
+* Added new versions of `coolemojis.ttf` and `coolemojisp.ttf` fonts - [[#2](https://github.com/hivesolutions/signatur/issues/2)
+
+## [0.5.2] - 2022-09-27
+
+### Fixed
+
+* Removed `graphic_element` from `diamond`
+
+## [0.5.1] - 2021-10-17
+
+### Added
+
+* New symbols added to both the base `coolemojis.ttf` font and the `coolemojisp.ttf`
+
+## [0.5.0] - 2021-10-06
+
+### Added
+
+* Support for the `/image` URL for PNG image generation
+
+## [0.4.1] - 2021-09-24
+
+### Added
+
+* Support in report for calligraphy
+
+## [0.4.0] - 2021-09-24
+
+### Added
+
+* Support for order number, size and observations
+
+## [0.3.2] - 2021-08-31
+
+### Added
+
+* More symbols to the `coolemojis.ttf` font
+
+## [0.3.1] - 2021-08-30
+
+### Added
+
+* Version information to footer
+
+### Changed
+
+* Bumped packages
+
+## [0.3.0] - 2021-08-30
+
+### Added
+
+* Support for new character for font `coolemojisp.ttf` (V, W, X, Y, Z, a, b, c, d, e, f and g)
+
+## [0.2.1] - 2021-07-08
+
+### Added
+
+* Small touch of files
+
+## [0.2.0] - 2021-07-08
+
+### Added
+
+* Support for display of main font in report and receipt
+* Added new cool emoji icons

package/README.md

@@ -4,12 +4,188 @@ Simple vector signature service to be used to convert signatures.
 
 Signatures from the client-side into beautiful files ready to be downloaded.
 
+Supported file format include:
+
+* [SVG](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) - Scalable Vector Graphics
+* [PDF](https://en.wikipedia.org/wiki/PDF) - Portable Document Format
+* [HPGL](https://en.wikipedia.org/wiki/HP-GL) - Hewlett-Packard Graphics Language
+
+## Features
+
+* Canvas based drawing, to be used in signatures
+* Viewport for drawing of text and emoji
+* Uses [canvas2svg](http://gliffy.github.io/canvas2svg) for SVG output
+
+## Configuration
+
+| Name              | Type  | Default                              | Description                                                                                                                                            |
+| ----------------- | ----- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `BASE_URL`        | `str` | `http://localhost:3000`              | The base URL that is going to be used in the construction of external URLs for Signatur.                                                               |
+| `SIGNATUR_KEY`    | `str` | `None`                               | Secret key that should be passed in protected calls so that the server side "trusts" the client side (authentication).                                 |
+| `HEADLESS_URL`    | `str` | `https://headless.stage.hive.pt`     | The base URL to be used to access [Headless](https://github.com/hivesolutions/headless).                                                               |
+| `PRINT_URL`       | `str` | `https://colony-print.stage.hive.pt` | Base URL of the [Colony Print](http://colony-print.hive.pt) service used for both the engraving job and the receipt printing.                          |
+| `PRINT_NODE`      | `str` | `default`                            | Name of the Colony Print node to use when printing the report receipt.                                                                                 |
+| `PRINT_PRINTER`   | `str` | `printer`                            | Name of the printer (within the receipt node) to use when printing the report receipt.                                                                 |
+| `PRINT_KEY`       | `str` | `null`                               | Secret key used to authenticate against Colony Print; shared by both the engraving job and the receipt printing.                                       |
+| `ENGRAVE_NODE`    | `str` | value of `PRINT_NODE`                | Name of the Colony Print node to use when sending an engraving job; falls back to `PRINT_NODE` so existing single-printer deployments keep working.    |
+| `ENGRAVE_PRINTER` | `str` | value of `PRINT_PRINTER`             | Name of the printer (within the engrave node) to use when sending an engraving job; falls back to `PRINT_PRINTER` for the same backward compat reason. |
+
+## Query Parameters
+
+The following query parameters are honored by the Signatur HTTP routes. Most of the session level toggles (`theme`, `locale`, `text`, `fullscreen`, etc.) are persisted to the cookie session on first sight and then read from the session on every subsequent request, so they never need to be carried around through the URL once they have been set. The viewport editor still round-trips its visual state through the URL so a `/viewport` link can be shared or bookmarked verbatim, but those keys are scoped to the viewport page and are not propagated to other sections.
+
+### Session persistence
+
+| Parameter       | Session-persisted | Notes                                                                                                                                                                                                                                                                                                                  |
+| --------------- | :---------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `theme`         |        yes        | Written to `req.session.theme` on every page that reads it except `/console`, which reads but does not write.                                                                                                                                                                                                          |
+| `locale`        |        yes        | Written to `req.session.locale` on every page that reads it.                                                                                                                                                                                                                                                           |
+| `text`          |        yes        | Written to `req.session.config.text` on every page that reads it.                                                                                                                                                                                                                                                      |
+| `fullscreen`    |        yes        | Written to `req.session.fullscreen` on every page that reads it; the URL query is honored first as a one-shot override and otherwise the session takes over.                                                                                                                                                           |
+| `home`          |        yes        | Set via the `/settings` POST body. Controls whether `/` redirects to `/gateway` (default) or `/welcome`.                                                                                                                                                                                                               |
+| `show_options`  |        yes        | Set via the `/settings` POST body. Controls whether the technology / elements / location selectors render on welcome and gateway.                                                                                                                                                                                      |
+| `viewport_mode` |        yes        | Set via the `/settings` POST body. Either `technical` (default) or `store` (simplified `/viewport` for store operators).                                                                                                                                                                                               |
+| `profile`       |        no         | Stored on the session via the `/gateway` POST body (form field), then forwarded as a query string to the editor on redirect.                                                                                                                                                                                           |
+| `variant`       |        no         | Same handling as `profile`.                                                                                                                                                                                                                                                                                            |
+| editor state    |        no         | `font`, `font_size`, `font_size_mode`, `zoom`, `margins`, `rulers`, `crosshair`, `keyboard`, `guidelines`, `caret` are written to the URL by the viewport only, and only while `.viewer-container` is mounted on the page so they never leak into `/welcome`, `/gateway`, `/settings` or any other downstream section. |
+| `engine`        |        no         | Read once per `/convert` POST.                                                                                                                                                                                                                                                                                         |
+| `format`        |        no         | Read once per `/convert` POST.                                                                                                                                                                                                                                                                                         |
+
+### Theme and locale
+
+| Route        | `theme` | `locale` | `fullscreen` |
+| ------------ | :-----: | :------: | :----------: |
+| `/`          |   yes   |   yes    |     yes      |
+| `/gateway`   |   yes   |   yes    |     yes      |
+| `/welcome`   |   yes   |   yes    |     yes      |
+| `/signature` |   yes   |    -     |     yes      |
+| `/viewport`  |   yes   |    -     |     yes      |
+| `/report`    |   yes   |   yes    |     yes      |
+| `/console`   |   yes   |    -     |      -       |
+| `/receipt`   |    -    |   yes    |      -       |
+| `/image`     |    -    |   yes    |      -       |
+
+| Name         | Type  | Default | Description                                                                                                                                    |
+| ------------ | ----- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `theme`      | `str` | `""`    | Visual theme identifier applied to the body (e.g. `ldj`). Persisted on the session for subsequent requests.                                    |
+| `locale`     | `str` | `""`    | Locale identifier used to pick a localized view (e.g. `pt_pt`). Persisted on the session and used to load the matching `*-${locale}.ejs`.      |
+| `fullscreen` | `str` | `"0"`   | When set to `"1"`, enables the `apple-mobile-web-app-capable` meta. Persisted on the session; the URL query is honored as a one-shot override. |
+
+### Text payload (`/viewport`, `/report`, `/text`, `/image`, `/receipt`)
+
+| Name   | Type  | Default | Description                                                                                                                |
+| ------ | ----- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `text` | `str` | `null`  | Serialized text payload to seed the editor or render with (`font/character` pairs). Persisted on the session config field. |
+
+### Template pre-selection (`/viewport`, `/report`)
+
+Forwarded automatically by the gateway POST when the welcome screen is used, but they can also be passed directly to deep-link into the editor with a specific template.
+
+| Name      | Type  | Default | Description                                                                                        |
+| --------- | ----- | ------- | -------------------------------------------------------------------------------------------------- |
+| `profile` | `str` | `null`  | Profile ID (matches a file under `static/profiles/*.json`) to pre-select in the profile dropdown.  |
+| `variant` | `str` | `null`  | Index of the variant to pre-select within the chosen profile, applied after `profile` is restored. |
+
+### Viewport editor state (`/viewport`)
+
+Read by the client and written back via `history.replaceState` so the editor URL always reflects the current state and can be shared or reloaded.
+
+| Name             | Type  | Default | Description                                                                                             |
+| ---------------- | ----- | ------- | ------------------------------------------------------------------------------------------------------- |
+| `font`           | `str` | `null`  | Currently selected font name; restored by clicking the matching font element on load.                   |
+| `font_size`      | `int` | `null`  | Manual font size in profile units; applied to both the slider and the number input.                     |
+| `font_size_mode` | `str` | `null`  | Either `manual` or `automatic` for the font size mode toggle.                                           |
+| `zoom`           | `int` | `null`  | Zoom percentage applied to the viewport preview; clamped to the slider's min/max range.                 |
+| `margins`        | `str` | `null`  | Four comma-separated values (`left,right,top,bottom`) overriding the profile padding, in profile units. |
+| `rulers`         | `str` | `"1"`   | When `"0"` hides the horizontal and vertical rulers; any other value (or absent) keeps them visible.    |
+| `crosshair`      | `str` | `"1"`   | When `"0"` disables the hover crosshair lines on the viewport preview.                                  |
+| `keyboard`       | `str` | `"1"`   | When `"0"` hides the visual keyboard panel until re-toggled.                                            |
+| `guidelines`     | `str` | `"1"`   | When `"0"` hides the SVG profile bounds and safe area outlines on the preview.                          |
+| `caret`          | `str` | `"1"`   | When `"0"` hides the blinking caret in the viewport preview.                                            |
+
+### `/convert`
+
+| Name     | Type  | Default      | Description                                                                              |
+| -------- | ----- | ------------ | ---------------------------------------------------------------------------------------- |
+| `engine` | `str` | `"inkscape"` | Conversion engine identifier; resolved against the registered engines (e.g. `inkscape`). |
+| `format` | `str` | `"hpgl"`     | Target output format honored by the inkscape engine; one of `svg`, `pdf`, or `hpgl`.     |
+
+## Profiles
+
+The engraving surfaces (medals, plates, rings, etc.) are described by JSON profile files under `static/profiles/`. The schema of these files (and of their companion `*.inspirations.json` files) is documented in [docs/profile-spec.md](docs/profile-spec.md). The authoritative validator lives in `lib/util/profile.js` and is the source the spec document tracks.
+
+## Printing
+
+Signatur drives two independent print jobs through Colony Print: the **engraving** job that is sent from the `/viewport` editor and the **receipt** job that is printed from `/report`. Both share the same Colony Print server URL and the same secret key, but each one targets its own node and printer so a single Signatur install can drive an engraver and a receipt printer that live on different physical machines without any name collision.
+
+The configuration is resolved through a three step fallback chain so existing single printer deployments keep working without any change:
+
+1. **Scenario specific `localStorage` keys** (browser side, highest priority).
+2. **Legacy unprefixed `localStorage` keys** (`node`, `printer`) so installs that predate the engrave/receipt split still see their old configuration.
+3. **Server side environment variables** rendered into the page as `data-*` fallbacks (`PRINT_URL`, `ENGRAVE_NODE`/`ENGRAVE_PRINTER` for the engrave button, `PRINT_NODE`/`PRINT_PRINTER` for the receipt button, `PRINT_KEY` for both).
+
+The settings page exposes a `Printing` readout that shows the server side base value next to the effective resolved value for each entry, so an operator can verify at a glance which side is active.
+
+### Configuration keys
+
+| `localStorage` key | Scenario | Server side fallback                            | Description                                                                         |
+| ------------------ | -------- | ----------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `url`              | shared   | `PRINT_URL`                                     | Colony Print base URL; used by both the engrave and the receipt flows.              |
+| `key`              | shared   | `PRINT_KEY`                                     | Colony Print secret key; used by both the engrave and the receipt flows.            |
+| `engrave_node`     | engrave  | `ENGRAVE_NODE` (defaults to `PRINT_NODE`)       | Colony Print node that receives the engrave job (`POST /nodes/<node>/print`).       |
+| `engrave_printer`  | engrave  | `ENGRAVE_PRINTER` (defaults to `PRINT_PRINTER`) | Printer within the engrave node; reserved for the per-printer engrave endpoint.     |
+| `receipt_node`     | receipt  | `PRINT_NODE`                                    | Colony Print node that receives the receipt (`POST /nodes/<node>/printers/print`).  |
+| `receipt_printer`  | receipt  | `PRINT_PRINTER`                                 | Printer within the receipt node.                                                    |
+| `node`             | legacy   | -                                               | Read as a fallback for both `engrave_node` and `receipt_node` so old installs work. |
+| `printer`          | legacy   | -                                               | Read as a fallback for both `engrave_printer` and `receipt_printer`.                |
+
+To configure both scenarios from the Browser's JavaScript console:
+
+```javascript
+// shared between both scenarios
+localStorage.setItem("url", "https://colony-print.stage.hive.pt");
+localStorage.setItem("key", "${server-key}");
+
+// engraving job (the /viewport "Engrave" action)
+localStorage.setItem("engrave_node", "${engrave-node}");
+localStorage.setItem("engrave_printer", "${engrave-printer}");
+
+// receipt printing (the /report "Receipt" action)
+localStorage.setItem("receipt_node", "${receipt-node}");
+localStorage.setItem("receipt_printer", "${receipt-printer}");
+```
+
+To read the configuration:
+
+```javascript
+console.info(localStorage.getItem("url"));
+console.info(localStorage.getItem("key"));
+console.info(localStorage.getItem("engrave_node"));
+console.info(localStorage.getItem("engrave_printer"));
+console.info(localStorage.getItem("receipt_node"));
+console.info(localStorage.getItem("receipt_printer"));
+```
+
+The same configuration can also be edited through the `Configure` modal accessible from the gateway and the viewport.
+
+## Maintenance
+
+### Adding New Emoji
+
+To add a new emoji to the system the following steps should be followed:
+
+1. Determine the right file name for the new emoji font file (e.g. `coolemojis.ttf` for laser and `coolemojisp.ttf` for pantogrpah)
+2. Place the new font file in the `static/fonts` directory
+3. Add the new emoji "characters" to the `emoji` array in the `viewport.ejs` file
+4. Test the using the local machine `yarn && yarn dev`
+5. Release a new version of the system (Docker Image)
+
 ## License
 
 Signatur is currently licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/).
 
 ## Build Automation
 
-[![Build Status](https://travis-ci.org/hivesolutions/signatur.svg?branch=master)](https://travis-ci.org/hivesolutions/signatur)
+[![Build Status](https://github.com/hivesolutions/signatur/workflows/Main%20Workflow/badge.svg)](https://github.com/hivesolutions/signatur/actions)
 [![npm Status](https://img.shields.io/npm/v/signatur.svg)](https://www.npmjs.com/package/signatur)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://www.apache.org/licenses/)