@prosopo/puzzle-assets 0.1.4 → 0.2.0

package/.turbo/turbo-build$colon$cjs.log

@@ -1,7 +1,4 @@
-
-> @prosopo/puzzle-assets@0.1.4 build:cjs
-> NODE_ENV=${NODE_ENV:-development}; vite build --config vite.cjs.config.ts --mode $NODE_ENV
-
+$ NODE_ENV=${NODE_ENV:-development}; vite build --config vite.cjs.config.ts --mode $NODE_ENV
 ViteCommonJSConfig: .
 { tsConfigPaths: [] }
 { externals: [] }
@@ -9,17 +6,18 @@ ViteCommonJSConfig: .
 vite v8.1.5 building ssr environment for production...
 Bundle build started
 
-✓ 9 modules transformed.
+✓ 10 modules transformed.
 rendering chunks...
 computing gzip size...
-dist/cjs/_virtual/_rolldown/runtime.cjs  1.00 kB │ gzip: 0.50 kB
-dist/cjs/prng.cjs                        1.47 kB │ gzip: 0.75 kB
-dist/cjs/encode.cjs                      1.91 kB │ gzip: 0.90 kB
-dist/cjs/palette.cjs                     2.42 kB │ gzip: 1.07 kB
-dist/cjs/index.cjs                       3.48 kB │ gzip: 1.26 kB
-dist/cjs/notch.cjs                       4.21 kB │ gzip: 1.37 kB
-dist/cjs/background.cjs                  4.30 kB │ gzip: 1.84 kB
-dist/cjs/decoys.cjs                      4.54 kB │ gzip: 1.94 kB
-dist/cjs/compose.cjs                     5.17 kB │ gzip: 2.00 kB
+dist/cjs/_virtual/_rolldown/runtime.cjs   1.00 kB │ gzip: 0.50 kB
+dist/cjs/prng.cjs                         1.47 kB │ gzip: 0.75 kB
+dist/cjs/encode.cjs                       1.91 kB │ gzip: 0.90 kB
+dist/cjs/palette.cjs                      4.07 kB │ gzip: 1.81 kB
+dist/cjs/contrast.cjs                     4.18 kB │ gzip: 1.92 kB
+dist/cjs/background.cjs                   4.30 kB │ gzip: 1.84 kB
+dist/cjs/index.cjs                        4.44 kB │ gzip: 1.54 kB
+dist/cjs/notch.cjs                        4.46 kB │ gzip: 1.81 kB
+dist/cjs/decoys.cjs                       4.54 kB │ gzip: 1.94 kB
+dist/cjs/compose.cjs                     10.60 kB │ gzip: 4.03 kB
 
-✓ built in 79ms
+✓ built in 53ms

package/.turbo/turbo-build$colon$tsc.log

@@ -1,14 +1,11 @@
-
-> @prosopo/puzzle-assets@0.1.4 build:tsc
-> tsc --build --verbose
-
-1:14:42 PM - Projects in this build: 
+$ tsc --build --verbose
+1:37:11 PM - Projects in this build: 
     * ../../dev/config/tsconfig.json
     * tsconfig.json
 
-1:14:43 PM - Project '../../dev/config/tsconfig.json' is up to date because newest input '../../dev/config/src/webpack/webpack.config.ts' is older than output '../../dev/config/tsconfig.tsbuildinfo'
+1:37:12 PM - Project '../../dev/config/tsconfig.json' is up to date because newest input '../../dev/config/src/webpack/webpack.config.ts' is older than output '../../dev/config/tsconfig.tsbuildinfo'
 
-1:14:43 PM - Project 'tsconfig.json' is out of date because output file 'tsconfig.tsbuildinfo' does not exist
+1:37:12 PM - Project 'tsconfig.json' is out of date because output file 'tsconfig.tsbuildinfo' does not exist
 
-1:14:43 PM - Building project '/home/runner/work/captcha/captcha/packages/puzzle-assets/tsconfig.json'...
+1:37:12 PM - Building project '/home/runner/work/captcha/captcha/packages/puzzle-assets/tsconfig.json'...
 

package/.turbo/turbo-build.log

