docs: fix relative path images not appearing by lucbic · Pull Request #2167 · superdoc-dev/superdoc

lucbic · 2026-02-24T22:36:49Z

sanitizeHref previously rejected all relative paths, which broke image rendering in docs widgets that use paths like /public/images/photo.png.

Instead of rejecting, relative paths are now resolved against the page origin with security enforcement: control character rejection, same-origin gate, and redirect blocklist support. This also skips the destructive image registration pipeline for relative-path images since the browser resolves them directly.

Refs: #2155

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: db54c3bb42

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

packages/super-editor/src/extensions/image/imageHelpers/imageRegistrationPlugin.js

caio-pizzol

thanks for the contribution, @lucbic! the approach is solid and the code is clean. left one inline comment — it's a blocking bug since the tests contradict the current behavior at line 526.

shared/url-validation/index.js

caio-pizzol · 2026-02-27T14:34:35Z

p.s. also rebase with main looks like all tests are failing here

caio-pizzol

@lucbic dot-relative fix looks good. left one inline note about a bare-path edge case — not blocking.

packages/super-editor/src/extensions/image/imageHelpers/imageRegistrationPlugin.js

caio-pizzol

@lucbic approach looks good, clean structure.

one thing to check — relative paths like ./photo.png resolve from the site root instead of the current page. small fix inline.

also a question about whether skipping relative images in the browser path affects export.

one minor cleanup on the origin comparison. test coverage looks solid.

left inline comments.

shared/url-validation/index.js

packages/super-editor/src/extensions/image/imageHelpers/imageRegistrationPlugin.js

caio-pizzol

@lucbic prior feedback addressed, nice. tested locally on the docs site — images show up and export works.

two small things inline. nothing blocking. feel free to merge after addressing those last comments.

on tests: we only have unit tests for this. would be good to also have:

a behavior test: open a doc with relative image paths, export to DOCX, check images are in the file
more unit tests: (1) inserting the same image twice while the first is still loading, (2) what happens when the image can't be fetched, (3) checking exact fallback size values instead of just "truthy"

packages/super-editor/src/extensions/image/imageHelpers/imageRegistrationPlugin.js

sanitizeHref previously rejected all relative paths, which broke image rendering in docs widgets that use paths like /public/images/photo.png. Instead of rejecting, relative paths are now resolved against the page origin with security enforcement: control character rejection, same-origin gate, and redirect blocklist support. This also skips the destructive image registration pipeline for relative-path images since the browser resolves them directly.

…zeHref Extend relative path detection to include paths starting with '.' (e.g., './image.png') in addition to '/' to properly handle relative imports in document processors.

…e paths - Add isRelativeUrl() helper using negation-based scheme detection for robustness - Support bare relative paths (e.g., images/photo.png) in sanitizeHref - Add comprehensive tests for isRelativeUrl() covering all path types - Add tests for bare path resolution in browser context

- Replace inline isRelativePath with imported isRelativeUrl from @superdoc/url-validation - Ensures consistent relative URL detection across codebase - Supports bare paths like images/photo.png

…directory Use window.location.href instead of window.location.origin so that relative paths like ./images/chart.jpg resolve against the current page directory rather than the site root.

Add registerRelativeImages to fetch binary data in the background for relative-path images (./photo.png, /public/images/img.png) so they can be included in DOCX exports. Skip re-registration for relative URLs that already have an rId.

Images with an empty attrs.size object (e.g. from HTML imports) caused pixelsToEmu(undefined) producing invalid wp:extent elements, which corrupted the exported DOCX. Check for explicit width/height values and fall back to default dimensions when missing.

Migrate the module-scoped Set to editor.storage.image to scope it per editor instance. Prevents duplicate relative URL registration when multiple editors exist on the same page.

Verifies that relative-URL images are fetched asynchronously and embedded in DOCX exports via registerRelativeImages. The test validates: - Image node receives rId after async registration - Exported DOCX contains image in word/media/ - PNG binary integrity is preserved - Relationships XML and document XML reference the image correctly Adds jszip dev dependency to parse and inspect exported DOCX.

Add three test cases for relative URL image registration: - Duplicate relative URLs: Verify that when two images with the same relative src arrive during loading, urlToFile is only called once due to pendingRelativeRegistrations deduplication guard. - Fetch failure: Verify that when urlToFile returns null (network error, 404, etc.), no media store entry or rId is created, and no transaction is dispatched. - Exact fallback size values: Update the existing fallback size test to assert exact EMU values (300×200 px fallback) instead of just truthy, catching regressions if defaults are changed. Follows Conventional Commits style per CONTRIBUTING.md guidelines.

lucbic · 2026-03-06T01:17:18Z

@caio-pizzol all done! I have changed the approach for registering the pendingRelativeRegistrations, now it's using the instance storage, so I guess it would be nice if you could take a look again.

I have also rebased from main and solved a few conflicts. A Few tests are failing, but they are unrelated to the changes in this branch

caio-pizzol

