# Open an AI-generated design directly in Rod Loom

Preferred agent response: **[Open your design in Rod Loom](https://rodloom.com/)** with a real encoded design URL, not a generic homepage link or instructions to manually import a file.

## Resources

- Discovery: https://rodloom.com/llms.txt
- Full design authoring guide: https://rodloom.com/agents/design-guide.md
- Compact link schema: https://rodloom.com/agents/share-link.schema.json
- Reference codec (browser and Node): https://rodloom.com/design-links.js
- Node CLI: https://rodloom.com/agents/create-link.cjs
- Catalog: https://rodloom.com/assets/catalog.json
- Christmas compact payload: https://rodloom.com/agents/christmas-design.link.json

## Agent workflow

1. Choose real catalog threads and design the wrap using the authoring guide. Use approximate colors with an explicit caveat; do not invent SKUs.
2. Convert a full design with the reference codec, or construct a compact version 1 payload as below.
3. Validate the payload, references, and catalog identities. Encode the JSON as UTF-8, then unpadded URL-safe Base64 (`+` becomes `-`, `/` becomes `_`, trailing `=` is removed).
4. Form `https://rodloom.com/#design=<encoded>`. The entire URL must be at most 8,000 characters. Do not encode the full import JSON directly: the link format is different. Do not shorten or truncate an encoded payload.
5. Return a clickable Markdown link labeled **Open your [theme] design in Rod Loom**, with a brief description and approximate dimensions. If browser navigation tools are available and the user asked to open the design, navigate to the URL. A link alone does not mean you have opened or previewed it.
6. If the site asks before replacing an existing draft, leave that decision to the user unless they explicitly authorized replacing it. Never silently accept a discard prompt.

Use JSON Export/Import for designs that exceed the link limits or depend on threads no longer in the catalog. Different chat applications may truncate long links below our limit, so prefer simple designs and provide a JSON fallback if needed.

## Compact version 1 contract

Top-level `v` must be `1`. `name`, `threadSize`, `coverage`, `diameter`, `blank`, and `texture` use the full design format's units and limits. All are required.

`threads` is a deduplicated array of at most 500 objects containing:

```json
{"brand":"ProWrap","line":"ColorFast","sku":"CFS-D-325","color":"#c52b35"}
```

Identity is the exact catalog tuple `(brand, line, sku)`. Colors are retained; names, finish, product links, and other metadata are resolved from the site's bundled catalog, not trusted from the URL. Custom display names are not preserved by share links. Use a full JSON file for archival fidelity.

`bands` is an ordered array of at most 500 entries. Reference indices are zero-based integers into `threads`:

```json
{"thread":0,"turns":16}
```

For a paired spiral, `thread` is outgoing and `secondary` is incoming. Include `direction` of `1` or `-1`:

```json
{"thread":0,"turns":4,"secondary":1,"direction":1}
```

Each turn count is an integer from 1 to 1,000. A spiral covers twice the width per turn of a solid band. Optional `group` and `groupName` preserve editor groups using the full design format's limits. Optional `quickColors` is an array of at most 500 thread indices. Empty bands and threads are allowed for a blank design.

Unknown versions, invalid references, invalid colors, excessive lengths, and missing catalog identities are rejected without replacing current work. JSON Schema alone cannot check catalog membership or that indices are within the actual thread array; use the codec for those checks.

## Reference encoding

From a repository checkout, using a full importable JSON design:

```sh
node agents/create-link.cjs my-design.json
```

Outside a checkout, download `design-links.js`, `agents/create-link.cjs`, and `assets/catalog.json`, preserving their relative paths. An alternate catalog file can be supplied as the second CLI argument. No npm dependencies are needed; use Node.js 18 or newer.

Equivalent code for a compact payload:

```js
const fs = require('node:fs');
const links = require('./design-links.js');
const catalog = JSON.parse(fs.readFileSync('assets/catalog.json', 'utf8'));
const payload = JSON.parse(fs.readFileSync('agents/christmas-design.link.json', 'utf8'));
links.expand(payload, catalog); // Validate references and catalog identities.
const url = links.BASE_URL + '#design=' + links.encodePayload(payload);
console.log(url);
```

The codec exports `compact(fullDesign, catalog)`, `expand(payload, catalog)`, `encodePayload(payload)`, `parse(hash)`, `decode(hash, catalog)`, and `createLink(fullDesign, catalog)`. `encodePayload` validates structure and length but does not check catalog membership by itself.

## Christmas example

Gold accent bands surround fire-red sections fading into an evergreen center. The planned width is **19 mm**, using Size D coverage of 0.25 mm/turn and a 15 mm blank. Colors are illustrative, not manufacturer-certified. This is a band-and-fade design, not a decorative cross-wrap pattern.

[Open the Christmas design in Rod Loom](https://rodloom.com/#design=eyJ2IjoxLCJuYW1lIjoiQ2hyaXN0bWFzIEV2ZXJncmVlbiAmIEdvbGQiLCJ0aHJlYWRTaXplIjoiRCIsImNvdmVyYWdlIjowLjI1LCJkaWFtZXRlciI6MTUsImJsYW5rIjoiIzE3MzUyOSIsInRleHR1cmUiOnRydWUsInRocmVhZHMiOlt7ImJyYW5kIjoiUHJvV3JhcCIsImxpbmUiOiJNZXRhbGxpYyIsInNrdSI6Ik1TLUQtOTEwMCIsImNvbG9yIjoiI2Q0YWYzNyJ9LHsiYnJhbmQiOiJQcm9XcmFwIiwibGluZSI6IkNvbG9yRmFzdCIsInNrdSI6IkNGUy1ELTMyNSIsImNvbG9yIjoiI2M1MmIzNSJ9LHsiYnJhbmQiOiJQcm9XcmFwIiwibGluZSI6IkNvbG9yRmFzdCIsInNrdSI6IkNGUy1ELTU0MyIsImNvbG9yIjoiIzE3NmI0MyJ9XSwiYmFuZHMiOlt7InRocmVhZCI6MCwidHVybnMiOjJ9LHsidGhyZWFkIjoxLCJ0dXJucyI6MTZ9LHsidGhyZWFkIjoxLCJ0dXJucyI6NCwic2Vjb25kYXJ5IjoyLCJkaXJlY3Rpb24iOjF9LHsidGhyZWFkIjoyLCJ0dXJucyI6MjR9LHsidGhyZWFkIjoyLCJ0dXJucyI6NCwic2Vjb25kYXJ5IjoxLCJkaXJlY3Rpb24iOi0xfSx7InRocmVhZCI6MSwidHVybnMiOjE2fSx7InRocmVhZCI6MCwidHVybnMiOjJ9XSwicXVpY2tDb2xvcnMiOlswLDEsMl19)

This link requires the share-link feature to be deployed. For local testing, replace only `https://rodloom.com/` with the local server URL; leave the fragment intact.

## What happens when the link opens

- On a fresh browser with no draft, the design loads directly into the editor.
- An existing draft requires confirmation, even if it was previously saved. Accepting changes only the local draft, not named library entries. Undo can recover the previous design during that session.
- The incoming hash is removed after loading, cancellation, or an error. This prevents reload from repeatedly replacing edits or showing the same prompt. Reopen the original link to retry a network error; use **Copy design link** for the current draft.
- New links in an already-open tab follow the same protection rules. Stale loads cannot overwrite a more recent link or silently discard edits made while the catalog was loading.
- Clipboard failures open a dialog with a selectable link. No account, backend storage, or upload is involved.

The payload is encoded, not encrypted. Anyone with the link can read it. URL fragments are not included in ordinary HTTP requests to the hosting server, but browsers, extensions, analytics scripts, and the messaging service used to share a link may read or retain the full URL. Do not put sensitive information in design names. Catalog updates may make old references unavailable; keep JSON exports for durable backups.