@@ -1,11 +1,5 @@
-
-> @prosopo/puzzle-assets@0.1.4 build
-> npm run build:cross-env -- --mode ${NODE_ENV:-development}
-
-
-> @prosopo/puzzle-assets@0.1.4 build:cross-env
-> vite build --config vite.esm.config.ts --mode production
-
+$ pnpm run build:cross-env --mode ${NODE_ENV:-development}
+$ vite build --config vite.esm.config.ts --mode production
 ViteEsmConfig: .
 { tsConfigPaths: [] }
 { externals: [] }
@@ -13,18 +7,19 @@ ViteEsmConfig: .
 vite v8.1.5 building ssr environment for production...
 Bundle build started
 
-✓ 10 modules transformed.
+✓ 11 modules transformed.
 rendering chunks...
 computing gzip size...
-dist/_virtual/_rolldown/runtime.js  0.04 kB │ gzip: 0.06 kB
-dist/prng.js                        1.40 kB │ gzip: 0.73 kB
-dist/browser.js                     1.63 kB │ gzip: 0.68 kB
-dist/encode.js                      1.67 kB │ gzip: 0.82 kB
-dist/palette.js                     2.39 kB │ gzip: 1.07 kB
-dist/index.js                       2.84 kB │ gzip: 1.16 kB
-dist/notch.js                       4.16 kB │ gzip: 1.36 kB
-dist/background.js                  4.25 kB │ gzip: 1.83 kB
-dist/decoys.js                      4.50 kB │ gzip: 1.93 kB
-dist/compose.js                     5.14 kB │ gzip: 1.99 kB
+dist/_virtual/_rolldown/runtime.js   0.04 kB │ gzip: 0.06 kB
+dist/prng.js                         1.40 kB │ gzip: 0.73 kB
+dist/browser.js                      1.66 kB │ gzip: 0.69 kB
+dist/encode.js                       1.67 kB │ gzip: 0.82 kB
+dist/index.js                        3.51 kB │ gzip: 1.41 kB
+dist/palette.js                      3.99 kB │ gzip: 1.79 kB
+dist/contrast.js                     4.03 kB │ gzip: 1.90 kB
+dist/background.js                   4.25 kB │ gzip: 1.83 kB
+dist/notch.js                        4.41 kB │ gzip: 1.81 kB
+dist/decoys.js                       4.50 kB │ gzip: 1.93 kB
+dist/compose.js                     10.51 kB │ gzip: 4.01 kB
 
-✓ built in 47ms
+✓ built in 33ms

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # @prosopo/puzzle-assets
 