@lucbic previous feedback all addressed, nice. two small inline comments — an edge case with duplicate images missing from export, and a helper reuse. tests look good.

caio-pizzol · 2026-03-18T21:58:23Z

packages/super-editor/src/extensions/image/imageHelpers/imageRegistrationPlugin.js

+  for (const { node } of images) {
+    const src = node.attrs.src;
+
+    if (pendingRelativeRegistrations.has(src)) continue;


if the same image gets inserted twice quickly, the second copy can end up without export data — it'll be missing from the DOCX. editing near it fixes it, but that's easy to miss. worth a fix or TODO?

caio-pizzol · 2026-03-18T21:58:23Z

packages/super-editor/src/extensions/image/imageHelpers/imageRegistrationPlugin.js

+    pendingRelativeRegistrations.add(src);
+
+    try {
+      const filename = src.split('/').pop()?.split(/[?#]/)[0] || 'image.bin';


derivePreferredFileName (line 125) already does this.

Suggested change

const filename = src.split('/').pop()?.split(/[?#]/)[0] || 'image.bin';

const filename = derivePreferredFileName(src);

chatgpt-codex-connector bot reviewed Feb 24, 2026

View reviewed changes

packages/super-editor/src/extensions/image/imageHelpers/imageRegistrationPlugin.js Outdated Show resolved Hide resolved

caio-pizzol added the community label Feb 27, 2026

caio-pizzol reviewed Feb 27, 2026

View reviewed changes

shared/url-validation/index.js Outdated Show resolved Hide resolved

caio-pizzol assigned lucbic Feb 27, 2026

lucbic force-pushed the docs/fix-relative-path-images branch from ed83de7 to 1763e56 Compare February 27, 2026 20:58

caio-pizzol reviewed Feb 28, 2026

View reviewed changes

packages/super-editor/src/extensions/image/imageHelpers/imageRegistrationPlugin.js Show resolved Hide resolved

caio-pizzol linked an issue Mar 2, 2026 that may be closed by this pull request

Docs: Images not appearing in the Image and Node Resizer extension pages #2155

Open

github-actions bot added the risk: critical label Mar 2, 2026

lucbic force-pushed the docs/fix-relative-path-images branch from 02b2314 to 816a368 Compare March 2, 2026 19:45

lucbic requested a review from caio-pizzol March 2, 2026 20:19

caio-pizzol reviewed Mar 3, 2026

View reviewed changes

shared/url-validation/index.js Outdated Show resolved Hide resolved

shared/url-validation/index.js Outdated Show resolved Hide resolved

packages/super-editor/src/extensions/image/imageHelpers/imageRegistrationPlugin.js Show resolved Hide resolved

caio-pizzol approved these changes Mar 5, 2026

View reviewed changes

packages/super-editor/src/extensions/image/imageHelpers/imageRegistrationPlugin.js Outdated Show resolved Hide resolved

packages/super-editor/src/extensions/image/imageHelpers/imageRegistrationPlugin.js Outdated Show resolved Hide resolved

lucbic added 14 commits March 5, 2026 21:33

fix: relative path image registration bypass breaking headless mode

4e58d1e

fix(url-validation): allow relative paths starting with dot in saniti…

1cd5029

…zeHref Extend relative path detection to include paths starting with '.' (e.g., './image.png') in addition to '/' to properly handle relative imports in document processors.

refactor(image): use shared isRelativeUrl helper

ea884fb

- Replace inline isRelativePath with imported isRelativeUrl from @superdoc/url-validation - Ensures consistent relative URL detection across codebase - Supports bare paths like images/photo.png

fix(url-validation): resolve dot-relative paths against current page …

1488081

…directory Use window.location.href instead of window.location.origin so that relative paths like ./images/chart.jpg resolve against the current page directory rather than the site root.

refactor(image): extract shared media-store initialization helper

9f6996c

refactor(image): move pendingRelativeRegistrations to per-editor storage

58e72d3

Migrate the module-scoped Set to editor.storage.image to scope it per editor instance. Prevents duplicate relative URL registration when multiple editors exist on the same page.

test(image): add pendingRelativeRegistrations to mock editor storage

bab2015

test(behavior): add test image asset for relative image export test

93290f8

lucbic force-pushed the docs/fix-relative-path-images branch from 2a9986b to 71430ed Compare March 6, 2026 00:56

caio-pizzol reviewed Mar 18, 2026

View reviewed changes

	const filename = src.split('/').pop()?.split(/[?#]/)[0] \|\| 'image.bin';
	const filename = derivePreferredFileName(src);

Conversation

lucbic commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

caio-pizzol left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

caio-pizzol commented Feb 27, 2026

Uh oh!

caio-pizzol left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

caio-pizzol left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

caio-pizzol left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

lucbic commented Mar 6, 2026

Uh oh!

caio-pizzol left a comment

Choose a reason for hiding this comment

Uh oh!

caio-pizzol Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

caio-pizzol Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lucbic commented Feb 24, 2026 •

edited

Loading

caio-pizzol left a comment •

edited

Loading