+## 0.2.0
+### Minor Changes
+
+- f961dab: Store everything needed to redraw a puzzle, so the portal can show the exact challenge a user was served.
+  
+  Until now a puzzle record kept the target, the origin and the accuracy required (`tolerance`), and
+  nothing else. The things that decide what the puzzle actually looked like — how many decoy shapes were
+  scattered on it, how dark they were, how big the piece was, and which background was used — were
+  picked per challenge and then thrown away. So you could see that someone failed by 11px and had no way
+  to know whether they had been handed an easy puzzle or a nasty one.
+  
+  Puzzle records now carry a `render` object with all of it: the difficulty ladder level, the piece size,
+  the frame geometry, the five render settings, and the two 128-bit seeds that regenerate the imagery.
+  Given those, the portal reproduces the background and the piece byte for byte.
+  
+  To make that possible the renderer had to become reproducible. `renderPuzzle` and `createBackground`
+  now take an optional seed and report the one they used, instead of generating one internally and
+  discarding it; the background pool hands out each image together with its seed. Default behaviour is
+  unchanged — omit the seed and you still get a fresh random one.
+  
+  The ladder level is new on the session too (`puzzleLevel`), because it was computed when the puzzle
+  was escalated and never written down anywhere. It is absent when the ladder did not choose the
+  puzzle — a site-configured puzzle or a traffic-filter override has no level.
+  
+  The record is patched after the imagery is produced rather than written with the rest of the record,
+  because the piece size and the seeds only exist once the render has run, and the target has to be
+  durable before it is expressed in pixels. If that patch fails it is logged and ignored: losing a
+  diagnostic must not cost the user their solve. Records written before this change, and any challenge
+  whose render threw, simply have no `render`.
+  
+  **The seeds are secret.** `puzzle-assets/src/prng.ts` explains why: they regenerate the clean
+  background, and a clean background can be diffed against the composite to read the target position
+  straight off. They were previously barred from leaving the provider entirely. They may now sit on the
+  captcha record, and nowhere else — not in a response, not in a log, not on the session. Anything that
+  exposes a puzzle record to a caller has to drop `render.backgroundSeed` and `render.renderSeed`, and
+  must not serve them at all while the challenge is still live. The comment in `prng.ts` now says so.
+  
+  Test coverage. Three guards, each confirmed to fail when the thing it protects is broken:
+  `renderReplay.unit.test.ts` re-renders from the stored fields and asserts the bytes match, with one
+  case per field asserting that changing *only* that field changes the output — so a record missing a
+  field cannot pass; `puzzleRenderer.unit.test.ts` replays through the same entry points the portal would
+  use, which catches a background paired with the wrong seed; and `schemas.test.ts` asserts every
+  sub-field survives a strict-mode mongoose write, since a field absent from the schema is dropped
+  silently and would store nothing at all.
+
+### Patch Changes
+
+- 6e2eb55: Make the puzzle piece look like a puzzle piece, sit apart from the background, and survive colour-blind vision.
+  
+  Three complaints from the Twickets call, all about how the challenge looks.
+  
+  **The silhouette is now always a jigsaw piece.** The generator had five unrelated shape families — jigsaw, circle, rounded rectangle, regular polygon, flower — so four pieces in five were not jigsaw-shaped at all, and a first-time user was as likely to be handed a heptagon as anything recognisable. There is now one grammar: a rounded body where each of the four edges independently gets a tab, a blank or nothing, with the knob's position along its edge, its radius and the corner rounding all varying.
+  
+  Silhouette variety is deliberate anti-automation and it has not been given up — it has moved inside the grammar. 3^4 edge combinations before any of the continuous parameters, against five families with a handful of parameters each, so the space did not shrink; what changed is that every sample in it reads as a piece of a jigsaw. A sweep over 400 seeds finds more than 320 distinct coarse signatures, so there is nothing like a template to match against.
+  
+  The piece is also scaled to fit its bounding box now, measured from the knobs actually drawn, rather than the body being inset by the worst case the parameters could produce. Insetting for the worst case shrinks every piece to make room for the largest tab that was never drawn. A tab reaching the border used to come out clipped flat, which looks like a manufacturing defect rather than a jigsaw tab.
+  
+  **The piece is separated by a luminance step, not by hue.** It is cut from the same mesh the background is drawn from, so on an unlucky palette it was the same colour as whatever it was resting on and the only thing dividing them was a CSS drop-shadow. It now carries an outline whose brightness steps away from its own, in the direction chosen from the piece's own mean luminance — a dark piece gets a light rim, a light piece a dark one. A fixed direction vanishes at one end of the range, which is how a cue that is present in the code ends up absent on screen.
+  
+  The size of the step is solved for per piece to reach a target contrast ratio, not set as a fixed byte offset: 40 units out of 255 is obvious on a mid grey and nearly invisible near white. Being a brightness step rather than a hue, it survives greyscale, a monochrome display, every dichromacy and a phone screen in sunlight — which the tests assert by measuring luminance only, and again after flattening the piece to grey.
+  
+  **Palette generation now has a measured contrast floor.** The six palettes are analogous-hue families, which is what makes a mesh gradient look deliberate and is also the worst case for colour-blind vision: a band of neighbouring hues at one lightness is exactly what a dichromat collapses to a single colour. Nothing checked for that, so a palette could lose all its structure for 1 in 12 men and no test would notice.
+  
+  A new `contrast` module does WCAG relative luminance on linearised sRGB and Viénot–Brettel–Mollon simulation of protanopia, deuteranopia and tritanopia. `drawPalette` now redraws while its widest pair falls below the floor under *any* of the four vision types, widening the lightness band on each retry rather than giving up after N tries — a floor that can be returned past is not a floor. The first attempts are unstretched, so an ordinary draw is exactly what it was before and only a failing palette gets touched.
+  
+  The floor is on the palette's *range*, not on every pair: a gradient needs near-neighbours, and demanding contrast between them would produce stripes. What it rules out is a field that is uniformly one brightness.
+  
+  **Tests sweep seeds rather than checking an example.** 45 tests, including 400-seed sweeps of the palette floor, the presence of tabs, silhouette variety, the bounding box, and the area covered; and 120-seed sweeps of the rim's luminance step, its direction, its survival in greyscale, and its survival under each dichromacy. A palette or parameter that is fine on the one seed somebody happened to look at and unreadable on a tenth of the rest is the failure that shipped, and a single-seed test cannot see it.
+  
+  One thing the tests could not see, found by rendering the output and looking at it: a fixed 4px rim is a tidy outline on a large piece and most of the surface area of a 44px one — the default — so the whole piece read as a pale blob rather than as a piece with a lit edge. No measurement of rim-versus-core contrast catches that, because by that measure a piece which is entirely rim scores perfectly. The rim is now proportional to the piece size, and the tests read the band geometry from the renderer so the measurement cannot drift away from what was drawn.
+
 ## 0.1.4
 ### Patch Changes
 

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2022 PROSOPO LIMITED
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser.d.ts

@@ -9,7 +9,8 @@ export interface RenderedPuzzleRgba {
     background: RgbaImage;
     piece: RgbaImage;
     pieceSize: number;
+    seed: Buffer;
 }
-export declare const renderPuzzleToRgba: (background: RgbaImage, placement: NotchPlacement, geometry?: PuzzleGeometry, settings?: PuzzleRenderSettings) => RenderedPuzzleRgba;
-export declare const createBackground: (geometry?: PuzzleGeometry) => RgbaImage;
+export declare const renderPuzzleToRgba: (background: RgbaImage, placement: NotchPlacement, geometry?: PuzzleGeometry, settings?: PuzzleRenderSettings, seed?: Buffer) => RenderedPuzzleRgba;
+export declare const createBackground: (geometry?: PuzzleGeometry, seed?: Buffer) => RgbaImage;
 //# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EACX,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,SAAS,EACT,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC3D,YAAY,EACX,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,SAAS,GACT,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,gBAAgB,EAAE,cAI9B,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,oBAMrC,CAAC;AAEF,MAAM,WAAW,kBAAkB;IAClC,UAAU,EAAE,SAAS,CAAC;IACtB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CAClB;AAOD,eAAO,MAAM,kBAAkB,eAClB,SAAS,aACV,cAAc,aACf,cAAc,aACd,oBAAoB,KAC5B,kBAuBF,CAAC;AAEF,eAAO,MAAM,gBAAgB,cAClB,cAAc,KACtB,SAC2E,CAAC"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EACX,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,SAAS,EACT,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC3D,YAAY,EACX,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,SAAS,GACT,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,gBAAgB,EAAE,cAI9B,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,oBAMrC,CAAC;AAEF,MAAM,WAAW,kBAAkB;IAClC,UAAU,EAAE,SAAS,CAAC;IACtB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAElB,IAAI,EAAE,MAAM,CAAC;CACb;AAOD,eAAO,MAAM,kBAAkB,eAClB,SAAS,aACV,cAAc,aACf,cAAc,aACd,oBAAoB,SACxB,MAAM,KACV,kBAuBF,CAAC;AAEF,eAAO,MAAM,gBAAgB,cAClB,cAAc,SAClB,MAAM,KACV,SACmE,CAAC"}

package/dist/browser.js

@@ -22,17 +22,18 @@ var DEFAULT_RENDER_SETTINGS = {
 * than WebP-encoded buffers, so browser consumers can `putImageData` onto
 * a canvas without needing sharp.
 */
-var renderPuzzleToRgba = (background, placement, geometry = DEFAULT_GEOMETRY, settings = DEFAULT_RENDER_SETTINGS) => {
-	const prng = createPrng(createSeed());
+var renderPuzzleToRgba = (background, placement, geometry = DEFAULT_GEOMETRY, settings = DEFAULT_RENDER_SETTINGS, seed = createSeed()) => {
+	const prng = createPrng(seed);
 	const pieceSize = geometry.pieceSize ?? geometry.notchSize;
 	paintDecoys(background, prng, settings.decoyCount, pieceSize, placement, settings.decoyEdgeDarkness, settings.decoyBodyBrightness, settings.decoyHoleDarken);
 	const { background: cut, piece } = cutNotch(prng, background, createNotchShape(prng, pieceSize), pieceSize, placement, settings.holeDarken);
 	return {
 		background: cut,
 		piece,
-		pieceSize
+		pieceSize,
+		seed
 	};
 };
-var createBackground = (geometry = DEFAULT_GEOMETRY) => generateBackground(createPrng(createSeed()), geometry.width, geometry.height);
+var createBackground = (geometry = DEFAULT_GEOMETRY, seed = createSeed()) => generateBackground(createPrng(seed), geometry.width, geometry.height);
 //#endregion
 export { DEFAULT_GEOMETRY, DEFAULT_RENDER_SETTINGS, SEED_BYTES, createBackground, createPrng, createSeed, generateBackground, paintDecoyPiece, paintDecoys, renderPuzzleToRgba };

package/dist/browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAQnD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAS3D,MAAM,CAAC,MAAM,gBAAgB,GAAmB;IAC/C,KAAK,EAAE,GAAG;IACV,MAAM,EAAE,GAAG;IACX,SAAS,EAAE,EAAE;CACb,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAyB;IAC5D,UAAU,EAAE,CAAC;IACb,iBAAiB,EAAE,EAAE;IACrB,mBAAmB,EAAE,CAAC;IACtB,UAAU,EAAE,IAAI;IAChB,eAAe,EAAE,GAAG;CACpB,CAAC;AAaF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CACjC,UAAqB,EACrB,SAAyB,EACzB,WAA2B,gBAAgB,EAC3C,WAAiC,uBAAuB,EACnC,EAAE;IACvB,MAAM,IAAI,GAAG,UAAU,CAAC,UAAU,EAAE,CAAC,CAAC;IACtC,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS,CAAC;IAC3D,WAAW,CACV,UAAU,EACV,IAAI,EACJ,QAAQ,CAAC,UAAU,EACnB,SAAS,EACT,SAAS,EACT,QAAQ,CAAC,iBAAiB,EAC1B,QAAQ,CAAC,mBAAmB,EAC5B,QAAQ,CAAC,eAAe,CACxB,CAAC;IACF,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAChD,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,QAAQ,CAC1C,IAAI,EACJ,UAAU,EACV,KAAK,EACL,SAAS,EACT,SAAS,EACT,QAAQ,CAAC,UAAU,CACnB,CAAC;IACF,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAC9C,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC/B,WAA2B,gBAAgB,EAC/B,EAAE,CACd,kBAAkB,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAQnD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAS3D,MAAM,CAAC,MAAM,gBAAgB,GAAmB;IAC/C,KAAK,EAAE,GAAG;IACV,MAAM,EAAE,GAAG;IACX,SAAS,EAAE,EAAE;CACb,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAyB;IAC5D,UAAU,EAAE,CAAC;IACb,iBAAiB,EAAE,EAAE;IACrB,mBAAmB,EAAE,CAAC;IACtB,UAAU,EAAE,IAAI;IAChB,eAAe,EAAE,GAAG;CACpB,CAAC;AAeF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CACjC,UAAqB,EACrB,SAAyB,EACzB,WAA2B,gBAAgB,EAC3C,WAAiC,uBAAuB,EACxD,OAAe,UAAU,EAAE,EACN,EAAE;IACvB,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS,CAAC;IAC3D,WAAW,CACV,UAAU,EACV,IAAI,EACJ,QAAQ,CAAC,UAAU,EACnB,SAAS,EACT,SAAS,EACT,QAAQ,CAAC,iBAAiB,EAC1B,QAAQ,CAAC,mBAAmB,EAC5B,QAAQ,CAAC,eAAe,CACxB,CAAC;IACF,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAChD,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,QAAQ,CAC1C,IAAI,EACJ,UAAU,EACV,KAAK,EACL,SAAS,EACT,SAAS,EACT,QAAQ,CAAC,UAAU,CACnB,CAAC;IACF,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AACpD,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC/B,WAA2B,gBAAgB,EAC3C,OAAe,UAAU,EAAE,EACf,EAAE,CACd,kBAAkB,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC"}

package/dist/cjs/compose.cjs

@@ -1,3 +1,4 @@
+const require_contrast = require("./contrast.cjs");
 const require_notch = require("./notch.cjs");
 //#region src/compose.ts
 /**
@@ -39,6 +40,74 @@ var HOLE_INNER_SHADOW = .45;
 * against the darkened cutout it drops into.
 */
 var PIECE_EDGE_LIGHT = 8;
+/**
+* The piece's outline, measured inwards from the silhouette, as a fraction of
+* the piece's size.
+*
+* Full strength out to `PLATEAU`, then tapering to nothing by `WIDTH`. A rim that
+* tapers from the very first pixel has its strongest values exactly where
+* anti-aliasing makes the pixels partly transparent, so the part of it that is
+* fully opaque is only ever half strength — the cue measures far weaker than the
+* number configuring it suggests. The plateau puts the full step on pixels that
+* are actually opaque, and the taper then stops it ending in a hard line.
+*
+* PROPORTIONAL, NOT A FIXED PIXEL COUNT. A 4px band is a tidy outline on a
+* 120px piece and most of the surface area of a 44px one — the default
+* `notchSize` — which made the whole piece read as a pale blob rather than as a
+* piece with a lit edge. Caught by rendering it and looking; no measurement of
+* rim-versus-core contrast can see it, because by that measure a piece that is
+* entirely rim scores perfectly.
+*/
+var PIECE_RIM_PLATEAU_RATIO = .03;
+var PIECE_RIM_WIDTH_RATIO = .065;
+/** Floors, so the rim does not vanish on a very small piece. */
+var PIECE_RIM_MIN_PLATEAU = 1;
+var PIECE_RIM_MIN_WIDTH = 2.2;
+/** Rim geometry for a piece of `size` px. Exported so tests measure the band the renderer actually drew. */
+var pieceRimGeometry = (size) => {
+	const plateau = Math.max(PIECE_RIM_MIN_PLATEAU, size * PIECE_RIM_PLATEAU_RATIO);
+	return {
+		plateau,
+		width: Math.max(PIECE_RIM_MIN_WIDTH, size * PIECE_RIM_WIDTH_RATIO, plateau + 1)
+	};
+};
+/**
+* The WCAG contrast ratio the rim aims to reach against the piece's own body.
+*
+* This is the separation cue, and it is deliberately not a hue. The piece is cut
+* from the same mesh the background is drawn from, so on an unlucky palette it
+* was the same colour as whatever it was resting on and the only thing dividing
+* them was a CSS drop-shadow. A luminance step survives what hue does not:
+* greyscale, a monochrome display, every dichromacy, and a phone screen in
+* sunlight.
+*
+* Expressed as a ratio rather than as a fixed byte offset because a fixed offset
+* is not a fixed cue: 40 units out of 255 is obvious on a mid grey and almost
+* invisible near white, where the same step is a much smaller fraction of the
+* luminance. The required offset is solved for per piece from the luminance it
+* actually has.
+*
+* 1.5 is comfortably visible without reading as a drawn border. The tests assert
+* a lower bound than this, because the taper and the per-pixel noise cost a
+* little of it.
+*/
+var PIECE_RIM_TARGET_CONTRAST = 1.5;
+/**
+* Cap on the rim offset, in 0-255 units. Past roughly this the rim stops reading
+* as a lit or shaded edge and starts reading as a stroke drawn around a sticker,
+* which is the look this is trying to avoid.
+*/
+var PIECE_RIM_MAX_STEP = 72;
+/**
+* Above this relative luminance the piece is treated as light, and gets a dark
+* rim rather than a light one.
+*
+* Picking the direction from the piece's own mean rather than fixing it is the
+* whole point: a fixed light rim vanishes on a pale background and a fixed dark
+* one vanishes on a dark background, which is how a cue that is present in the
+* code ends up absent on screen.
+*/
+var PIECE_RIM_DIRECTION_THRESHOLD = .4;
 var clamp255 = (v) => v < 0 ? 0 : v > 255 ? 255 : v;
 /**
 * Sample the background at `(x, y)`. Returns `null` when the coordinate
@@ -56,6 +125,49 @@ var sampleBackground = (image, x, y) => {
 	];
 };
 /**
+* Rim strength in [0, 1] for a signed distance: 1 on the plateau, tapering to 0
+* at the full width inside the silhouette, 0 beyond it.
+*/
+var rimProfile = (d, plateau, width) => {
+	if (d <= -width) return 0;
+	if (d >= -plateau) return 1;
+	return (d + width) / (width - plateau);
+};
+/** Approximate sRGB byte for a relative luminance. */
+var byteForLuminance = (luminance) => 255 * Math.max(0, Math.min(1, luminance)) ** (1 / 2.2);
+/**
+* The signed offset, in 0-255 units, to apply at the piece's rim.
+*
+* Averages the luminance of the pixels the piece will be cut from, picks the
+* direction that steps *away* from it, then solves for the offset that reaches
+* [`PIECE_RIM_TARGET_CONTRAST`] against it. A dark piece gets a light rim and a
+* light piece a dark one, so the cue is present whatever the palette produced —
+* which neither a fixed direction nor a fixed magnitude can promise.
+*/
+var pieceRimDelta = (background, shape, size, left, top) => {
+	let total = 0;
+	let counted = 0;
+	for (let ly = 0; ly < size; ly += 4) for (let lx = 0; lx < size; lx += 4) {
+		if (require_notch.coverageFromDistance(shape.distance(lx, ly)) <= 0) continue;
+		const sample = sampleBackground(background, left + lx, top + ly);
+		if (sample === null) continue;
+		total += require_contrast.relativeLuminance({
+			r: sample[0],
+			g: sample[1],
+			b: sample[2]
+		});
+		counted++;
+	}
+	if (counted === 0) return PIECE_RIM_MAX_STEP;
+	const pieceLuminance = total / counted;
+	const lighten = pieceLuminance <= PIECE_RIM_DIRECTION_THRESHOLD;
+	const delta = byteForLuminance(lighten ? PIECE_RIM_TARGET_CONTRAST * (pieceLuminance + .05) - .05 : (pieceLuminance + .05) / PIECE_RIM_TARGET_CONTRAST - .05) - byteForLuminance(pieceLuminance);
+	const capped = Math.max(-PIECE_RIM_MAX_STEP, Math.min(PIECE_RIM_MAX_STEP, delta));
+	const floor = 24;
+	if (Math.abs(capped) < floor) return lighten ? floor : -24;
+	return capped;
+};
+/**
 * Cut the notch out of `background` and produce the matching piece.
 *
 * `background` is mutated in place — it is a freshly generated, single-use
@@ -67,6 +179,8 @@ var cutNotch = (prng, background, shape, size, placement, holeDarken) => {
 	const top = Math.round(placement.targetY - half);
 	const pieceData = Buffer.alloc(size * size * 4);
 	const brightness = prng.range(PIECE_BRIGHTNESS_RANGE[0], PIECE_BRIGHTNESS_RANGE[1]);
+	const rimStep = pieceRimDelta(background, shape, size, left, top);
+	const rim = pieceRimGeometry(size);
 	for (let ly = 0; ly < size; ly++) for (let lx = 0; lx < size; lx++) {
 		const d = shape.distance(lx, ly);
 		const coverage = require_notch.coverageFromDistance(d);
@@ -82,8 +196,9 @@ var cutNotch = (prng, background, shape, size, placement, holeDarken) => {
 		}
 		const [r, g, b] = sample;
 		const edgeLight = d > -2 ? PIECE_EDGE_LIGHT * (1 + d / 2) : 0;
+		const rimDelta = rimStep * rimProfile(d, rim.plateau, rim.width);
 		const noise = (prng.next() - .5) * 2 * PIECE_NOISE;
-		const delta = brightness + edgeLight + noise;
+		const delta = brightness + edgeLight + rimDelta + noise;
 		pieceData[pi] = clamp255(Math.round(r + delta));
 		pieceData[pi + 1] = clamp255(Math.round(g + delta));
 		pieceData[pi + 2] = clamp255(Math.round(b + delta));
@@ -124,3 +239,4 @@ var cutNotch = (prng, background, shape, size, placement, holeDarken) => {
 };
 //#endregion
 exports.cutNotch = cutNotch;
+exports.pieceRimGeometry = pieceRimGeometry;